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.

The dimension of the query vector must match the dimension of your index.

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.

Arguments

Payload · QueryOptions · required

Hide child attributes

vector · number[] · required

The query vector

topK · 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.

includeMetadata · 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.

includeVectors · boolean

The metadata of the vector. This is used to make it easier to identify the vector on queries.

filter · 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

Response

QueryResponse · Vector[] · required

Hide child attributes

id · string | number · required

The ID of the resulting vector.

score · number · required

The score of the vector data, calculated based on the distance metric of your index.

vector · number[] · required

The resulting vector.

metadata · Record<string, unknown>

The metadata of the vector. This is used to make it easier to identify the vector on queries.

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: ''
}
*/

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}`)
}