> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-vector.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>

## 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 recieve 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>
  </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,
  })

  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>