Query - Upstash Documentation

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

QueryCommandPayload

required

vector | sparseVector | data

number[] | SparseVector | string

required

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.

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

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

Whether to include the vector themselves in the response.

includeData

boolean

Whether to include the data field in the response.

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

weightingStrategy

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.

fusionAlgorithm

FusionAlgorithm

Fusion algorithm to use while fusing scores from dense and sparse components of a hybrid index. If not provided, defaults to RRF.

queryMode

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.

Options

QueryCommandOptions

Namespace

string

Namespace to query. If not set, default namespace is used.

Response

QueryResult

required

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[]

The resulting vector (if includeVectors is set to true)

sparseVector

SparseVector

The resulting sparseVector (if includeVectors is set to true)

metadata

Record<string, unknown>

The metadata of the vector (if includeMetadata is set to true)

data

string

The data of the vector (if includeData is set to true)

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
  },
]
*/

​Arguments

​Response

Arguments

Response