Struct VectorIndex 

pub struct VectorIndex { /* private fields */ }

Implementations

impl VectorIndex

pub fn mrl_search( &self, query: &[f32], limit: usize, config: &MrlConfig, filter: Option<&dyn SearchFilter>, ) -> Result<Vec<VectorHit>, SearchError>

Search using MRL-accelerated truncated scan with full-dimension rescore.

If config.search_dims >= self.dimension(), this falls back to the standard search_top_k (no truncation benefit).

Errors

Returns SearchError::DimensionMismatch when query.len() does not match index dimensionality, SearchError::InvalidConfig for invalid config values, and SearchError::IndexCorrupted for malformed data.

pub fn mrl_search_with_stats( &self, query: &[f32], limit: usize, config: &MrlConfig, filter: Option<&dyn SearchFilter>, ) -> Result<(Vec<VectorHit>, MrlSearchStats), SearchError>

Like mrl_search but also returns diagnostic stats.

Errors

Same error conditions as mrl_search.

impl VectorIndex

pub fn search_top_k( &self, query: &[f32], limit: usize, filter: Option<&dyn SearchFilter>, ) -> Result<Vec<VectorHit>, SearchError>

Brute-force cosine-similarity top-k search over all records.

The query is expected to already be normalized for cosine similarity. The result is sorted by descending score with NaN-safe semantics.

Errors

Returns SearchError::DimensionMismatch when query.len() does not match index dimensionality, and SearchError::IndexCorrupted for malformed vector slab contents.

pub fn search_top_k_with_params( &self, query: &[f32], limit: usize, filter: Option<&dyn SearchFilter>, params: SearchParams, ) -> Result<Vec<VectorHit>, SearchError>

Brute-force cosine-similarity top-k search with configurable parallelism.

Behaves identically to search_top_k but uses the caller-supplied SearchParams instead of the compiled-in defaults.

Errors

Returns SearchError::DimensionMismatch when query.len() does not match index dimensionality, and SearchError::IndexCorrupted for malformed vector slab contents.

impl VectorIndex

pub fn open(path: &Path) -> Result<VectorIndex, SearchError>

Open an existing FSVI index from disk.

Errors

Returns SearchError::IndexNotFound if the file does not exist and SearchError::IndexCorrupted when header/layout validation fails.

pub fn create( path: &Path, embedder_id: &str, dimension: usize, ) -> Result<VectorIndexWriter, SearchError>

Create a writer that stores vectors as f16 with an empty revision string.

Errors

Returns SearchError::InvalidConfig when arguments are invalid (for example, zero dimension or oversized header fields).

pub fn create_with_revision( path: &Path, embedder_id: &str, embedder_revision: &str, dimension: usize, quantization: Quantization, ) -> Result<VectorIndexWriter, SearchError>

Create a writer with explicit embedder revision and quantization.

Errors

Returns SearchError::InvalidConfig when arguments are invalid (for example, zero dimension or oversized header fields).

pub const fn record_count(&self) -> usize

Number of vectors in this index.

pub const fn dimension(&self) -> usize

Embedding dimensionality.

pub fn embedder_id(&self) -> &str

Embedder id stored in the index header.

pub fn embedder_revision(&self) -> &str

Embedder revision stored in the index header.

pub const fn quantization(&self) -> Quantization

Stored quantization.

pub const fn metadata(&self) -> &VectorMetadata

Full parsed metadata.

pub const fn set_wal_config(&mut self, config: WalConfig)

Set the WAL configuration for incremental updates.

pub const fn wal_record_count(&self) -> usize

Number of entries in the write-ahead log (pending compaction).

pub fn needs_compaction(&self) -> bool

Whether the WAL is large enough that compaction is recommended.

Returns true when the WAL exceeds either the absolute threshold or the ratio threshold relative to the main index size.

pub fn soft_delete(&mut self, doc_id: &str) -> Result<bool, SearchError>

Tombstone (soft-delete) a document by doc_id.

Returns Ok(true) when a live record was marked deleted, and Ok(false) when the document does not exist or is already tombstoned.

Errors

Returns SearchError::Io for filesystem write/sync failures and SearchError::IndexCorrupted if the on-disk record table is malformed.

pub fn soft_delete_batch( &mut self, doc_ids: &[&str], ) -> Result<usize, SearchError>

Tombstone a batch of document ids.

Returns the number of records that transitioned from live -> deleted.

Errors

Returns the first IO/corruption error encountered while updating flags.

pub fn is_deleted(&self, record_index: usize) -> bool

Whether the record at record_index is tombstoned.

pub fn tombstone_count(&self) -> usize

Number of tombstoned records in the main index.

pub fn tombstone_ratio(&self) -> f64

Fraction of records that are tombstoned (tombstones / record_count).

pub fn needs_vacuum(&self) -> bool

Whether the tombstone ratio exceeds the default vacuum threshold.

pub fn vacuum(&mut self) -> Result<VacuumStats, SearchError>

Rewrite the main index file without tombstoned records.

WAL entries are preserved and reloaded after the rewrite.

Errors

Returns SearchError::Io for filesystem failures and SearchError::IndexCorrupted for malformed data.

pub fn append( &mut self, doc_id: &str, vector: &[f32], ) -> Result<(), SearchError>

Append a single vector to the index via the WAL.

The vector is immediately searchable. It is written to the WAL sidecar file for crash safety.

Errors

Returns SearchError::DimensionMismatch for wrong embedding lengths and SearchError::Io for filesystem failures.

pub fn append_batch( &mut self, entries: &[(String, Vec<f32>)], ) -> Result<(), SearchError>

Append a batch of vectors to the index via the WAL.

All vectors in the batch are written atomically to a single WAL batch (one CRC covers the whole batch).

Errors

Returns SearchError::DimensionMismatch for wrong embedding lengths, SearchError::InvalidConfig for invalid values, and SearchError::Io for filesystem failures.

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

Compact the WAL into the main index.

Rewrites the main index file with all main + WAL records merged, then removes the WAL sidecar. The index is atomically swapped (write to tmp, rename over original).

Errors

Returns SearchError::Io for filesystem failures and SearchError::InvalidConfig for encoding issues.

pub fn doc_id_at(&self, index: usize) -> Result<&str, SearchError>

Resolve the document id at index.

Errors

Returns SearchError::InvalidConfig for out-of-range indices and SearchError::IndexCorrupted for malformed record/string tables.

pub fn vector_at_f32(&self, index: usize) -> Result<Vec<f32>, SearchError>

Decode a vector as f32 values.

Errors

Returns SearchError::InvalidConfig for out-of-range indices and SearchError::IndexCorrupted for malformed vector slab data.

pub fn vector_at_f16(&self, index: usize) -> Result<Vec<f16>, SearchError>

Decode a vector as f16 values.

Errors

Returns SearchError::InvalidConfig for out-of-range indices and SearchError::IndexCorrupted for malformed vector slab data.

pub fn find_index_by_doc_hash(&self, doc_id_hash: u64) -> Option<usize>

Binary-search the sorted record table by document hash.

pub fn get_embeddings(&self, doc_id_hashes: &[u64]) -> Vec<Option<Vec<f16>>>

Fetch embeddings for hashed doc ids (f16 values).

Missing hashes return None entries at the same position.

Trait Implementations

impl Debug for VectorIndex

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

Formats the value using the given formatter.