Vector Search Guide

turbopuffer supports vector search with filtering. Vectors are incrementally indexed in an SPFresh vector index for performant search. Writes appear in search results immediately.

The vector index is automatically tuned for 90-100% recall ("accuracy"). We automatically monitor recall for production queries. You can use the recall endpoint to test yourself.

The example below uses native embeddings, so turbopuffer turns the text into vectors on write and query. To embed in your own code instead, choose an from the dropdown in the code sample.

# $ pip install turbopuffer
import os
import uuid

import turbopuffer

tpuf = turbopuffer.Turbopuffer(
    api_key=os.getenv("TURBOPUFFER_API_KEY"), # created here: https://turbopuffer.com/dashboard
    region="gcp-us-central1", # choose best region: https://turbopuffer.com/docs/regions
)

namespace = os.getenv("TURBOPUFFER_NAMESPACE", f"vector-search-{uuid.uuid4().hex[:8]}")
ns = tpuf.namespace(namespace)

# Upsert documents with attributes
ns.write(
    upsert_rows=[
        {
            "id": 1,
            "text": "A cat sleeping on a windowsill",
            "category": "animal",
        },
        {
            "id": 2,
            "text": "A playful kitten chasing a toy",
            "category": "animal",
        },
        {
            "id": 3,
            "text": "An airplane flying through clouds",
            "category": "vehicle",
        },
    ],
    distance_metric="cosine_distance",
    schema={
        "text": {"type": "string", "embed": {"model": "nvidia/nemotron-3-embed-8b", "dims": 1024}},
    },
)

# Basic vector search
result = ns.query(
    rank_by=("text", "ANN", ("Embed", "feline")),
    limit=2,
    include_attributes=["text"],
)
print(result.rows)

# Vector search with filters
ns2 = tpuf.namespace(f"{namespace}-vehicles")
ns2.write(
    upsert_rows=[
        {
            "id": 1,
            "description": "A shiny red sports car",
            "color": "red",
            "type": "car",
            "price": 50000,
        },
        {
            "id": 2,
            "description": "A sleek blue sedan",
            "color": "blue",
            "type": "car",
            "price": 35000,
        },
        {
            "id": 3,
            "description": "A large red delivery truck",
            "color": "red",
            "type": "truck",
            "price": 80000,
        },
        {
            "id": 4,
            "description": "A blue pickup truck",
            "color": "blue",
            "type": "truck",
            "price": 45000,
        },
    ],
    distance_metric="cosine_distance",
    schema={
        "description": {"type": "string", "embed": {"model": "nvidia/nemotron-3-embed-8b", "dims": 1024}},
    },
)

result = ns2.query(
    rank_by=("description", "ANN", ("Embed", "car")),
    limit=10,
    filters=("And", (("price", "Lt", 60000), ("color", "Eq", "blue"))),
    include_attributes=["description", "price"],
)
print(result.rows)