Struct MutableVectorIndex 

pub struct MutableVectorIndex { /* private fields */ }

Thread-safe mutable overlay over an immutable HNSW base.

Inserts and updates are searched exactly from a bounded delta. Deletions are tombstones. Self::compact deterministically folds both into a new immutable base without making readers observe a partial rebuild.

Implementations

impl MutableVectorIndex

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

Loads a complete mutable bundle. Legacy immutable vector snapshots are accepted with empty metadata and deltas.

Errors

Returns typed snapshot or storage errors.

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

Atomically saves base and sealed graphs, staged vectors, tombstones, and metadata without forcing compaction.

Errors

Returns a compaction or storage error.

impl MutableVectorIndex

pub fn build( config: IndexConfig, records: &[VectorRecord], ) -> Result<Self, SearchError>

Builds a mutable index and preserves supplied metadata.

Errors

Returns typed config, vector, allocation, capacity, or duplicate-key errors.

pub fn from_index(index: VectorIndex) -> Self

Wraps an existing immutable index with an empty mutable delta.

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

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn delta_len(&self) -> usize

pub fn staged_len(&self) -> usize

Number of writes still using exact delta search.

pub fn sealed_len(&self) -> usize

Number of live vectors in the sealed HNSW delta.

pub fn should_compact(&self, maximum_delta: usize) -> bool

impl MutableVectorIndex

pub fn insert( &self, key: u64, vector: &[f32], metadata: Metadata, ) -> Result<(), SearchError>

Inserts a new key.

Errors

Returns SearchError::DuplicateKey when the live key already exists, or a typed vector validation error.

pub fn upsert( &self, key: u64, vector: &[f32], metadata: Metadata, ) -> Result<MutationOutcome, SearchError>

Inserts or replaces one key without rebuilding the immutable base.

Errors

Returns a typed vector validation error.

pub fn insert_batch(&self, records: &[VectorRecord]) -> Result<(), SearchError>

Atomically inserts a batch after validating every record.

Errors

Returns without applying any record when the batch contains duplicate keys, an existing live key, or an invalid vector.

pub fn upsert_batch( &self, records: &[VectorRecord], ) -> Result<Vec<MutationOutcome>, SearchError>

Atomically inserts or replaces a batch after validating every record.

Results follow input order.

Errors

Returns without applying any record when the batch contains duplicate keys or an invalid vector.

pub fn delete(&self, key: u64) -> bool

Tombstones a live key. Returns whether a vector was removed.

pub fn delete_batch(&self, keys: &[u64]) -> usize

Tombstones every live key in keys and returns the number removed.

pub fn rename(&self, from: u64, to: u64) -> Result<bool, SearchError>

Renames one live vector key without rebuilding either graph.

Errors

Returns SearchError::DuplicateKey when to is already live.

pub fn set_metadata( &self, key: u64, metadata: Metadata, ) -> Result<(), SearchError>

Replaces metadata without changing the vector.

Errors

Returns SearchError::MissingKey when key is not live.

pub fn metadata(&self, key: u64) -> Option<Metadata>

impl MutableVectorIndex

pub fn seal_delta(&self) -> Result<(), SearchError>

Rebuilds only the mutable delta into its own HNSW graph.

This bounds exact staged scanning without rebuilding the immutable base. Concurrent mutations are retried and never lost.

Errors

Returns a build error or SearchError::MutationConflict after three conflicting attempts.

pub fn compact(&self) -> Result<(), SearchError>

Deterministically rebuilds the immutable base. Concurrent mutations are detected and retried without losing updates.

Errors

Returns a build error or SearchError::MutationConflict after three conflicting rebuilds.

impl MutableVectorIndex

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

Searches the immutable base and exact delta, then deterministically merges equal keys.

Errors

Returns a typed query or allocation error.

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

Searches only records matching filter.

Errors

Returns a typed query or allocation error.

Trait Implementations

impl Debug for MutableVectorIndex

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

Formats the value using the given formatter.

impl SearchShard for MutableVectorIndex

fn dimensions(&self) -> usize

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

Searches this shard.