Struct HNSWIndex 

pub struct HNSWIndex { /* private fields */ }

HNSW index for approximate nearest neighbor search.

Implementations

impl HNSWIndex

pub fn new() -> HNSWIndex

Create a new HNSW index with default configuration.

pub const fn with_config(config: HNSWConfig) -> HNSWIndex

Create a new HNSW index with custom configuration.

pub fn with_instrumentation(config: HNSWConfig) -> HNSWIndex

Create an HNSW index with access instrumentation enabled.

pub const fn has_instrumentation(&self) -> bool

Returns true if access instrumentation is enabled.

pub fn access_stats(&self) -> Option<HNSWStatsSnapshot>

Returns access statistics snapshot if instrumentation is enabled.

pub fn len(&self) -> usize

Returns the number of nodes in the index.

Panics

Panics if the internal lock is poisoned.

pub fn is_empty(&self) -> bool

Returns true if the index contains no nodes.

pub fn insert(&self, vector: Vec<f32>) -> usize

Insert a vector into the index. Returns the assigned node ID.

pub fn insert_sparse(&self, sparse: SparseVector) -> usize

Insert a sparse vector into the index. Returns the assigned node ID.

pub fn insert_auto(&self, vector: Vec<f32>) -> usize

Insert a vector with automatic storage format selection.

Automatically chooses sparse storage when the vector has sparsity above config.sparsity_threshold (default 50% zeros), otherwise uses dense storage. This provides memory savings for high-sparsity vectors without requiring manual format selection.

pub fn try_insert( &self, vector: Vec<f32>, ) -> Result<usize, EmbeddingStorageError>

Try to insert a vector into the index.

Errors

Returns Err(CapacityExceeded) if max_nodes limit is reached.

pub fn try_insert_sparse( &self, sparse: SparseVector, ) -> Result<usize, EmbeddingStorageError>

Try to insert a sparse vector into the index.

Errors

Returns Err(CapacityExceeded) if max_nodes limit is reached.

pub fn insert_quantized(&self, vector: &[f32]) -> usize

Insert a vector with 8-bit scalar quantization.

Quantizes the vector to 8-bit precision before storage, achieving ~4x memory reduction compared to dense storage. The quantization preserves relative magnitudes using asymmetric min/max scaling.

Trade-offs

• Memory: ~4x reduction (768-dim: 3072 bytes -> 784 bytes)
• Recall: Typically >90% recall@10 compared to dense
• Latency: ~10-20% overhead from dequantization during search

pub fn try_insert_quantized( &self, vector: &[f32], ) -> Result<usize, EmbeddingStorageError>

Try to insert a quantized vector into the index.

Errors

Returns Err(CapacityExceeded) if max_nodes limit is reached.

pub fn insert_quantized_vector(&self, quantized: ScalarQuantizedVector) -> usize

Insert a pre-quantized vector into the index.

pub fn insert_tt( &self, vector: Vec<f32>, config: &TTConfig, ) -> Result<usize, String>

Insert a vector with TensorTrain compression.

Uses Tensor Train decomposition to compress the vector before storage, achieving 8-10x memory savings for high-dimensional vectors (768+ dims). The config parameter controls compression accuracy vs size tradeoff.

Errors

Returns an error if TT decomposition fails.

pub fn insert_tt_vector(&self, tt: &TTVector) -> usize

Insert a pre-decomposed TensorTrain vector.

Reconstructs to dense for storage - HNSW needs fast distance computations. TT compression is useful for storage/transmission, not HNSW indexing.

pub fn insert_batch_tt( &self, vectors: Vec<Vec<f32>>, config: &TTConfig, ) -> Result<Vec<usize>, String>

Insert multiple vectors with TensorTrain validation in batch.

Vectors are validated via TT decomposition but stored as dense for fast HNSW distance computations.

Errors

Returns an error if batch TT decomposition fails.

pub fn search_tt( &self, query: &[f32], k: usize, config: &TTConfig, ) -> Vec<(usize, f32)>

Search with a TensorTrain-compressed query.

The query is compressed before searching, reducing memory bandwidth during the search. Works best when the index contains TT-compressed vectors.

pub fn search_tt_with_ef( &self, query_tt: &TTVector, k: usize, ef: usize, ) -> Vec<(usize, f32)>

Search with TT query and custom ef parameter.

Uses native TT operations throughout - no dense reconstruction needed. For TT-to-TT comparisons, this is zero-allocation.

Panics

Panics if the internal lock is poisoned.

pub fn insert_embedding(&self, embedding: EmbeddingStorage) -> usize

Insert an embedding (dense or sparse) into the index.

Use try_insert_embedding for a non-panicking version.

Panics

Panics if the index is at capacity (max_nodes), if Delta vectors are used, or if the internal lock is poisoned.

pub fn try_insert_embedding( &self, embedding: EmbeddingStorage, ) -> Result<usize, EmbeddingStorageError>

Insert an embedding with capacity checking.

Errors

Returns Err(CapacityExceeded) if max_nodes limit is reached. Returns Err(DeltaNotSupported) if a Delta vector is provided.

Panics

Panics if the internal lock is poisoned.

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

Search for k nearest neighbors of the query vector.

pub fn search_sparse(&self, query: &SparseVector, k: usize) -> Vec<(usize, f32)>

Search for k nearest neighbors using a sparse query.

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

Search with custom ef parameter (higher = better recall, slower)

Panics

Panics if the internal lock is poisoned.

pub fn search_sparse_with_ef( &self, query: &SparseVector, k: usize, ef: usize, ) -> Vec<(usize, f32)>

Search with sparse query and custom ef parameter.

Panics

Panics if the internal lock is poisoned.

pub fn get_vector(&self, id: usize) -> Option<Vec<f32>>

Get the vector for a node ID (as dense, for compatibility).

Returns None if the vector cannot be converted to dense (e.g., Delta without registry).

Panics

Panics if the internal lock is poisoned.

pub fn get_embedding(&self, id: usize) -> Option<EmbeddingStorage>

Get the embedding storage for a node ID.

Panics

Panics if the internal lock is poisoned.

pub fn memory_stats(&self) -> HNSWMemoryStats

Get memory usage statistics.

Panics

Panics if the internal lock is poisoned.

pub const fn config(&self) -> &HNSWConfig

Get configuration

pub const fn set_ef_search(&mut self, ef: usize)

Set ef_search parameter (controls recall/speed tradeoff)

Trait Implementations

impl Default for HNSWIndex

fn default() -> HNSWIndex

Returns the “default value” for a type.