Struct MmapVectorStore 

pub struct MmapVectorStore { /* private fields */ }

Memory-mapped vector store for ultra-high-throughput writes.

This implementation uses memory-mapped I/O to achieve 500K-1M vectors/sec write throughput by eliminating syscall overhead.

Key Features

• Direct memory writes: No write() syscalls, just memcpy
• Pre-allocated storage: File is pre-sized to avoid remapping
• Checkpoint-based durability: msync() called periodically, not per-write
• HNSW index: Same O(log N) search as regular VectorStore

Trade-offs

• Higher memory usage (file is memory-mapped)
• Checkpoint-bounded durability (may lose recent writes on crash)
• Requires pre-allocation (must estimate capacity)

Implementations

impl MmapVectorStore

pub fn new<P: AsRef<Path>>(path: P, config: MmapVectorConfig) -> Result<Self>

Creates or opens a memory-mapped vector store.

Arguments

• path - Path to the mmap file
• config - Configuration for the store

Errors

• SynaError::InvalidDimensions - If dimensions are not in range 64-8192
• SynaError::Io - If file operations fail

pub fn insert(&mut self, key: &str, vector: &[f32]) -> Result<()>

Inserts a vector with the given key.

This is an ultra-fast operation because it writes directly to memory without any syscalls. The data is persisted via periodic checkpoints.

Arguments

• key - Unique identifier for the vector
• vector - The vector data (must match configured dimensions)

Errors

• SynaError::DimensionMismatch - If vector length doesn’t match
• SynaError::Io - If the mmap region is full

pub fn insert_batch( &mut self, keys: &[&str], vectors: &[&[f32]], ) -> Result<usize>

Inserts multiple vectors in a batch (maximum throughput).

This is the fastest way to load vectors, achieving 500K-1M vectors/sec.

Arguments

• keys - Slice of key strings
• vectors - Slice of vector slices

Returns

Number of vectors successfully inserted.

pub fn get(&self, key: &str) -> Result<Option<Vec<f32>>>

Retrieves a vector by key.

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

Gets a vector as a slice reference (zero-copy).

Safety

The returned slice is valid only as long as the MmapVectorStore exists and no grow operations occur.

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

Searches for the k nearest neighbors.

pub fn build_index(&mut self) -> Result<()>

Builds the HNSW index from all stored vectors.

pub fn checkpoint(&mut self) -> Result<()>

Checkpoints the store to disk (flushes mmap and saves index).

pub fn flush(&mut self) -> Result<()>

Flushes any pending changes to disk.

pub fn len(&self) -> usize

Returns the number of vectors stored.

pub fn is_empty(&self) -> bool

Returns true if the store is empty.

pub fn dimensions(&self) -> u16

Returns the configured dimensions.

pub fn metric(&self) -> DistanceMetric

Returns the configured distance metric.

pub fn has_index(&self) -> bool

Returns whether an HNSW index is built.

pub fn is_dirty(&self) -> bool

Returns whether the index has unsaved changes.

pub fn keys(&self) -> Vec<String>

Returns all keys in the store.

Trait Implementations

impl Drop for MmapVectorStore

fn drop(&mut self)

Executes the destructor for this type.