Struct VectorIndex 

pub struct VectorIndex { /* private fields */ }

Immutable deterministic HNSW candidate index.

Implementations

impl VectorIndex

pub fn search_batch( &self, queries: &[&[f32]], count: usize, ) -> Result<Vec<Vec<SearchHit>>, SearchError>

Searches independent queries using bounded scoped workers. Each worker reuses its visited-set and heaps across queries.

Errors

Returns the first query error in input order or a worker-panic error.

pub fn search_batch_with_policy( &self, queries: &[&[f32]], count: usize, policy: SearchPolicy, ) -> Result<Vec<Vec<SearchHit>>, SearchError>

Searches independent queries with a shared per-query recall policy.

Errors

Returns the first query error in input order or a worker-panic error.

impl VectorIndex

pub fn build( config: IndexConfig, vectors: &[(u64, &[f32])], ) -> Result<Self, SearchError>

Builds independently seeded HNSW replicas over validated normalized vectors.

Input order does not affect the resulting graph when keys, vectors, config, and seed are unchanged.

Errors

Returns typed configuration, vector, capacity, allocation, or worker failures.

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub const fn dimensions(&self) -> usize

pub fn config(&self) -> &IndexConfig

pub fn keys(&self) -> impl ExactSizeIterator<Item = u64> + '_

Iterates stable caller-provided keys in ascending order.

pub fn vector(&self, key: u64) -> Option<&[f32]>

Returns the normalized vector stored for key.

pub fn estimated_memory_bytes(&self) -> usize

Returns an allocation-based estimate of resident vector and graph storage. It excludes allocator metadata and temporary query scratch.

impl VectorIndex

pub fn search( &self, query: &[f32], count: usize, ) -> Result<Vec<SearchHit>, SearchError>

Returns approximate top-K hits ordered by exact distance and key.

Errors

Returns a typed error for an invalid query or scratch allocation.

pub fn search_with_policy( &self, query: &[f32], count: usize, policy: SearchPolicy, ) -> Result<Vec<SearchHit>, SearchError>

Returns approximate top-K hits with a per-query recall policy.

This separates graph expansion from deterministic routing recovery so callers can raise recall without rebuilding the index.

Errors

Returns a typed error for an invalid policy, query, or scratch allocation.

pub fn search_exact( &self, query: &[f32], count: usize, ) -> Result<Vec<SearchHit>, SearchError>

Returns exact top-K results over the same normalized vectors.

This is intended as a correctness and recall oracle.

Errors

Returns a typed error for an invalid query.

pub fn search_exact_filtered<F>( &self, query: &[f32], count: usize, filter: F, ) -> Result<Vec<SearchHit>, SearchError>

where F: Fn(u64) -> bool,

Returns exact top-K results accepted by filter.

Errors

Returns a typed error for an invalid query.

pub fn search_filtered<F>( &self, query: &[f32], count: usize, filter: F, ) -> Result<Vec<SearchHit>, SearchError>

where F: Fn(u64) -> bool,

Searches HNSW candidates accepted by filter, with an exact fallback when selective filters do not yield enough approximate candidates.

Errors

Returns a typed error for an invalid query or scratch allocation.

pub fn search_filtered_with_policy<F>( &self, query: &[f32], count: usize, filter: F, policy: FilterSearchPolicy, ) -> Result<Vec<SearchHit>, SearchError>

where F: Fn(u64) -> bool,

Searches with the predicate applied during graph traversal.

Traversal avoids a full scan and may return fewer than count hits. ExactFallback preserves completeness when the graph cannot find enough accepted candidates.

Errors

Returns a typed error for an invalid query or scratch allocation.

impl VectorIndex

pub fn save(&self, path: impl AsRef<Path>) -> Result<(), SearchError>

Persists normalized vectors, routing data, and every HNSW replica.

The snapshot is written through a temporary sibling and flushed before replacement.

Errors

Returns a typed storage, allocation, or capacity error.

pub fn load(path: impl AsRef<Path>) -> Result<Self, SearchError>

Loads a persisted index into owned memory without rebuilding HNSW.

Errors

Returns a typed storage, version, integrity, allocation, or config error.

pub fn to_bytes(&self) -> Result<Vec<u8>, SearchError>

Serializes the canonical snapshot into an owned byte buffer.

Errors

Returns a typed storage, allocation, or capacity error.

pub fn from_bytes(bytes: &[u8]) -> Result<Self, SearchError>

Restores an owned index directly from a canonical snapshot buffer.

Errors

Returns a typed version, integrity, allocation, or config error.

pub fn write_to<W: Write + Seek>( &self, writer: &mut W, ) -> Result<(), SearchError>

Writes a canonical snapshot to a seekable stream.

The caller should provide an empty or truncated stream.

Errors

Returns a typed stream, allocation, or capacity error.

pub fn read_from<R: Read>(reader: &mut R) -> Result<Self, SearchError>

Reads a complete canonical snapshot from a stream.

Errors

Returns a typed stream, version, integrity, allocation, or config error.

pub fn read_metadata( path: impl AsRef<Path>, ) -> Result<SnapshotMetadata, SearchError>

Reads snapshot metadata without decoding vectors or graphs.

Errors

Returns a typed storage, version, or header error.

Trait Implementations

impl Debug for VectorIndex

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl SearchShard for VectorIndex

fn dimensions(&self) -> usize

fn search_shard( &self, query: &[f32], count: usize, ) -> Result<Vec<SearchHit>, SearchError>

Searches this shard.