The resumable query feature 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.

​
Synchronous Usage

​
Creating a Resumable Query

To create a resumable query, use the resumable_query method of the Index class:

query = index.resumable_query(
    vector=[0.1, 0.2],  # or use 'data' parameter for text-based queries
    top_k=2,
    include_metadata=True,
    include_vectors=True,
    namespace="your_namespace"
)

Parameters:

  • vector: A list of floats representing the query vector.
  • data: A string for text-based queries (mutually exclusive with vector).
  • top_k: The number of results to fetch initially.
  • include_metadata: Whether to include metadata in the results.
  • include_vectors: Whether to include vector values in the results.
  • max-idle: The maximum idle time for the query in seconds.
  • namespace: The namespace to query (optional).

​
Starting the Query

To start the query and get initial results:

initial_results = query.start()

The initial_results will be a list of result objects, each having properties like id and metadata (if included).

​
Fetching More Results

To fetch additional results:

next_results = query.fetch_next(number_of_results)

This method returns a list of additional results. If no more results are available, it returns an empty list.

​
Stopping the Query

When you’re done with the query, stop it to release resources:

stop_result = query.stop()
assert stop_result == 'Success'

​
Asynchronous Usage

For asynchronous operations, use the AsyncIndex class:

​
Creating an Async Resumable Query

query = await async_index.resumable_query(
  vector=[0.1, 0.2],
  top_k=2,
  include_metadata=True,
  include_vectors=True,
  namespace='your_namespace'
)

​
Starting the Async Query

initial_results = await query.async_start()

​
Fetching More Results Asynchronously

next_results = await query.async_fetch_next(number_of_results)

​
Stopping the Async Query

stop_result = await query.async_stop()
assert stop_result == 'Success'

​
Error Handling

After stopping a query, attempting to fetch more results or stop it again will raise a ClientError:

with pytest.raises(ClientError):
  query.fetch_next(1)
  query.async_fetch_next(1)

for async with pytest.raises(ClientError):
  query.stop() # or await query.async_stop() for async

Example: Fetching All Results Here’s an example of how to fetch all results using a resumable query:

query = index.resumable_query(
  vector=[0.1, 0.2],
  top_k=2,
  include_metadata=True
)
results = query.start()
while True:
  next_batch = query.fetch_next(2)
  if not next_batch:
    break
  results.extend(next_batch)
query.stop()

This pattern allows you to efficiently retrieve large result sets without loading everything into memory at once.

Remember to always stop your query when you’re done to release server-side resources.

​
Example

from upstash_vector import Index

# Create an index instance
index = Index()

# Upsert vectors into the index
index.upsert(
    vectors=[
        ("id1", [0.1, 0.2], {"field": "value1"}),
        ("id2", [0.3, 0.4], {"field": "value2"}),
        ("id3", [0.5, 0.6], {"field": "value3"}),
    ],
    namespace="example-namespace"
)

# Start a resumable query
query = index.resumable_query(
    vector=[0.1, 0.2],
    top_k=2,
    include_metadata=True,
    include_vectors=True,
    namespace="example-namespace"
)

# Fetch initial results
results = query.start()

# Access result data
for result in results:
    print(f"ID: {result.id}, Metadata: {result.metadata}")

# Stop the query when done
query.stop()

Was this page helpful?

QueryRange