Struct HnswIndex 

pub struct HnswIndex { /* private fields */ }

Hierarchical Navigable Small World graph index.

Production HNSW per Malkov & Yashunin (2018):

• Multi-layer graph with exponential layer assignment
• FP32 construction for structural integrity
• Heuristic neighbor selection (Algorithm 4)
• Beam search with configurable ef parameter

Implementations

impl HnswIndex

pub fn insert(&mut self, vector: Vec<f32>) -> Result<(), VectorError>

Insert a vector into the index.

1. Assign a random layer using the exponential distribution
2. Greedily descend from the entry point to the new node’s layer + 1
3. At each layer from the node’s layer down to 0, search for nearest neighbors, select via the diversity heuristic, and add bidirectional edges
4. Prune over-connected nodes to maintain the M/M0 invariant

impl HnswIndex

pub fn new(dim: usize, params: HnswParams) -> HnswIndex

Create a new empty HNSW index.

pub fn with_seed(dim: usize, params: HnswParams, seed: u64) -> HnswIndex

Create with a specific RNG seed (for deterministic testing).

pub fn len(&self) -> usize

pub fn live_count(&self) -> usize

pub fn tombstone_count(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn delete(&mut self, id: u32) -> bool

Soft-delete a vector by internal node ID.

pub fn is_deleted(&self, id: u32) -> bool

pub fn undelete(&mut self, id: u32) -> bool

pub fn dim(&self) -> usize

pub fn get_vector(&self, id: u32) -> Option<&[f32]>

pub fn params(&self) -> &HnswParams

pub fn entry_point(&self) -> Option<u32>

pub fn max_layer(&self) -> usize

pub fn checkpoint_to_bytes(&self) -> Vec<u8>

Serialize the index to MessagePack bytes for storage.

NOTE: The checklist mandates rkyv for engine blobs, but HNSW’s recursive Vec<Vec> structure doesn’t support rkyv derive (same issue as Value). We use MessagePack here — the cold-start budget is met because HNSW rebuild from checkpoint is a single deserialization, not per-node allocation. For CSR (flat arrays), rkyv zero-copy is used.

pub fn from_checkpoint(bytes: &[u8]) -> Option<HnswIndex>

Restore an index from a checkpoint snapshot.

pub fn compact(&mut self) -> usize

Compact the index by removing all tombstoned nodes.

impl HnswIndex

pub fn search_filtered( &self, query: &[f32], k: usize, ef: usize, allowed: &HashSet<u32>, ) -> Vec<SearchResult>

K-NN search with pre-filtering: only consider vectors whose IDs are in allowed.

The graph is still traversed through all nodes for connectivity, but only nodes in allowed are added to the result set. This gives much better recall than post-filtering because the beam search can explore deeper before filling the result set.

ef is automatically scaled up to compensate for filter selectivity.

pub fn search(&self, query: &[f32], k: usize, ef: usize) -> Vec<SearchResult>

K-NN search: find the k closest vectors to query.

ef controls the search beam width (higher = better recall, slower). Must be >= k. Typical values: ef = 2k to 10k.