Skip to main content

uqa_engine/search/
vector.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! KNN, calibrated vector, and similarity search.
8
9use super::{storage_sql_error, Engine, SQLError, ScoredEntry};
10
11impl Engine {
12    /// Top-`k` nearest neighbors against the named vector field.
13    pub(crate) fn knn_search_leaf(
14        &self,
15        table: &str,
16        field: &str,
17        query_vector: impl AsRef<[f32]>,
18        top_k: usize,
19        diagnostics: Option<&uqa_execution::query::diagnostics::CapturedDiagnostics>,
20    ) -> Result<Vec<ScoredEntry>, SQLError> {
21        if top_k == 0 {
22            return Ok(Vec::new());
23        }
24        let Some(t) = self
25            .try_query_table(table)
26            .map_err(|error| storage_sql_error("resolve vector-search table", error))?
27        else {
28            return Err(SQLError::UnknownTable(table.to_string()));
29        };
30        let vector_indexes = t.vector_indexes.read();
31        let Some(index) = vector_indexes.get(field) else {
32            return Err(SQLError::UnknownColumn(field.to_string()));
33        };
34        let pl = uqa_execution::serializable::vector::search_knn_with_diagnostics(
35            index,
36            self.serializable_table_read(table)?.as_ref(),
37            &t.columns.snapshot(),
38            field,
39            query_vector.as_ref(),
40            top_k,
41            diagnostics.map(|collector| (collector, table)),
42        )
43        .map_err(|error| storage_sql_error("execute KNN search", error))?;
44        Ok(uqa_scoring::rank_top_k(&pl, top_k))
45    }
46
47    /// Run KNN and query-pool calibration directly against the registered vector index so metadata validation does not materialize an unrelated full execution context.
48    pub(crate) fn query_pool_vector_search_leaf(
49        &self,
50        table: &str,
51        field: &str,
52        query_vector: impl AsRef<[f32]>,
53        top_k: usize,
54        diagnostics: Option<&uqa_execution::query::diagnostics::CapturedDiagnostics>,
55    ) -> Result<Vec<ScoredEntry>, SQLError> {
56        let query_vector = query_vector.as_ref();
57        if query_vector.is_empty() || query_vector.iter().any(|component| !component.is_finite()) {
58            return Err(SQLError::TypeMismatch(
59                "calibrated vector search requires a non-empty finite query vector".to_string(),
60            ));
61        }
62        if top_k == 0 {
63            return Ok(Vec::new());
64        }
65        let Some(table_state) = self
66            .try_query_table(table)
67            .map_err(|error| storage_sql_error("resolve calibrated-vector table", error))?
68        else {
69            return Err(SQLError::UnknownTable(table.to_string()));
70        };
71        let indexes = table_state.vector_indexes.read();
72        let index = indexes
73            .get(field)
74            .ok_or_else(|| SQLError::UnknownColumn(field.to_string()))?;
75        let raw = uqa_execution::serializable::vector::search_knn_with_diagnostics(
76            index,
77            self.serializable_table_read(table)?.as_ref(),
78            &table_state.columns.snapshot(),
79            field,
80            query_vector,
81            top_k,
82            diagnostics.map(|collector| (collector, table)),
83        )
84        .map_err(|error| storage_sql_error("execute calibrated-vector KNN", error))?;
85        let calibrated = uqa_operators::calibrate_query_pool_postings(
86            &raw,
87            uqa_operators::RelevantSampleSplit::default(),
88            0.5,
89        )
90        .map_err(|error| storage_sql_error("calibrate vector query pool", error))?;
91        Ok(uqa_scoring::rank_top_k(&calibrated, top_k))
92    }
93
94    /// Top-`k` nearest neighbors through the shared operator optimizer and
95    /// executor.
96    pub fn knn_search(
97        &self,
98        table: &str,
99        field: &str,
100        query_vector: impl AsRef<[f32]>,
101        top_k: usize,
102    ) -> Result<Vec<ScoredEntry>, SQLError> {
103        self.with_direct_table_read(table, |engine, name, _| {
104            let tree = uqa_operators::OperatorTree::KNN {
105                query_vector: query_vector.as_ref().to_vec(),
106                k: top_k,
107                field: field.to_string(),
108            };
109            let entries =
110                crate::operator_tree_bridge::execute_scored_tree(engine, name, table, &[], &tree)?;
111            Ok(uqa_scoring::rank_scored_entries_top_k(entries, top_k))
112        })
113    }
114
115    /// Obtain the actual `DiskANN` corpus and physical-generation versions for fitting a fixed calibration model. Embedding identity remains the caller's contract. This metadata read does not execute KNN or register a serializable vector predicate.
116    pub fn diskann_calibration_target(
117        &self,
118        table: &str,
119        field: &str,
120        embedding_model_id: &str,
121        embedding_model_version: &str,
122        candidate_k: usize,
123    ) -> Result<uqa_scoring::VectorCalibrationTarget, SQLError> {
124        self.with_direct_table_read(table, |engine, table_name, table| {
125            let indexes = table.vector_indexes.read();
126            let index = indexes
127                .get(field)
128                .ok_or_else(|| SQLError::UnknownColumn(field.into()))?;
129            let control = engine.query_retention_control()?;
130            uqa_execution::query::vector_calibration::diskann_target(
131                index,
132                table_name,
133                field,
134                (embedding_model_id, embedding_model_version),
135                candidate_k,
136                &control,
137            )
138        })
139    }
140
141    /// Apply a persisted/offline vector calibration model to a KNN pool.
142    ///
143    /// Unlike `calibrated_vector_match`, this path never fits parameters from the current query's top-K results. The target must match the model provenance, physical table/field, index kind, dimensions and candidate K. For `DiskANN`, obtain actual corpus/generation versions with [`Self::diskann_calibration_target`]; execution revalidates them against the same retained index used for KNN. Embedding identity and other index methods' version labels remain explicit caller contracts.
144    pub fn calibrated_vector_search_with_model(
145        &self,
146        table: &str,
147        field: &str,
148        query_vector: impl AsRef<[f32]>,
149        model: &uqa_scoring::VectorCalibrationModel,
150        target: &uqa_scoring::VectorCalibrationTarget,
151    ) -> Result<Vec<ScoredEntry>, SQLError> {
152        self.with_direct_table_read(table, |engine, table_name, table| {
153            uqa_execution::query::vector_calibration::validate_names(
154                model, target, table_name, field,
155            )?;
156
157            let indexes = table.vector_indexes.read();
158            let index = indexes
159                .get(field)
160                .ok_or_else(|| SQLError::UnknownColumn(field.to_string()))?;
161            let control = engine.query_retention_control()?;
162            let retained = if index.index_kind() == "diskann" {
163                Some(index.snapshot_with_control(&control).map_err(|error| {
164                    storage_sql_error("retain calibrated-vector selection", error)
165                })?)
166            } else {
167                None
168            };
169            let index = retained.as_deref().unwrap_or(index);
170            uqa_execution::query::vector_calibration::validate_index(index, target, &control)?;
171            let captured = engine.runtime.diagnostics.capture();
172            let raw = uqa_execution::serializable::vector::search_knn_with_diagnostics(
173                index,
174                engine.serializable_table_state_read(table)?.as_ref(),
175                &table.columns.snapshot(),
176                field,
177                query_vector.as_ref(),
178                target.candidate_k,
179                captured.as_ref().map(|collector| (collector, table_name)),
180            )
181            .map_err(|error| storage_sql_error("execute calibrated-vector KNN", error))?;
182            model
183                .calibrate_postings(&raw, target)
184                .map_err(|error| SQLError::Internal(error.to_string()))
185        })
186    }
187
188    /// All documents whose cosine similarity to `query_vector` is at least
189    /// `threshold`.
190    pub fn vector_similarity_search(
191        &self,
192        table: &str,
193        field: &str,
194        query_vector: Vec<f32>,
195        threshold: f32,
196    ) -> Result<Vec<ScoredEntry>, SQLError> {
197        self.with_direct_table_read(table, |engine, name, _| {
198            let tree = uqa_operators::OperatorTree::VectorSimilarity {
199                query_vector,
200                threshold,
201                field: field.to_string(),
202            };
203            let mut out =
204                crate::operator_tree_bridge::execute_scored_tree(engine, name, table, &[], &tree)?;
205            out.sort_by(|a, b| {
206                b.score
207                    .total_cmp(&a.score)
208                    .then_with(|| a.doc_id.cmp(&b.doc_id))
209            });
210            Ok(out)
211        })
212    }
213}