1use super::{storage_sql_error, Engine, SQLError, ScoredEntry};
10
11impl Engine {
12 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 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 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 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 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 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}