Resumable Query - Upstash Documentation

The resumableQuery method allows you to perform queries that can be resumed to fetch additional results. This is particularly useful for large result sets or when implementing pagination.

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

PayloadResumableQueryPayloadrequired

vector | sparseVector | datanumber[] | SparseVector | stringrequired

There are two ways to use the resumableQuery 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.

topKnumberrequired

The initial number of vectors to retrieve in the query result. The response will be sorted based on the distance metric score.

includeMetadataboolean

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.

includeVectorsboolean

Whether to include the vector values in the response.

includeDataboolean

Whether to include the data field in the response.

filterstring

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 want to learn more about filtering check: Metadata Filtering

weightingStrategyWeightingStrategy

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.

fusionAlgorithmFusionAlgorithm

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

queryModeQueryMode

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.

maxIdlenumber

Maximum idle time for the resumable query in seconds.

Response

ResumableQueryResponseObjectrequired

resultQueryResult[]required

The initial query results.

fetchNext(additionalK: number) => Promise<Vector[]>required

A function to fetch the next batch of results.

stop() => Promise<string>required

A function to stop the resumable query and release resources.

QueryResultObjectrequired

idstring | numberrequired

The ID of the resulting vector.

scorenumberrequired

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

vectornumber[]

The resulting vector (if includeVectors is set to true)

sparseVectorSparseVector

The resulting sparseVector (if includeVectors is set to true)

metadataRecord<string, unknown>

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

datastring

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

with Vector

const { result, fetchNext, stop } = await index.resumableQuery({  maxIdle: 3600,  topK: 50,  vector: [0, 1, 2, ..., 383], // 384-dimensional vector  includeMetadata: true,  includeVectors: true,});console.log(result);/*[  {    id: '6345',    score: 1.00000012,    vector: [0, 1, 2, ..., 383],    metadata: {      sentence: "Upstash is great."    }  },  // ... more results]*/const nextBatch = await fetchNext(5); // Fetch next 5 resultsconsole.log(nextBatch);await stop(); // Stop the resumable query

with Data

const { result, fetchNext, stop } = await index.resumableQuery({  maxIdle: 3600,  topK: 50,  data: "lord of the rings"  includeMetadata: true,  includeData: true,});console.log(result);/*[  {    id: '6345',    score: 1.00000012,    data: "hobbit",    metadata: {      sentence: "Upstash is great."    }  },  // ... more results]*/const nextBatch = await fetchNext(5); // Fetch next 5 resultsconsole.log(nextBatch);await stop(); // Stop the resumable query

with Metadata Type

type Metadata = {  title: string,  genre: 'sci-fi' | 'fantasy' | 'horror' | 'action'}const { result, fetchNext, stop } = await index.resumableQuery<Metadata>({  vector: [    ... // query embedding  ],  includeMetadata: true,  topK: 1,  filter: "genre = 'fantasy' and title = 'Lord of the Rings'",  maxIdle: 3600,})if (result[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 } = result[0].metadata;  console.log(`The best match in fantasy was ${title}`)}await stop();