What it does
The engine contains a disk-resident approximate index in the SPANN family: an in-memory navigator over cluster centroids and on-disk postings of compressed codes, with live writes, rebalancing and memory-mapped reads. It has engine tests and one published memory measurement. The server does not build it, so it is a roadmap capability.
How it works
Vectors are clustered with k-means. A small in-memory graph over the centroids routes a query to the nprobe nearest postings (default 8). Each posting holds compressed codes for the vectors assigned to it. Rows are estimated cheaply from the codes, and a bounded candidate pool is then reranked exactly against the full-precision embedding. In the engine disk tier each vector is stored in its two nearest postings, so a small nprobe does not lose boundary neighbours.
Writes are visible immediately. Fresh inserts and tombstones sit in a memtable searched exactly alongside the postings, and a flush writes new immutable postings at the next epoch rather than editing files in place. Each flush also splits oversized postings, merges undersized ones and reassigns rows to a closer centroid, which keeps a skewed insert stream from growing one posting without bound.
Settled postings are served from memory-mapped files at query time. Measured, local scope, one host (Cortex-X925, 121 GB RAM): serving SPANN postings from mmap at query time drops resident memory from about 16.4% of raw f32 to 0.13%, roughly 125x less, with byte-identical search results. The artifact adds that resident memory drops but total I/O does not, because the bytes are still read; they become a page-cache matter for the kernel instead of heap memory for the process. The figure is for one 50,000 by 64 corpus and is not a per-vector constant, and no latency claim is attached.
The engine can pick the index by size. With the default tier setting, an index builds as HNSW below 2,000,000 live vectors and as SPANN at or above that count, and the tier can also be forced either way. A fresh disk-tier index uses the Caustic residual codec by default, an override selects the RaBitQ codec, and an index built under another codec is never reinterpreted in place; the engine rebuilds it from the entities.
At boot the engine adopts the index when its manifest watermark equals the entity checkpoint. A missing or damaged directory is rebuilt from the entities. An index at a different watermark is not served: the engine logs an error and falls back to exact scans until the index is rebuilt.
Where you reach it
- Library
Engine::enable_vector_index with EngineConfig::vector_tier(ForceDisk) or vector_tier_threshold; disk_vector_codec (Rust engine API; not exposed by the server)
Limits
- Not reachable through any route, command or setting of the private-preview server.
- Building the index (k-means, encoding, one fsync per posting) holds the writer freeze for the whole build and can take minutes at scale, so writes stall meanwhile.
- The memory measurement covers one small synthetic corpus on one host and attaches no latency claim. Page-cache pressure on a real host will change behaviour.
- Rebalancing runs one bounded round per flush; a pathological insert stream may need several flushes to settle.
- No end-to-end recall or latency artifact exists for the disk tier at the default 2,000,000-vector threshold.
Evidence
- ArtifactBenchmark ledger, including the SPANN mmap residency measurement (local scope, Cortex-X925, 121 GB RAM)
- Tests18 tiering tests and 34 in-module tests cover disk-tier recall against the RAM tier, live writes without a manual rebuild, restart, tombstones and filtered search across flushes, codec mismatch handling and the Caustic default
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
Every figure on this site is local-scope: one host, one operator, no third-party reproduction. Artifacts are linked next to each number, and gates that were missed are published beside the gates that were met.
KynetraDB is in private preview
This is not available in the preview. Request a preview to discuss the current scope.