Skip to main content

VectorIndex

oxirs_vec::vector_index

Trait VectorIndex 

Source 
pub trait VectorIndex: Send + Sync {
    // Required methods
    fn insert(&mut self, uri: String, vector: Vector) -> Result<()>;
    fn search_knn(&self, query: &Vector, k: usize) -> Result<Vec<(String, f32)>>;
    fn search_threshold(
        &self,
        query: &Vector,
        threshold: f32,
    ) -> Result<Vec<(String, f32)>>;
    fn get_vector(&self, uri: &str) -> Option<&Vector>;

    // Provided methods
    fn add_vector(
        &mut self,
        id: VectorId,
        vector: Vector,
        _metadata: Option<HashMap<String, String>>,
    ) -> Result<()> { ... }
    fn update_vector(&mut self, id: VectorId, vector: Vector) -> Result<()> { ... }
    fn update_metadata(
        &mut self,
        _id: VectorId,
        _metadata: HashMap<String, String>,
    ) -> Result<()> { ... }
    fn remove_vector(&mut self, _id: VectorId) -> Result<()> { ... }
    fn iter_vectors(&self) -> Vec<(String, Vector)> { ... }
    fn supports_enumeration(&self) -> bool { ... }
}
Expand description

Vector index trait for efficient similarity search.

§Score contract (must be honored by every implementation)

All VectorIndex methods that return (id, score) tuples use similarity semantics, not raw distance:

  • The f32 score is a similarity: larger means more similar / closer.
  • VectorIndex::search_knn returns results sorted by descending similarity (best match first).
  • VectorIndex::search_threshold returns every vector whose similarity is >= threshold (i.e. the comparison is similarity >= threshold, never distance <= threshold).

This mirrors the public crate::VectorStore::similarity_search API and the reference MemoryVectorIndex implementation. Backends whose internal algorithm works in distance space (HNSW, LSH, memory-mapped, IVF, PQ, NSG) must convert their distances to a monotonically-decreasing similarity (the crate convention is similarity = 1.0 / (1.0 + distance)) before returning, so that all backends agree on units and ordering. A caller that dispatches the same logical query to different backends (e.g. DynamicIndexSelector) must be able to compare and re-rank the returned scores without knowing which backend produced them.

Required Methods§

Source

fn insert(&mut self, uri: String, vector: Vector) -> Result<()>

Insert a vector with associated URI

Source

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

Find the k nearest neighbors, returned as (id, similarity) sorted by descending similarity (best match first). See the trait-level score contract: the score is a similarity, not a distance.

Source

fn search_threshold( &self, query: &Vector, threshold: f32, ) -> Result<Vec<(String, f32)>>

Find all vectors whose similarity to query is >= threshold.

The score is a similarity (larger = closer), consistent with VectorIndex::search_knn; the filter is similarity >= threshold.

Source

fn get_vector(&self, uri: &str) -> Option<&Vector>

Get a vector by its URI

Provided Methods§

Source

fn add_vector( &mut self, id: VectorId, vector: Vector, _metadata: Option<HashMap<String, String>>, ) -> Result<()>

Add a vector with associated ID and metadata

Source

fn update_vector(&mut self, id: VectorId, vector: Vector) -> Result<()>

Update an existing vector

Source

fn update_metadata( &mut self, _id: VectorId, _metadata: HashMap<String, String>, ) -> Result<()>

Update metadata for a vector

Source

fn remove_vector(&mut self, _id: VectorId) -> Result<()>

Remove a vector by its ID

Source

fn iter_vectors(&self) -> Vec<(String, Vector)>

Iterate all stored (id, vector) pairs.

The default returns an empty list; concrete index types that hold their vectors in memory (or can reconstruct them, e.g. via decoding quantized codes) should override this and VectorIndex::supports_enumeration so callers like VectorStore::save_to_disk can tell real emptiness apart from “this index type cannot enumerate its vectors”.

Source

fn supports_enumeration(&self) -> bool

Whether VectorIndex::iter_vectors returns a real, complete enumeration of the vectors held by this index.

Index types that override iter_vectors with a real implementation (e.g. MemoryVectorIndex, HnswIndex, IvfIndex, PQIndex) must also override this to return true. Callers that need to persist or otherwise fully enumerate an index (e.g. VectorStore::save_to_disk) should check this flag and fail loudly instead of silently persisting an empty snapshot when it is false.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§