> ## Documentation Index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Vectors

> Queries the approximate nearest neighbors of a vector.

<Tip>
  Query will run against the default namespace by default.
  You can use a different namespace by specifying it in the request path.
</Tip>

## Request

It is also possible to send a batch query request by providing an array
of fields below.

<ParamField body="vector" name="vector" type="number[]" required>
  The query vector
  <Note>The query vector should have the same dimensions as your index.</Note>
</ParamField>

<ParamField body="topK" type="number" default="10">
  The total number of the vectors that you want to receive as a query
  result. The response will be sorted based on the distance metric score,
  and at most `topK` many vectors will be returned.
</ParamField>

<ParamField body="includeMetadata" type="boolean" default="false">
  Whether to include the metadata of the vectors in the response, if any.
  It is recommended to set this to `true` to easily identify vectors.
</ParamField>

<ParamField body="includeVectors" type="boolean" default="false">
  Whether to include the vector values in the response.
  It is recommended to set this to `false` as the vector values can be
  quite big, and not needed most of the time.
</ParamField>

<ParamField body="includeData" type="boolean" default="false">
  Whether to include the data of the vectors in the response, if any.
</ParamField>

<ParamField body="filter" type="string" default="">
  [Metadata filter](/vector/features/filtering) to apply.
</ParamField>

<ParamField body="weightingStrategy" type="string">
  For sparse vectors of sparse and hybrid indexes, specifies what kind of
  weighting strategy should be used while querying the matching non-zero
  dimension values of the query vector with the documents.

  If not provided, no weighting will be used.

  Only possible value is `IDF` (inverse document frequency).
</ParamField>

<ParamField body="fusionAlgorithm" type="string">
  Fusion algorithm to use while fusing scores
  from dense and sparse components of a hybrid index.

  If not provided, defaults to `RRF` (Reciprocal Rank Fusion).

  Other possible value is `DBSF` (Distribution-Based Score Fusion).
</ParamField>

## Path

<ParamField path="namespace" type="string" default="">
  The namespace to use.
  When no namespace is specified, the default namespace will be used.
</ParamField>

## Response

If the request was an array of a single element, or a JSON object,
an object with the following fields is returned.

If the request was an array of more than one items, an array of
objects below is returned, one for each query item.

<Note>
  For dense indexes, the score is normalized to always be between 0 and 1.
  The closer the score is to 1, the more similar the vector is to the query vector.
  This does not depend on the distance metric you use.

  For sparse and hybrid indexes, scores can be arbitrary values, but the score
  will be higher for more similar vectors.
</Note>

<ResponseField name="Scores" type="Object[]">
  <Expandable defaultOpen="true">
    <ResponseField name="id" type="string" required>
      The id of the vector.
    </ResponseField>

    <ResponseField name="score" type="number" required>
      The similarity score of the vector, calculated based on the distance metric of your index.
    </ResponseField>

    <ResponseField name="vector" type="number[]">
      The dense vector value for dense and hybrid indexes.
    </ResponseField>

    <ResponseField name="sparseVector" type="Object[]">
      The sparse vector value for sparse and hybrid indexes.

      <Expandable defaultOpen="true">
        <ResponseField name="indices" type="number[]">
          Indices of the non-zero valued dimensions.
        </ResponseField>

        <ResponseField name="values" type="number[]">
          Values of the non-zero valued dimensions.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="metadata" type="Object">
      The metadata of the vector, if any.
    </ResponseField>

    <ResponseField name="data" type="string">
      The unstructured data of the vector, if any.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```sh curl theme={"system"}
  curl $UPSTASH_VECTOR_REST_URL/query \
    -X POST \
    -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
    -d '{ "vector": [0.1, 0.2], "topK": 2, "includeMetadata": true }'
  ```

  ```sh curl (Namespace) theme={"system"}
  curl $UPSTASH_VECTOR_REST_URL/query/ns \
    -X POST \
    -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
    -d '{ "vector": [0.1, 0.2], "topK": 2, "includeMetadata": true }'
  ```

  ```sh curl (Batch Query) theme={"system"}
  curl "$UPSTASH_VECTOR_REST_URL/query" \
    -X POST \
    -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
    -d '[
          {
            "vector": [0.1, 0.2],
            "topK": 2,
            "includeMetadata": true
          },
          {
            "vector": [0.2, 0.3],
            "topK": 3
          }
        ]'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"system"}
  {
      "result": [
          {
              "id": "id-0",
              "score": 1.0,
              "metadata": {
                  "link": "upstash.com"
              }
          },
          {
              "id": "id-1",
              "score": 0.99996454
          }
      ]
  }
  ```
</ResponseExample>