> ## 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 Data

> Queries the approximate nearest neighbors of a raw text data after embedding it.

<Warning>
  To use this endpoint, the index must be created with an [embedding model](/vector/features/embeddingmodels).
</Warning>

<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="data" name="data" type="string" required>
  The raw text data to embed and query.
</ParamField>

<ParamField body="topK" type="number" required 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.
  When set to true, data will contain the raw text data used
  while upserting.
</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>

<ParamField body="queryMode" type="string">
  Query mode for hybrid indexes with Upstash-hosted
  embedding models.

  Specifies whether to run the query in only the
  dense index, only the sparse index, or in both.

  If not provided, defaults to `HYBRID`.

  Possible values are `HYBRID`, `DENSE`, and `SPARSE`.
</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 textual data of the vector before embedding it.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```sh curl theme={"system"}
  curl $UPSTASH_VECTOR_REST_URL/query-data \
    -X POST \
    -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
    -d '{ "data": "What is Upstash?", "topK": 2, "includeMetadata": true }'
  ```

  ```sh curl (Namespace) theme={"system"}
  curl $UPSTASH_VECTOR_REST_URL/query-data/ns \
    -X POST \
    -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
    -d '{ "data": "What is Upstash?", "topK": 2, "includeMetadata": true }'
  ```

  ```sh curl (Batch Query) theme={"system"}
  curl $UPSTASH_VECTOR_REST_URL/query-data \
    -X POST \
    -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
    -d '[
          {
            "data": "What is Upstash?",
            "topK": 2,
            "includeMetadata": true
          },
          {
            "data": "What is Upstash Vector?",
            "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
          }
      ]
  }
  ```

  ```json 422 Unprocessable Entity theme={"system"}
  {
      "error": "Embedding data for this index is not allowed. The index must be created with an embedding model to use it.",
      "status": 422
  }
  ```
</ResponseExample>