vector-py

upstash-vector is the official Python SDK for Upstash Vector, a serverless vector database accessed entirely over a REST API. It wraps that HTTP interface in a typed Index (sync) and AsyncIndex (async) client, letting Python code upsert, query, fetch, update, delete, and range over vectors without hand-rolling HTTP calls or connection pooling.

The library supports Upstash Vector’s dense, sparse, and hybrid index types, plus embedding-model-backed indexes that accept raw string data instead of pre-computed vectors, resumable multi-page queries, per-namespace operations, and metadata filtering, all built on top of httpx with configurable retry behavior.

What You Get

• Sync and async clients - Index and AsyncIndex mirror the same operations, one built on httpx.Client, the other on httpx.AsyncClient.
• Full CRUD over vectors - upsert, query, fetch, update, delete, and range, each accepting tuples, dicts, or Vector/Data dataclasses.
• Dense, sparse, and hybrid index support, including SparseVector plus fusion-algorithm and weighting-strategy controls for hybrid queries.
• Embedding-model indexes - upsert and query with raw string data instead of precomputed vectors when the index has an embedding model attached.
• Namespace-scoped operations plus list-namespaces and delete-namespace calls for multi-tenant indexes.
• Resumable queries for paging through large top-k result sets across multiple requests.
• Built-in retry handling with configurable retries and retry_interval on every client.

Common Use Cases

• RAG pipelines - a Python backend upserts document embeddings via index.upsert() and retrieves nearest neighbors with index.query() to ground LLM responses.
• Semantic search over string data - apps on an embedding-model-backed index upsert and query with raw text via Data/data=, letting Upstash generate the vectors server-side.
• Multi-tenant vector storage - SaaS products isolate each customer’s vectors in a dedicated namespace, using list-namespaces and delete-namespace for lifecycle management.
• Hybrid keyword + semantic search - services combine dense and sparse vectors in one query with a fusion algorithm, blending lexical and embedding relevance.

Under The Hood

Architecture The SDK is a thin layered wrapper: Index/AsyncIndex (client.py) inherit from IndexOperations/AsyncIndexOperations (core/index_operations.py) which define all vector operations - upsert, query, fetch, delete, update, range, list_namespaces, delete_namespace, and the resumable-query family - and build a JSON payload before calling _execute_request/_execute_request_async. Actual HTTP transport lives in http.py’s execute_with_parameters/execute_with_parameters_async, which wrap an httpx Client/AsyncClient POST call in a bounded retry loop and unwrap the REST response envelope, raising UpstashError on failure. Type and dataclass definitions (Vector, Data, SparseVector, QueryResult, FetchResult, RangeResult, InfoResult) live in types.py, and utils.py converts arbitrary vector shapes - tuples, dicts, dataclasses, numpy-like objects via a SupportsToList protocol - into REST payloads. Separation of concerns is clean: operations describe what request to build, http.py handles how to send it, and types.py defines the wire-shaped domain objects, with sync and async clients sharing the same operation logic through inheritance rather than duplicating it.

Tech Stack A pure Python package built with Poetry, targeting Python 3.8 and up, with httpx as its only runtime dependency for both sync and async HTTP. Dev tooling includes mypy for type checking, ruff for linting, and pytest/pytest-asyncio for testing, plus numpy and pandas as optional test-time dependencies used to exercise the SupportsToList protocol against array-like objects. There is no web framework, ORM, or CLI involved - it is a lean REST client library, distributed via Poetry’s build backend with a dedicated release workflow for publishing on tag.

Code Quality Tests live under tests/core/, covering upsert, query, fetch, delete, update, range, reset, resumable-query, namespace operations, and info, each parametrized across dense, sparse, hybrid, and embedding-model index fixtures defined in conftest.py. These run as live integration tests against real Upstash Vector REST endpoints rather than mocks, verifying actual wire behavior. Error handling is explicit and typed - UpstashError for REST-level failures, ClientError for invalid client-side input - and the codebase is comprehensively type-hinted with dataclasses, a Protocol for SupportsToList, and generic Sequence/Union types, enforced by mypy and ruff. A CI workflow runs the test suite on every push, and naming is consistent snake_case throughout.

API Design The public API favors flexibility over rigidity: upsert() accepts plain tuples, dicts, Vector dataclasses, or Data dataclasses for embedding-backed indexes, and that same flexibility carries through query, fetch, and update. Index.from_env() removes boilerplate for the common case of loading REST credentials from the environment, and every operation exposes namespace as an optional keyword rather than requiring a separate namespace-scoped client. Docstrings on public methods include runnable examples directly in code, which is unusually thorough for a library this size - though the operations module itself is large for what is conceptually a handful of REST calls, since each dense/sparse/hybrid/embedding variant is documented and typed separately rather than collapsed into a single builder.