HeliosDB Nano v3.32 — A Durable, 16×-Smaller Vector Index for RAG, With Recall-Safe Defaults

v3.32 lands the vector-search story RAG builders have been asking for: a durable, crash-recoverable HNSW index with Product-Quantization compression, online deletes with neighbour repair, and filtered KNN — all in one in-house Rust path, all under Apache 2.0, and all opt-in behind a single Cargo feature. Two releases stack together: v3.32.0 ships the index, v3.32.1 fixes the PQ-config default that controls recall on every callsite. If you upgrade for one thing, upgrade for both.

What's new

Persistent PQ-HNSW. A new PersistentVectorIndex in heliosdb_nano::vector::persistent that combines a from-scratch HNSW graph (Malkov & Yashunin) with k-means Product Quantization codes, RocksDB-backed persistence (in the __vidx: keyspace), online deletes with neighbour repair, and filtered KNN in a single index. open() restores the graph from disk with no rebuild — the first query after restart is the same speed as the thousandth.

Two-stage rerank. PQ codes (~16× smaller than full vectors) stay resident in RAM; full vectors stay on disk. Queries traverse the graph with Asymmetric Distance Computation on the codes, then rerank the candidate set against the full vectors for exact ordering. Measured recall@10: 0.987 (PQ) vs 0.989 (exact) on the canonical 2 000-vector / dim-128 fixture from the engine's validation report.

Recall-safe defaults (v3.32.1). ProductQuantizerConfig::default_for_dimension previously picked too few sub-quantizers for common embedding sizes — dim-384 collapsed to a 4-byte code, recall floor ~0.026 — silently breaking any caller that relied on the default. The default now targets ~4 dimensions per sub-vector (≈16× compression), the operating point that holds recall. The fix touches three call paths: the SQL CREATE INDEX … USING hnsw PQ path, quantized_hnsw, and the v3.32.0 create_with_pq fallback. Found by the CodeKB MCP team's adoption testing of v3.32.0 and shipped the same day.

Online deletes + compaction. remove() repairs the affected neighbourhood so the graph's recall stays stable under churn; compact() reclaims tombstoned space. Tombstone-only deletes rot recall on long-running corpora (doc updates, GDPR right-to-be-forgotten, expiring data). This is the path that survives.

Filtered KNN. search_filtered() evaluates a row predicate during graph traversal. Post-filtering a top-k often returns far fewer than k rows that pass the filter; this returns the top-k that pass. The natural fit for multi-tenancy (WHERE tenant_id = $1) and shard-style queries.

Multi-precision rerank dial. F32 / F16 (hand-rolled IEEE half) / I8 scalar quantization on the rerank vectors. Trade a bit of recall for half (F16) or a quarter (I8) of the rerank-store footprint. Zero new dependencies.

Numbers worth quoting

From the validation report and the head-to-head bench on the merge branch (both shipped in-tree as VALIDATION_REPORT_persistent_pq_hnsw.md and BENCHMARK_main_vs_persistent_pq_hnsw.md):

• RAM: 1 024 KB → 64 KB at dim-128 / n-2 000 (16.0× compression). At dim-384 / n-18 985 the in-house adoption smoke measured 27.81 MB → 1.74 MB (also 16.0×).
• Recall@10: 0.987 (PQ) vs 0.989 (exact). The 6 % gap on the larger synthetic corpus reproduces within methodology noise.
• Persistence: drop → reopen returns identical top-10. Two queries 1 µs apart across a process restart see the same row IDs in the same order.
• No regression elsewhere: default-features cargo bench on main vs the merge branch scatters bidirectionally (−13 % … +16 %) across OLTP and existing vector paths — the signature of machine noise, not code. The entire delta is gated behind #[cfg(feature = "vector-persist")], so the default binary is byte-identical to v3.31.2.

Measured on representative fixtures — reproduce on your own and report variance.

What it doesn't change

The existing in-RAM hnsw_index and quantized_hnsw paths are unchanged on the durability axis — they remain in-RAM, fast, and the right choice for ephemeral or small corpora. The new path is additive and opt-in. Enable it with:

cargo add heliosdb-nano@3.32.1 --features vector-persist

The new index is currently a library API. SQL CREATE INDEX wiring for the persistent path is on the roadmap; today you call it from Rust the same way the engine drives code_index and graph_rag_ingest_docs.

Where to go next

• Build a RAG App on Nano v3.32 — an 80-line Rust walkthrough from fastembed to a persistent, compressed index.
• Building a Persistent, Quantized, Deletable HNSW in Rust — the engineering deep dive: HNSW + PQ + RocksDB + delete repair, no third-party graph crate.
• Benchmarking Nano v3.32 — the full recall / memory / latency table.

HeliosDB Nano is Apache 2.0. Repository: github.com/dimensigon/HDB-HeliosDB-Nano.

← Back to Blog