turbopuffer v3 abandons vector‑primary index in favor of a secondary ANN index

TL;DR – turbopuffer v3 drops the vector‑primary storage layout

turbopuffer v3 makes the ANN index a secondary structure instead of the primary key, which removes massive storage and write amplification and allows much larger vectorized processing blocks, speeding up vector search, full‑text search, aggregations, and other query plans.

Why turbopuffer is redesigning its storage architecture

turbopuffer’s original design (v1) stored each document as an ID + vector and used the ANN address (cluster + local IDs) as the primary key. This worked extremely well for approximate nearest‑neighbor (ANN) search on object storage, enabling single indexes of >100 B vectors with 200 ms p99 latency at >1 k QPS.

However, the vector‑primary layout creates three critical inefficiencies for non‑vector workloads:

Storage amplification – Multi‑vector documents (e.g., late‑interaction models) duplicate all attribute and text payloads for every vector because each vector has its own ANN address.
Write amplification – Insertion, update, or deletion triggers SPFresh rebalancing of vectors, which moves the entire document payload and every inverted index entry that points to the old ANN address.
Limited vectorization – Modern query engines process data in large blocks (thousands of rows). Because the ANN address dictates block size (≈100‑200 docs per cluster), all other query plans are forced into these small blocks, preventing full CPU pipeline utilization.

These problems prevent turbopuffer from delivering state‑of‑the‑art performance for attribute filtering, full‑text search, aggregations, and regex queries.

Evolution of turbopuffer’s query capabilities

v1 – ID + vector only

Hierarchical clustering index (SPANN → SPFresh) stored vectors in a tree of centroids.
Keys were ClusterId + LocalId (e.g., C0L1), forming the ANN address.

v2 – Attribute filtering and full‑text search

Added inverted indexes mapping attribute values or terms to ANN addresses.
Stored document attributes alongside the vector under the same ANN key.
Supported BM25, regex, fuzzy matching, sparse vectors, and ordering by attributes—all built on the same vector‑primary layout.

The core problem: ANN as primary index

Because every document’s payload lives under its ANN address, any change to the vector layout forces a cascade of moves for all associated data. This design mirrors the classic MySQL‑style primary‑index‑point‑to‑row approach, where secondary indexes point to a stable primary key, avoiding massive rewrites on updates. In contrast, PostgreSQL‑style designs point secondary indexes directly to the physical row location, optimizing read‑time lookups at the cost of heavy write amplification.

turbopuffer’s original design is effectively the PostgreSQL model for search: excellent ANN lookup performance but prohibitive write costs and limited block sizes for other query shapes.

turbopuffer v3’s solution – make ANN a secondary index

“don’t key on the ANN address” – turbopuffer v3 replaces the ANN‑address primary key with a conventional document‑ID primary index. The ANN index now behaves like a secondary index that points to the document ID, similar to InnoDB’s secondary‑index‑to‑PK model.

Expected benefits

Reduced storage amplification – Document attributes are stored once per document, regardless of the number of vectors.
Lower write amplification – Rebalancing vectors no longer forces movement of the full document payload or inverted indexes; only the ANN index entries need updating.
Larger vectorized processing blocks – Query engines can now batch thousands of rows for aggregations, regex, and full‑text scoring, unlocking SIMD and better CPU utilization.
Improved query latency – Early benchmarks (e.g., FTS v2) showed 10× smaller posting lists and up to 20× faster queries once posting lists were decoupled from ANN clusters; v3 aims to extend these gains across all query plans.

Community reactions and parallels

gopalv likened the change to the classic Postgres vs. MySQL trade‑off, noting that moving to a stable primary key (MySQL‑style) reduces write‑side amplification.
blakeashleyjr echoed this analogy, emphasizing that stopping indexes from pointing at physical storage locations is the same fix Uber described for PostgreSQL write amplification.
Tsarp highlighted LanceDB’s approach, where ANN is a secondary index and rows live in immutable fragments—directly comparable to turbopuffer v3’s design.
marekgalovic and gk1 argued that “vector database” is a marketing term; the real shift is abandoning the vector‑primary storage layout.
sreekanth850 and peterpanhead advocated for native vector support inside a full‑featured SQL engine, noting that separate vector stores add operational complexity.

What’s next for turbopuffer v3?

Correctness first – The team has achieved 100 % CI pass rate on the new storage layer.
Performance parity – Public benchmarks will be released in the coming weeks as the team optimizes for speed while maintaining the existing ANN performance guarantees.
Rollout plan – After reaching parity, turbopuffer v3 will be deployed to production, promising faster vector, text, and aggregation queries at scale.

Bottom line

turbopuffer v3’s architectural pivot—making ANN a secondary index and adopting a stable document‑ID primary key—directly addresses the storage and write amplification that have limited non‑vector query performance. By aligning with proven database indexing strategies, turbopuffer aims to deliver faster, more scalable search across all query types while preserving its strong ANN capabilities.