Struct VectorStore 

pub struct VectorStore {
    pub vectors: Vec<Vector>,
    pub hnsw_index: Option<HNSWIndex>,
    pub id_to_index: FxHashMap<String, usize>,
    /* private fields */
}

Vector store with HNSW indexing

Fields

vectors: Vec<Vector>

All vectors stored in memory (used for rescore when quantization enabled)

hnsw_index: Option<HNSWIndex>

HNSW index for approximate nearest neighbor search

id_to_index: FxHashMap<String, usize>

Map from string IDs to internal indices (public for Python bindings)

Implementations

impl VectorStore

pub fn new(dimensions: usize) -> Self

Create new vector store

pub fn new_with_quantization(dimensions: usize, mode: QuantizationMode) -> Self

Create new vector store with quantization

Quantization is trained on the first batch of vectors inserted.

pub fn new_with_params( dimensions: usize, m: usize, ef_construction: usize, ef_search: usize, distance_metric: Metric, ) -> Result<Self>

Create new vector store with custom HNSW parameters

pub fn open(path: impl AsRef<Path>) -> Result<Self>

Open a persistent vector store at the given path

Creates a new database if it doesn’t exist, or loads existing data. All operations (insert, set, delete) are automatically persisted.

Arguments

• path - Directory path for the database (e.g., “mydb.oadb”)

Example

let mut store = VectorStore::open("mydb.oadb")?;
store.set("doc1".to_string(), vector, metadata)?;
// Data is automatically persisted

pub fn open_with_dimensions( path: impl AsRef<Path>, dimensions: usize, ) -> Result<Self>

Open a persistent vector store with specified dimensions

Like open() but ensures dimensions are set for new databases.

pub fn open_with_options( path: impl AsRef<Path>, options: &VectorStoreOptions, ) -> Result<Self>

Open a persistent vector store with custom options.

This is the internal implementation used by VectorStoreOptions::open().

pub fn build_with_options(options: &VectorStoreOptions) -> Result<Self>

Build an in-memory vector store with custom options.

pub fn insert(&mut self, vector: Vector) -> Result<usize>

Insert vector and return its ID

pub fn insert_with_metadata( &mut self, id: String, vector: Vector, metadata: JsonValue, ) -> Result<usize>

Insert vector with string ID and metadata

This is the primary method for inserting vectors with metadata support. Returns error if ID already exists (use set for insert-or-update semantics).

pub fn set( &mut self, id: String, vector: Vector, metadata: JsonValue, ) -> Result<usize>

Upsert vector (insert or update) with string ID and metadata

This is the recommended method for most use cases.

pub fn set_batch( &mut self, batch: Vec<(String, Vector, JsonValue)>, ) -> Result<Vec<usize>>

Batch set vectors (insert or update multiple vectors at once)

This is the recommended method for bulk operations.

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

Enable text search on this store

pub fn enable_text_search_with_config( &mut self, config: Option<TextSearchConfig>, ) -> Result<()>

Enable text search with custom configuration

pub fn has_text_search(&self) -> bool

Check if text search is enabled

pub fn set_with_text( &mut self, id: String, vector: Vector, text: &str, metadata: JsonValue, ) -> Result<usize>

Upsert vector with text content for hybrid search

pub fn set_batch_with_text( &mut self, batch: Vec<(String, Vector, String, JsonValue)>, ) -> Result<Vec<usize>>

Batch upsert vectors with text content for hybrid search

pub fn text_search(&self, query: &str, k: usize) -> Result<Vec<(String, f32)>>

Search text index only (BM25 scoring)

pub fn hybrid_search( &mut self, query_vector: &Vector, query_text: &str, k: usize, alpha: Option<f32>, ) -> Result<Vec<(String, f32, JsonValue)>>

Hybrid search combining vector similarity and BM25 text relevance

pub fn hybrid_search_with_rrf_k( &mut self, query_vector: &Vector, query_text: &str, k: usize, alpha: Option<f32>, rrf_k: Option<usize>, ) -> Result<Vec<(String, f32, JsonValue)>>

Hybrid search with configurable RRF k constant

pub fn hybrid_search_with_filter( &mut self, query_vector: &Vector, query_text: &str, k: usize, filter: &MetadataFilter, alpha: Option<f32>, ) -> Result<Vec<(String, f32, JsonValue)>>

Hybrid search with filter

pub fn hybrid_search_with_filter_rrf_k( &mut self, query_vector: &Vector, query_text: &str, k: usize, filter: &MetadataFilter, alpha: Option<f32>, rrf_k: Option<usize>, ) -> Result<Vec<(String, f32, JsonValue)>>

Hybrid search with filter and configurable RRF k constant

pub fn hybrid_search_with_subscores( &mut self, query_vector: &Vector, query_text: &str, k: usize, alpha: Option<f32>, rrf_k: Option<usize>, ) -> Result<Vec<(HybridResult, JsonValue)>>

Hybrid search returning separate keyword and semantic scores.

Returns HybridResult with keyword_score (BM25) and semantic_score (vector distance) for each result, enabling custom post-processing or debugging.

pub fn hybrid_search_with_filter_subscores( &mut self, query_vector: &Vector, query_text: &str, k: usize, filter: &MetadataFilter, alpha: Option<f32>, rrf_k: Option<usize>, ) -> Result<Vec<(HybridResult, JsonValue)>>

Hybrid search with filter returning separate keyword and semantic scores.

pub fn update( &mut self, id: &str, vector: Option<Vector>, metadata: Option<JsonValue>, ) -> Result<()>

Update existing vector by string ID

pub fn delete(&mut self, id: &str) -> Result<()>

Delete vector by string ID

This method:

1. Marks the vector as deleted (soft delete)
2. Repairs the HNSW graph using MN-RU algorithm to maintain recall quality
3. Removes from text index if present
4. Persists to WAL

pub fn delete_batch(&mut self, ids: &[String]) -> Result<usize>

Delete multiple vectors by string IDs

Uses batch MN-RU graph repair for better efficiency than individual deletes.

pub fn delete_by_filter(&mut self, filter: &MetadataFilter) -> Result<usize>

Delete vectors matching a metadata filter

Evaluates the filter against all vectors and deletes those that match. This is more efficient than manually iterating and calling delete_batch.

Arguments

• filter - MongoDB-style metadata filter

Returns

Number of vectors deleted

pub fn count_by_filter(&self, filter: &MetadataFilter) -> usize

Count vectors matching a metadata filter

Evaluates the filter against all vectors and returns the count of matches. More efficient than iterating and counting manually.

Arguments

• filter - MongoDB-style metadata filter

Returns

Number of vectors matching the filter

pub fn get(&self, id: &str) -> Option<(Vector, JsonValue)>

Get vector by string ID

Returns owned data since vectors may be loaded from disk for quantized stores.

pub fn get_batch( &self, ids: &[impl AsRef<str>], ) -> Vec<Option<(Vector, JsonValue)>>

Get multiple vectors by string IDs

Returns a vector of results in the same order as input IDs. Missing/deleted IDs return None in their position.

pub fn get_metadata_by_id(&self, id: &str) -> Option<&JsonValue>

Get metadata by string ID (without loading vector data)

pub fn batch_insert(&mut self, vectors: Vec<Vector>) -> Result<Vec<usize>>

Insert batch of vectors in parallel

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

Rebuild HNSW index from existing vectors

pub fn merge_from(&mut self, other: &VectorStore) -> Result<usize>

Merge another VectorStore into this one using IGTM algorithm

pub fn needs_index_rebuild(&self) -> bool

Check if index needs to be rebuilt

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

Ensure HNSW index is ready for search

pub fn knn_search( &mut self, query: &Vector, k: usize, ) -> Result<Vec<(usize, f32)>>

K-nearest neighbors search using HNSW

pub fn knn_search_with_ef( &mut self, query: &Vector, k: usize, ef: Option<usize>, ) -> Result<Vec<(usize, f32)>>

K-nearest neighbors search with optional ef override

pub fn knn_search_readonly( &self, query: &Vector, k: usize, ef: Option<usize>, ) -> Result<Vec<(usize, f32)>>

Read-only K-nearest neighbors search (for parallel execution)

pub fn knn_search_ef( &self, query: &Vector, k: usize, ef: usize, ) -> Result<Vec<(usize, f32)>>

Fast K-nearest neighbors search with concrete ef value

pub fn knn_search_with_filter( &mut self, query: &Vector, k: usize, filter: &MetadataFilter, ) -> Result<Vec<(usize, f32, JsonValue)>>

K-nearest neighbors search with metadata filtering

pub fn knn_search_with_filter_ef( &mut self, query: &Vector, k: usize, filter: &MetadataFilter, ef: Option<usize>, ) -> Result<Vec<(usize, f32, JsonValue)>>

K-nearest neighbors search with metadata filtering and optional ef override

pub fn knn_search_with_filter_ef_readonly( &self, query: &Vector, k: usize, filter: &MetadataFilter, ef: Option<usize>, ) -> Result<Vec<(usize, f32, JsonValue)>>

Read-only filtered search (for parallel execution)

Uses Roaring bitmap index for O(1) filter evaluation when possible, falls back to JSON-based filtering for complex filters.

pub fn search( &mut self, query: &Vector, k: usize, filter: Option<&MetadataFilter>, ) -> Result<Vec<(usize, f32, JsonValue)>>

Search with optional filter (convenience method)

pub fn search_with_ef( &mut self, query: &Vector, k: usize, filter: Option<&MetadataFilter>, ef: Option<usize>, ) -> Result<Vec<(usize, f32, JsonValue)>>

Search with optional filter and ef override

pub fn search_with_options( &mut self, query: &Vector, k: usize, filter: Option<&MetadataFilter>, ef: Option<usize>, max_distance: Option<f32>, ) -> Result<Vec<(usize, f32, JsonValue)>>

Search with all options: filter, ef override, and max_distance

pub fn search_with_ef_readonly( &self, query: &Vector, k: usize, filter: Option<&MetadataFilter>, ef: Option<usize>, ) -> Result<Vec<(usize, f32, JsonValue)>>

Read-only search with optional filter (for parallel execution)

pub fn search_with_options_readonly( &self, query: &Vector, k: usize, filter: Option<&MetadataFilter>, ef: Option<usize>, max_distance: Option<f32>, ) -> Result<Vec<(usize, f32, JsonValue)>>

Read-only search with all options (for parallel execution)

pub fn search_batch( &self, queries: &[Vector], k: usize, ef: Option<usize>, ) -> Vec<Result<Vec<(usize, f32)>>>

Parallel batch search for multiple queries

pub fn search_batch_with_metadata( &self, queries: &[Vector], k: usize, ef: Option<usize>, ) -> Vec<Result<Vec<(usize, f32, JsonValue)>>>

Parallel batch search with metadata

pub fn knn_search_brute_force( &self, query: &Vector, k: usize, ) -> Result<Vec<(usize, f32)>>

Brute-force K-NN search (fallback)

pub fn optimize(&mut self) -> Result<usize>

Optimize index for cache-efficient search

Reorders graph nodes and vectors using BFS traversal to improve memory locality. Nodes that are frequently accessed together during search will be stored adjacently in memory, reducing cache misses and improving QPS.

Call this after loading/building the index and before querying for best results. Based on NeurIPS 2021 “Graph Reordering for Cache-Efficient Near Neighbor Search”.

Returns the number of nodes reordered, or 0 if index is empty/not initialized.

pub fn len(&self) -> usize

Number of vectors stored (excluding deleted vectors)

pub fn count(&self) -> usize

Count of vectors stored (excluding deleted vectors)

Alias for len() - preferred for database-style APIs.

pub fn is_empty(&self) -> bool

Check if store is empty

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

List all non-deleted IDs

Returns vector IDs without loading vector data. O(n) time, O(n) memory for strings only.

pub fn items(&self) -> Vec<(String, Vec<f32>, JsonValue)>

Get all items as (id, vector, metadata) tuples

Returns all non-deleted items. O(n) time and memory.

pub fn contains(&self, id: &str) -> bool

Check if an ID exists (not deleted)

pub fn memory_usage(&self) -> usize

Memory usage estimate (bytes)

pub fn bytes_per_vector(&self) -> f32

Bytes per vector (average)

pub fn set_ef_search(&mut self, ef_search: usize)

Set HNSW ef_search parameter (runtime tuning)

pub fn get_ef_search(&self) -> Option<usize>

Get HNSW ef_search parameter

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

Flush all pending changes to disk

Commits vector/metadata changes and HNSW index to .omen storage.

pub fn is_persistent(&self) -> bool

Check if this store has persistent storage enabled

pub fn storage(&self) -> Option<&OmenFile>

Get reference to the .omen storage backend (if persistent)