> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-fix-issues-on-docs.mintlify.site/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="QueryOptions" required>
  <Expandable defaultOpen="true">
    <ResponseField name="vector" type="number[]" required>
      The query vector
    </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">
      The metadata of the vector. This is used to make it easier to identify the
      vector on queries.
    </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](https://upstash.com/docs/vector/features/filtering)
    </ResponseField>
  </Expandable>
</ResponseField>

## Response

<ResponseField name="QueryResponse" type="Vector[]" 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[]" required>
      The resulting vector.
    </ResponseField>

    <ResponseField name="metadata" type="Record<string, unknown>">
      The metadata of the vector. This is used to make it easier to identify the
      vector on queries.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```typescript Basic
  await index.query({ topK: 2, vector: [ ... ]})
  /*
  {
    matches: [
      {
        id: '6345',
        score: 1.00000012,
        vector: [],
        metadata: {
  		sentence: "Upstash is great."
  	  }
      },
      {
        id: '1233',
        score: 1.00000012,
        vector: [],
        metadata: undefined
      },
    ],
    namespace: ''
  }
  */
  ```

  ```typescript Improved Typechecking
  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>