Struct VectorSearch

Source

pub struct VectorSearch { /* private fields */ }

Expand description

Vector search builder

Provides k-NN search with optional filtering and custom distance metrics.

§Example

use azoth::prelude::*;
use azoth_vector::{VectorSearch, Vector, DistanceMetric};

let db = AzothDb::open("./data")?;

let query = Vector::new(vec![0.1, 0.2, 0.3]);
let search = VectorSearch::new(db.projection().clone(), "embeddings", "vector")?
    .distance_metric(DistanceMetric::Cosine);

let results = search.knn(&query, 10).await?;

Implementations§

Source §

impl VectorSearch

Source

pub fn new( projection: Arc<SqliteProjectionStore>, table: impl Into<String>, column: impl Into<String>, ) -> Result<Self>

Create a new vector search builder

§Arguments

projection - The SQLite projection store
table - Table name containing the vector column (must be a valid SQL identifier)
column - Vector column name (must be a valid SQL identifier, initialized with vector_init)

§Errors

Returns an error if table or column contain characters other than ASCII alphanumeric and underscore, or don’t start with a letter/underscore.

Source

pub fn distance_metric(self, metric: DistanceMetric) -> Self

Set the distance metric

Default is Cosine similarity.

Source

pub async fn knn(&self, query: &Vector, k: usize) -> Result<Vec<SearchResult>>

Perform k-nearest neighbors search

Returns up to k results ordered by similarity (closest first).

§Example

let query_vector = Vector::new(vec![0.1, 0.2, 0.3]);
let results = search.knn(&query_vector, 10).await?;

for result in results {
    println!("Row {}: distance = {}", result.rowid, result.distance);
}

Source

pub async fn threshold( &self, query: &Vector, max_distance: f32, k: usize, ) -> Result<Vec<SearchResult>>

Search with distance threshold

Returns all results within the given distance threshold, up to k results.

§Example

let query = Vector::new(vec![0.1, 0.2, 0.3]);
// Only return results with cosine distance < 0.3 (similarity > 0.7)
let results = search.threshold(&query, 0.3, 100).await?;

Source

pub async fn knn_filtered( &self, query: &Vector, k: usize, filter: &VectorFilter, ) -> Result<Vec<SearchResult>>

Search with structured filter conditions

Allows filtering results by additional columns in the table using a type-safe VectorFilter builder. All column names are validated as safe SQL identifiers, and all values are bound via parameterized queries, preventing SQL injection by construction.

§Example

let query = Vector::new(vec![0.1, 0.2, 0.3]);

let filter = VectorFilter::new()
    .eq("category", "tech")
    .eq_i64("in_stock", 1);

let results = search.knn_filtered(&query, 10, &filter).await?;

Source

pub fn projection(&self) -> &Arc<SqliteProjectionStore>

Get multiple results by rowids and include their distances from query

Useful for retrieving full records after search.

§Example

let query = Vector::new(vec![0.1, 0.2, 0.3]);
let results = search.knn(&query, 10).await?;

// Get full records
for result in results {
    let record: String = search.projection()
        .query(|conn: &rusqlite::Connection| {
            conn.query_row(
                "SELECT content FROM embeddings WHERE rowid = ?",
                [result.rowid],
                |row: &rusqlite::Row| row.get(0),
            ).map_err(|e| azoth_core::error::AzothError::Projection(e.to_string()))
        })?;
    println!("Distance: {}, Content: {}", result.distance, record);
}