Turbopuffer Python Client

1.21.0 · active · verified Fri Apr 10

The official Python client library for the Turbopuffer API, a serverless vector database designed for fast, low-cost vector search. It enables programmatic interaction with Turbopuffer services, including creating and managing namespaces, upserting vectors, and performing queries. The library is actively maintained with frequent releases, typically multiple minor versions per month.

Warnings

breaking The `recall` endpoint in the `VectorDatabase` interface no longer accepts the `queries` parameter. Calls using this parameter will fail.
Fix: Remove the `queries` parameter from `recall()` method calls. If you need to perform queries, use the `query()` method instead.
gotcha API key management is crucial. The client primarily authenticates via the `TURBOPUFFER_API_KEY` environment variable. Directly embedding API keys in code is discouraged.
Fix: Set `TURBOPUFFER_API_KEY` as an environment variable (e.g., `export TURBOPUFFER_API_KEY="your_key"`) before running your application. The `tp.init()` call will automatically pick it up, or you can pass it explicitly via `tp.init(api_key=os.environ.get('TURBOPUFFER_API_KEY'))`.
gotcha Ensure the data types and shapes for `ids`, `vectors`, and `metadata` in `upsert` operations match the expected format (lists of integers, lists of floats, and lists of dictionaries, respectively). Mismatched types can lead to errors or unexpected behavior.
Fix: Validate your input data before calling `upsert`. For example, vectors should be `List[List[float]]`, IDs `List[int]`, and metadata `List[Dict[str, Any]]`.

Install

pip install turbopuffer Install Turbopuffer

Imports

turbopuffer
```
import turbopuffer as tp
```

Quickstart

This quickstart initializes the Turbopuffer client, creates or retrieves a namespace, upserts sample vectors with metadata, and then performs a simple query. Ensure the `TURBOPUFFER_API_KEY` environment variable is set for authentication.

import turbopuffer as tp
import os

# Ensure your API key is set as an environment variable (TURBOPUFFER_API_KEY)
api_key = os.environ.get('TURBOPUFFER_API_KEY', 'YOUR_API_KEY')

if not api_key or api_key == 'YOUR_API_KEY':
    print("Warning: TURBOPUFFER_API_KEY environment variable not set. Using dummy key.")

tp.init(api_key=api_key)

namespace_name = "my_first_namespace"
# Creating a namespace (idempotent operation)
# You might get a 409 Conflict if it already exists, which is fine.
# The library's methods generally handle existing resources gracefully.
# For example, create_namespace will return the existing namespace if it already exists
# instead of raising an error.

try:
    namespace = tp.VectorDatabase.create_namespace(namespace_name)
    print(f"Namespace '{namespace_name}' created or retrieved successfully.")
except tp.APIStatusError as e:
    if e.status_code == 409:
        print(f"Namespace '{namespace_name}' already exists. Retrieving it.")
        namespace = tp.VectorDatabase.get_namespace(namespace_name)
    else:
        raise

# Upserting data
vectors = [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]]
ids = [1, 2]
metadata = [{'text': 'hello'}, {'text': 'world'}]

namespace.upsert(ids=ids, vectors=vectors, metadata=metadata)
print("Vectors upserted.")

# Querying data
query_vector = [0.11, 0.22, 0.33]
results = namespace.query(vector=query_vector, top_k=1)
print(f"Query results: {results.vectors[0]} with metadata {results.metadata[0]}.")

view raw JSON →