Upstash Vector Python SDK

Common errors

• KeyError: 'UPSTASH_VECTOR_REST_URL'

  cause The `UPSTASH_VECTOR_REST_URL` environment variable is not set or is misspelled when attempting to initialize `Index.from_env()`.
  fix Ensure `UPSTASH_VECTOR_REST_URL` and `UPSTASH_VECTOR_REST_TOKEN` are correctly set in your environment. Alternatively, pass the `url` and `token` directly to the `Index` constructor: `Index(url="YOUR_URL", token="YOUR_TOKEN")`.

• upstash_vector.errors.UpstashVectorException: Unauthorized

  cause The `UPSTASH_VECTOR_REST_TOKEN` provided is incorrect, expired, or does not have sufficient permissions to access the Upstash Vector index.
  fix Verify your `UPSTASH_VECTOR_REST_TOKEN` in the Upstash Console and ensure it's accurately configured in your environment variables or passed correctly to the `Index` constructor.

• upstash_vector.errors.UpstashVectorException: Vector dimension mismatch. Expected X, got Y.

  cause The vector being upserted (inserted or updated) has a different dimension (number of elements) than what is configured for your Upstash Vector index.
  fix Ensure that the vectors you provide for `upsert`, `query`, or `update` operations exactly match the dimension configured for your index in the Upstash Console.

• AttributeError: 'UpstashVectorFetchResult' object has no attribute 'vector'

  cause When calling `index.fetch()` or `index.range()`, the `include_vectors` parameter was not explicitly set to `True` (it defaults to `False` or is recommended as `False` for performance if not needed).
  fix To retrieve the actual vector values, you must explicitly set `include_vectors=True` in your `fetch` or `range` calls: `index.fetch(ids=['id'], include_vectors=True)`.

Warnings

• gotcha For optimal performance and connection reuse in serverless environments, it is recommended to initialize the `Index` client outside of request handlers.
  Fix: Initialize `index = Index.from_env()` or `index = Index(url=..., token=...)` globally or at module level, rather than inside a function that is called on every request.
• gotcha The SDK sends anonymous telemetry data by default (SDK version, platform, Python runtime version).
  Fix: To opt out of telemetry, pass `allow_telemetry=False` during client initialization: `Index(url=..., token=..., allow_telemetry=False)` or `Index.from_env(allow_telemetry=False)`.
• breaking The Resumable Query API underwent changes in version `0.6.0`.
  Fix: Review the official Upstash Vector documentation for the updated usage pattern of `resumable query` and adapt your code accordingly.
• gotcha Version `0.8.0` introduced new capabilities for ranging, fetching, and deleting vectors using `id prefix` or `metadata filters`. Previous versions lacked these granular filtering options.
  Fix: Upgrade to v0.8.0 or later to leverage more efficient `range`, `fetch`, and `delete` operations with `prefix` or `filter` arguments. Review the changelog for specific API changes.

Install

• pip install upstash-vector Install via pip

Imports

• Index

  from upstash_vector import Index

Quickstart

Initializes the Upstash Vector client, upserts a sample vector with metadata, fetches it, and performs a similarity query. Credentials are loaded from environment variables (preferred) or can be replaced with direct values. Ensure your Upstash Vector index is created with the correct dimension.

import os
import random
from upstash_vector import Index

# Initialize the index client using environment variables
# Ensure UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN are set
index = Index(
    url=os.environ.get('UPSTASH_VECTOR_REST_URL', 'YOUR_UPSTASH_VECTOR_REST_URL'),
    token=os.environ.get('UPSTASH_VECTOR_REST_TOKEN', 'YOUR_UPSTASH_VECTOR_REST_TOKEN')
)

def main():
    # Define the dimension based on your index configuration (e.g., 128)
    dimension = 128 

    # Generate a random vector for upsert
    vector_to_upsert = [random.random() for _ in range(dimension)]
    
    # Additional metadata associated with the vector (optional)
    metadata = {"text": "example test for metadata", "source": "quickstart"}
    
    # Upsert the vector into the index
    response = index.upsert(vectors=[
        ("id-for-vector-1", vector_to_upsert, metadata)
    ])
    print(f"Upsert response: {response}")

    # Fetch the upserted vector
    fetched_vectors = index.fetch(ids=["id-for-vector-1"], include_vectors=True, include_metadata=True)
    if fetched_vectors and fetched_vectors[0]:
        print(f"Fetched vector: {fetched_vectors[0].id}, Metadata: {fetched_vectors[0].metadata}")
    else:
        print("Vector not found or fetch failed.")

    # Query for similar vectors
    query_vector = [random.random() for _ in range(dimension)] # Example query vector
    query_results = index.query(
        vector=query_vector,
        top_k=1,
        include_vectors=False,
        include_metadata=True
    )
    print(f"Query results: {query_results}")

if __name__ == "__main__":
    main()