Trait SearchBackend 

pub trait SearchBackend: Send {
    // Required methods
    fn ingest(
        &mut self,
        vectors: &[(VectorId, Vec<f32>)],
    ) -> Result<(), BackendError>;
    fn search(
        &self,
        query: &[f32],
        top_k: usize,
    ) -> Result<Vec<SearchResult>, BackendError>;
    fn remove(&mut self, vector_ids: &[VectorId]) -> Result<(), BackendError>;
    fn len(&self) -> usize;
    fn dim(&self) -> Option<usize>;

    // Provided method
    fn is_empty(&self) -> bool { ... }
}

The public contract every search backend must satisfy.

Implementors hold a mutable collection of (VectorId, Vec<f32>) pairs and expose a uniform ingest / search / remove interface. Backends may be in-process (brute-force) or remote (pgvector); the trait hides the difference from callers.

Thread safety

The trait requires Send so that backends can be moved between threads, e.g. wrapped in a Mutex<dyn SearchBackend>. Individual implementations may add Sync if they wish.

Errors

All methods return Result<_, BackendError>. The caller decides whether to treat BackendError::Empty as a soft empty result or a hard failure.

Required Methods

fn ingest( &mut self, vectors: &[(VectorId, Vec<f32>)], ) -> Result<(), BackendError>

Store the supplied (VectorId, Vec<f32>) pairs.

• Dimension-locks on the first non-empty call; subsequent calls with a different dimension return Err(BackendError::Adapter("dimension mismatch: expected {d}, got {got}")).
• Duplicate VectorIds overwrite the stored vector silently (Python parity).
• An empty slice is a no-op returning Ok(()).

Errors

Returns Err(BackendError::Adapter(_)) if the vectors’ dimension does not match the dimension locked by a previous ingest call.

fn search( &self, query: &[f32], top_k: usize, ) -> Result<Vec<SearchResult>, BackendError>

Return the top_k nearest vectors to query by cosine similarity, sorted descending.

• top_k == 0 → Err(BackendError::InvalidTopK).
• Empty backend → Ok(vec![]).
• If the backend contains fewer than top_k vectors, returns all of them sorted descending.

Errors

Returns Err(BackendError::InvalidTopK) when top_k == 0. Returns Err(BackendError::Adapter(_)) when the query dimension does not match the locked dimension, or on adapter-specific failures.

fn remove(&mut self, vector_ids: &[VectorId]) -> Result<(), BackendError>

Remove vectors by id.

Unknown ids are silently ignored (Python parity). An empty slice is a no-op returning Ok(()).

Errors

Returns Err(BackendError::Adapter(_)) on adapter-specific failures (e.g. a lost database connection). In-process backends always return Ok(()).

fn len(&self) -> usize

Number of vectors currently stored.

fn dim(&self) -> Option<usize>

The locked dimension, or None if no vectors have been ingested yet.

Provided Methods

fn is_empty(&self) -> bool

Returns true if no vectors are stored.

Implementors