Trait VectorStore 

pub trait VectorStore: Send + Sync {
    // Required methods
    fn ensure_collection(
        &self,
        collection: &str,
        vector_size: u64,
    ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>;
    fn collection_exists(
        &self,
        collection: &str,
    ) -> Pin<Box<dyn Future<Output = Result<bool, VectorStoreError>> + Send + '_>>;
    fn delete_collection(
        &self,
        collection: &str,
    ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>;
    fn upsert(
        &self,
        collection: &str,
        points: Vec<VectorPoint>,
    ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>;
    fn search_clamp_diagnostics(&self) -> (&'static str, &'static AtomicBool);
    fn search_clamped(
        &self,
        collection: &str,
        vector: Vec<f32>,
        limit: u64,
        filter: Option<VectorFilter>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<ScoredVectorPoint>, VectorStoreError>> + Send + '_>>;
    fn delete_by_ids(
        &self,
        collection: &str,
        ids: Vec<String>,
    ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>;
    fn scroll_all(
        &self,
        collection: &str,
        key_field: &str,
    ) -> Pin<Box<dyn Future<Output = Result<ScrollResult, VectorStoreError>> + Send + '_>>;
    fn scroll_all_with_point_ids(
        &self,
        collection: &str,
        key_field: &str,
    ) -> Pin<Box<dyn Future<Output = Result<ScrollWithIdsResult, VectorStoreError>> + Send + '_>>;
    fn health_check(
        &self,
    ) -> Pin<Box<dyn Future<Output = Result<bool, VectorStoreError>> + Send + '_>>;

    // Provided methods
    fn search(
        &self,
        collection: &str,
        vector: Vec<f32>,
        limit: u64,
        filter: Option<VectorFilter>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<ScoredVectorPoint>, VectorStoreError>> + Send + '_>> { ... }
    fn create_keyword_indexes(
        &self,
        _collection: &str,
        _fields: &[&str],
    ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>> { ... }
    fn get_points(
        &self,
        _collection: &str,
        _ids: Vec<String>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<VectorPoint>, VectorStoreError>> + Send + '_>> { ... }
}

Abstraction over a vector database backend.

Implementations must be Send + Sync so they can be wrapped in Arc and shared across async tasks. All methods return boxed futures via BoxFuture to remain object-safe.

Implementations

Type	Notes
crate::embedding_store::EmbeddingStore	Qdrant-backed; production default.
crate::db_vector_store::DbVectorStore	SQLite BLOB; offline / CI use.
crate::in_memory_store::InMemoryVectorStore	Fully in-process; unit tests.

Required Methods

fn ensure_collection( &self, collection: &str, vector_size: u64, ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>

Create a collection with cosine-distance vectors of vector_size dimensions.

Idempotent — no error if the collection already exists with the same dimension.

fn collection_exists( &self, collection: &str, ) -> Pin<Box<dyn Future<Output = Result<bool, VectorStoreError>> + Send + '_>>

Returns true if collection exists in the backend.

fn delete_collection( &self, collection: &str, ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>

Delete a collection and all its points.

fn upsert( &self, collection: &str, points: Vec<VectorPoint>, ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>

Upsert points into collection.

Points with existing IDs are overwritten; new IDs are inserted.

fn search_clamp_diagnostics(&self) -> (&'static str, &'static AtomicBool)

Per-implementor diagnostic label and “already warned” flag backing Self::search’s one-shot clamp warning.

Self::search is one shared default-method body invoked identically for every implementor, so a static declared directly inside it would be a single item shared by all implementors — Rust does not duplicate function-local statics per monomorphization, and a default method reached through dyn VectorStore compiles to one shared body regardless of the concrete backend behind it. For the same reason, a generic helper like std::any::type_name::<Self>() called from within that one shared body cannot distinguish implementors either. Each implementor must therefore supply its own label and flag here — a distinct &'static str identifying the concrete type (so an operator can tell which backend logged the warning) and a reference to a local static AtomicBool initialized to false — mirroring the per-call-site static already used by EmbeddingStore::search, EmbeddingRegistry::search_raw, and ReasoningMemory::search (see module docs).

The flag this returns is per-implementor-type, not per-instance: every Self value shares the one static declared in this method’s body. This crate’s own test suite currently has exactly one logs_contain(...)-asserting clamp test per implementor type, which is why that is safe today — a second such test against the same concrete type would silently race on this same flag (the identical #6686 hazard this method exists to prevent, just reintroduced one level up). If you add another oversized-limit clamp test for a type that already has one, give the existing test’s assertion double duty instead of adding a second one.

fn search_clamped( &self, collection: &str, vector: Vec<f32>, limit: u64, filter: Option<VectorFilter>, ) -> Pin<Box<dyn Future<Output = Result<Vec<ScoredVectorPoint>, VectorStoreError>> + Send + '_>>

Backend-specific search implementation invoked by Self::search.

Do not call directly — call Self::search, which clamps limit before delegating here. Implementors MUST NOT re-clamp limit; it is guaranteed to already be within [1, MAX_SEARCH_LIMIT]. Never call Self::search from here — it re-enters this method (infinite recursion).

fn delete_by_ids( &self, collection: &str, ids: Vec<String>, ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>

Delete specific points from collection by their string IDs.

fn scroll_all( &self, collection: &str, key_field: &str, ) -> Pin<Box<dyn Future<Output = Result<ScrollResult, VectorStoreError>> + Send + '_>>

Scroll (paginate) all points in collection and return a map of point_id → { key_field → value } payload entries.

fn scroll_all_with_point_ids( &self, collection: &str, key_field: &str, ) -> Pin<Box<dyn Future<Output = Result<ScrollWithIdsResult, VectorStoreError>> + Send + '_>>

Scroll all points in collection, returning (point_id, string_payload_fields) pairs.

Only points whose payload contains key_field as a string value are included. Unlike Self::scroll_all, the Qdrant point ID is preserved as the first tuple element rather than being used as the map key — this is required when consumers need to delete points by their IDs (e.g. stale-embedding cleanup).

Errors

Returns an error if the underlying scroll operation fails.

fn health_check( &self, ) -> Pin<Box<dyn Future<Output = Result<bool, VectorStoreError>> + Send + '_>>

Return true if the backend is reachable and operational.

Provided Methods

fn search( &self, collection: &str, vector: Vec<f32>, limit: u64, filter: Option<VectorFilter>, ) -> Pin<Box<dyn Future<Output = Result<Vec<ScoredVectorPoint>, VectorStoreError>> + Send + '_>>

Search collection for the limit nearest neighbours of vector.

Returns results in descending similarity order. An optional VectorFilter restricts the search space to points matching the payload conditions.

limit is clamped to [1, MAX_SEARCH_LIMIT] before delegating to Self::search_clamped — this is the sole choke point where the clamp is enforced, regardless of which implementor handles the call. Implementors MUST implement Self::search_clamped, not override this method; overriding search bypasses the clamp.

fn create_keyword_indexes( &self, _collection: &str, _fields: &[&str], ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>

Create keyword payload indexes for the given field names.

Default implementation is a no-op (for non-Qdrant backends).

fn get_points( &self, _collection: &str, _ids: Vec<String>, ) -> Pin<Box<dyn Future<Output = Result<Vec<VectorPoint>, VectorStoreError>> + Send + '_>>

Batched vector + payload retrieval by point IDs.

Returns one VectorPoint per matched id (missing ids are silently dropped). Backends that cannot return vectors return Err(VectorStoreError::Unsupported).

Errors

Returns VectorStoreError::Unsupported when the backend does not support direct point retrieval with vectors (e.g. DbVectorStore, InMemoryVectorStore unless overridden in tests).

Dyn Compatibility

This trait is dyn compatible.

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

Implementors

impl VectorStore for DbVectorStore

impl VectorStore for InMemoryVectorStore

impl VectorStore for QdrantOps