Struct HnswIndex 

pub struct HnswIndex { /* private fields */ }

Hierarchical Navigable Small World graph index.

• 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 checkpoint_to_bytes(&self) -> Vec<u8>

Serialize the index to rkyv bytes (with magic header) for storage.

Magic header RKHNS\0 allows from_checkpoint to detect format.

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

Restore an index from a checkpoint snapshot.

Auto-detects format: rkyv (magic RKHNS\0) or legacy MessagePack.

impl HnswIndex

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

Create a new empty HNSW index.

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

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 tombstone_ratio(&self) -> f64

Tombstone ratio: fraction of nodes that are deleted.

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 rng_state(&self) -> u64

Current RNG state (for snapshot reproducibility).

pub fn memory_usage_bytes(&self) -> usize

Approximate memory usage in bytes (vector data + neighbor lists).

pub fn export_vectors(&self) -> Vec<Vec<f32>>

Export all vectors for snapshot transfer.

pub fn export_neighbors(&self) -> Vec<Vec<Vec<u32>>>

Export all neighbor lists for snapshot transfer.

pub fn compact(&mut self) -> usize

Compact the index by removing all tombstoned nodes.

Returns the number of removed nodes. See compact_with_map for the variant that also returns the old→new id remapping.

pub fn compact_with_map(&mut self) -> (usize, Vec<u32>)

Compact and return both the removed count and the old→new id map.

id_map[old_local] = new_local, or u32::MAX if the node was tombstoned (removed).

impl HnswIndex

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.

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

Filtered K-NN search with Roaring bitmap pre-filtering.

pub fn search_filtered_offset( &self, query: &[f32], k: usize, ef: usize, filter: &RoaringBitmap, id_offset: u32, ) -> Vec<SearchResult>

Filtered K-NN search where the bitmap is keyed in a shifted ID space.

id_offset is added to local node IDs before testing filter.contains. Used by multi-segment collections where the bitmap holds GLOBAL ids and each segment’s HNSW nodes are numbered starting at base_id.

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

Deserialize a Roaring bitmap from bytes and perform filtered search.

pub fn search_with_bitmap_bytes_offset( &self, query: &[f32], k: usize, ef: usize, bitmap_bytes: &[u8], id_offset: u32, ) -> Vec<SearchResult>

Deserialize a Roaring bitmap and search with an ID offset applied before testing membership. See search_filtered_offset for rationale.