Install & Compatibility
Where this runs
tested against v0.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.387s · 22.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.1s · import 0.351s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Index
✓ from upstash_vector import Index
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()
Debug
Known issues
gotchaFor optimal performance and connection reuse in serverless environments, it is recommended to initialize the `Index` client outside of request handlers.fixInitialize `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.
affects: All versions
gotchaThe SDK sends anonymous telemetry data by default (SDK version, platform, Python runtime version).fixTo opt out of telemetry, pass `allow_telemetry=False` during client initialization: `Index(url=..., token=..., allow_telemetry=False)` or `Index.from_env(allow_telemetry=False)`.
affects: All versions
breakingThe Resumable Query API underwent changes in version `0.6.0`.fixReview the official Upstash Vector documentation for the updated usage pattern of `resumable query` and adapt your code accordingly.
affects: v0.6.0 and later (if upgrading from <0.6.0)
gotchaVersion `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.fixUpgrade 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.
affects: prior to v0.8.0
Errors
Common errors & fixes
KeyError: 'UPSTASH_VECTOR_REST_URL'
The `UPSTASH_VECTOR_REST_URL` environment variable is not set or is misspelled when attempting to initialize `Index.from_env()`.
fixEnsure `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
The `UPSTASH_VECTOR_REST_TOKEN` provided is incorrect, expired, or does not have sufficient permissions to access the Upstash Vector index.
fixVerify 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.
The vector being upserted (inserted or updated) has a different dimension (number of elements) than what is configured for your Upstash Vector index.
fixEnsure 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'
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).
fixTo 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)`.
Upgrade
Version history
0.8.0latest on PyPI · released Feb 27, 2025
Audit
Dependencies
No dependency data recorded yet.