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

The query method is designed to retrieve the most similar vectors from the index, using the specific distance metric defined for your index. This method supports a variety of options to configure the query to your needs.

<Note>
  The dimension of the query vector must match the dimension of your index.
</Note>

<Note>
  The score returned from query requests is a normalized value between 0 and 1,
  where 1 indicates the highest similarity and 0 the lowest regardless of the
  similarity function used.
</Note>

## Arguments

<ResponseField name="Payload" type="QueryCommandPayload" required>
  <Expandable defaultOpen="true">
    <ResponseField name="vector | sparseVector | data" type="number[] | SparseVector | string" required>
      <Note>
        There are two ways to use the query method. You can either create the vectors on your own and pass directly the `vector` or `sparseVector` field, depending on your index type. Or you can pass the `data` field and create the embeddings using Upstash Embedding.
      </Note>

      The query data/vector that you want to search for in the index.
    </ResponseField>

    <ResponseField name="topK" type="number" required>
      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 `topK` vectors will be returned.
    </ResponseField>

    <ResponseField name="includeMetadata" type="boolean">
      Whether to include the metadata of the vectors in the response. Setting
      this `true` would be the best practice, since it will make it easier to
      identify the vectors.
    </ResponseField>

    <ResponseField name="includeVectors" type="boolean">
      Whether to include the vector themselves in the response.
    </ResponseField>

    <ResponseField name="includeData" type="boolean">
      Whether to include [the data field](/vector/features/metadata#data) in the response.
    </ResponseField>

    <ResponseField name="filter" type="string">
      The metadata filtering of the vector. This is used to query your data based on the filters and narrow down the query results.
      If you wanna learn more about filtering check: [Metadata Filtering](/vector/features/filtering)
    </ResponseField>

    <ResponseField name="weightingStrategy" type="WeightingStrategy">
      For sparse vectors, 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.
    </ResponseField>

    <ResponseField name="fusionAlgorithm" type="FusionAlgorithm">
      Fusion algorithm to use while fusing scores from dense and sparse components of a hybrid index. If not provided, defaults to `RRF`.
    </ResponseField>

    <ResponseField name="queryMode" type="QueryMode">
      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`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="Options" type="QueryCommandOptions">
  <Expandable defaultOpen="true">
    <ResponseField name="Namespace" type="string">
      Namespace to query. If not set, default namespace is used.
    </ResponseField>
  </Expandable>
</ResponseField>

## Response

<ResponseField name="Response" type="QueryResult" required>
  <Expandable defaultOpen="true">
    <ResponseField name="id" type="string | number" required>
      The ID of the resulting vector.
    </ResponseField>

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

    <ResponseField name="vector" type="number[]">
      The resulting vector (if `includeVectors` is set to true)
    </ResponseField>

    <ResponseField name="sparseVector" type="SparseVector">
      The resulting sparseVector (if `includeVectors` is set to true)
    </ResponseField>

    <ResponseField name="metadata" type="Record<string, unknown>">
      The metadata of the vector (if `includeMetadata` is set to true)
    </ResponseField>

    <ResponseField name="data" type="string">
      The data of the vector (if `includeData` is set to true)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```typescript Using Vector theme={"system"}
  await index.query({
    topK: 2,
    vector: [ ... ],
    includeMetadata: true,
    includeVectors: true
  }, { namespace: "my-namespace" })
  /*
  [
    {
      id: '6345',
      score: 0.85,
      vector: [],
      metadata: {
        sentence: "Upstash is great."
      }
    },
    {
      id: '1233',
      score: 0.75,
      vector: [],
      metadata: undefined
    },
  ]
  */
  ```

  ```typescript Using Data theme={"system"}
  const results = await index.query({
    data: "Movie about an adventure of a hobbit in a fantasy world.",
    includeVectors: true,
    includeMetadata: true,
    topK: 1,
    filter: "genre = 'fantasy' and title = 'Lord of the Rings'",
  });
  /*
  [
    {
      id: "1234",
      vector: [0.1, 0.2, 0.3, 0.4, 0.5],
      score: 0.9999999,
      metadata: {
        title: "Lord of The Rings",
        genre: "fantasy",
        category: "classic",
      },
    }
  ]
  */
  ```

  ```typescript Improved Typechecking theme={"system"}
  type Metadata = {
    title: string,
    genre: 'sci-fi' | 'fantasy' | 'horror' | 'action'
  }

  const results = await index.query<Metadata>({
    vector: [
      ... // query embedding
    ],
    includeVectors: true,
    topK: 1,
    filter: "genre = 'fantasy' and title = 'Lord of the Rings'"
  })

  if (results[0].metadata) {
    // Since we passed the Metadata type parameter above,
    // we can interact with metadata fields without having to
    // do any typecasting.
    const { title, genre } = results[0].metadata;
    console.log(`The best match in fantasy was ${title}`)
  }
  ```
</RequestExample>