1use crate::operator_tree::{OperatorOutput, OperatorTreeDriver};
10use crate::parallel::ParallelExecutor;
11use crate::query::retrieval::combine_signal_priors;
12use crate::ScalarExpr;
13use std::collections::{BTreeMap, BTreeSet};
14use uqa_core::{
15 DocId, GeneralizedPostingList, Payload, PostingEntry, PostingList, Predicate, ScoredEntry,
16 Value,
17};
18use uqa_operators::{
19 BayesianEvidenceFusionOperator, DeepGraphDirection, ExternalPriorMode, GatingSpec,
20 MultiStageCutoff, MultiStageEntry, OperatorTree, RobustPositiveEvidencePoolOperator,
21 TextScoringMode,
22};
23use uqa_sql::{ast::ColumnType, SQLError, SQLParam};
24use uqa_storage::StorageBackendError;
25
26pub mod context;
27mod deep_layers;
28mod dispatch;
29mod filter;
30mod fusion;
31mod graph;
32mod graph_runtime;
33mod intersection;
34pub mod introspection;
35mod joins;
36mod phrase;
37pub mod posting;
38mod relation_context;
39mod relational;
40mod text_query;
41
42use context::PhysicalDriverContext;
43use deep_layers::{
44 deep_runtime_gating, lower_deep_batch_norm, lower_deep_conv, lower_deep_dense,
45 lower_deep_dropout, lower_deep_pool,
46};
47use graph_runtime::{
48 graph_pattern_from_ir, parse_rpq, restrict_result_to_source, temporal_filter_from_ir,
49 GraphNeighborAccess,
50};
51use introspection::{
52 collect_graph_names, first_structured_field, first_text_signal, require_graph_name,
53 require_shared_structured_field, require_shared_vector_field, require_text_field,
54 require_vector_field, scored_term_count,
55};
56use posting::{
57 fuse_signal_batches_with, fuse_signals_with, numeric_score, scored_to_posting_list,
58 sparse_threshold_inline, static_operator, StaticPostingList,
59};
60
61type DriverResult<T> = Result<T, SQLError>;
62
63#[derive(Clone, Copy)]
64struct WeightedPathExecution<'a> {
65 rpq_source: &'a str,
66 start_vertex: u64,
67 graph: &'a str,
68 weight_property: &'a str,
69 default_edge_weight: f64,
70 max_hops: usize,
71 predicate: &'a uqa_operators::PathWeightPredicate,
72 predicate_selectivity: f64,
73 score: f64,
74}
75
76#[derive(Clone, Copy)]
77pub struct HybridJoinFields<'a> {
78 pub left_structured: &'a str,
79 pub left_vector: &'a str,
80 pub right_structured: &'a str,
81 pub right_vector: &'a str,
82}
83
84#[derive(Clone, Copy)]
85struct PositiveEvidencePoolExecution<'a> {
86 signals: &'a [OperatorTree],
87 alpha: f64,
88 gating: &'a GatingSpec,
89 weights: Option<&'a [f64]>,
90 logit_min: Option<&'a [f64]>,
91 logit_max: Option<&'a [f64]>,
92 adaptive_weights: bool,
93}
94
95fn operator_execution_error(operator: &str, error: impl std::fmt::Display) -> SQLError {
96 SQLError::Internal(format!("execute {operator}: {error}"))
97}
98fn graph_execution_error(
99 operator: &str,
100 error: impl std::error::Error + Send + Sync + 'static,
101) -> SQLError {
102 crate::storage_errors::storage_error(
103 &format!("execute {operator}"),
104 &StorageBackendError::backend("graph", error),
105 )
106}
107
108pub struct PhysicalRetrievalDriver<'a> {
109 diagnostics: Option<crate::query::diagnostics::CapturedDiagnostics>,
110 pub context: PhysicalDriverContext<'a>,
111 pub table: &'a str,
112 signal_table: &'a str,
113 pub params: &'a [SQLParam],
114 pub parallel: ParallelExecutor,
115}
116
117impl<'a> PhysicalRetrievalDriver<'a> {
118 pub fn new(
119 context: PhysicalDriverContext<'a>,
120 table: &'a str,
121 signal_table: &'a str,
122 params: &'a [SQLParam],
123 ) -> Self {
124 Self {
125 diagnostics: context.runtime.diagnostics.capture(),
126 context,
127 table,
128 signal_table,
129 params,
130 parallel: ParallelExecutor::default(),
131 }
132 }
133
134 #[must_use]
135 pub fn with_parallel(mut self, parallel: ParallelExecutor) -> Self {
136 self.parallel = parallel;
137 self
138 }
139
140 fn bayesian_params_for(&self, field: &str) -> DriverResult<uqa_scoring::BayesianBM25Params> {
141 self.context
142 .text
143 .bayesian_params_for_relation(self.table, self.signal_table, field)
144 }
145
146 fn with_diagnostics<T>(&self, execute: impl FnOnce() -> DriverResult<T>) -> DriverResult<T> {
147 let _binding = self
148 .diagnostics
149 .as_ref()
150 .map(|collector| self.context.runtime.diagnostics.bind(collector))
151 .transpose()
152 .map_err(|error| {
153 crate::storage_errors::storage_error("bind vector diagnostics", &error)
154 })?;
155 execute()
156 }
157
158 fn execute_posting_node(&self, op: &OperatorTree) -> DriverResult<PostingList> {
159 match self.execute_node(op)? {
160 OperatorOutput::Posting(result) => Ok(result),
161 OperatorOutput::Graph(result) => Ok(result.to_posting_list()),
162 OperatorOutput::Generalized(_) => Err(SQLError::TypeMismatch(format!(
163 "{} produces tuple rows and cannot feed a single-document operator",
164 crate::operator_tree::operator_name(op)
165 ))),
166 }
167 }
168
169 fn execute_posting_branches(
170 &self,
171 branches: &[OperatorTree],
172 ) -> DriverResult<Vec<PostingList>> {
173 let workers: Vec<_> = branches
174 .iter()
175 .map(|branch| || self.with_diagnostics(|| self.execute_posting_node(branch)))
176 .collect();
177 self.parallel
178 .execute_branches(&workers)
179 .into_iter()
180 .collect()
181 }
182
183 fn execute_output_branches(
184 &self,
185 branches: &[OperatorTree],
186 ) -> DriverResult<Vec<OperatorOutput>> {
187 let workers: Vec<_> = branches
188 .iter()
189 .map(|branch| || self.with_diagnostics(|| self.execute_node(branch)))
190 .collect();
191 self.parallel
192 .execute_branches(&workers)
193 .into_iter()
194 .collect()
195 }
196
197 fn execute_term(
198 &self,
199 query: &str,
200 field: Option<&str>,
201 scoring: Option<TextScoringMode>,
202 top_k: Option<uqa_operators::TextTopKPlan>,
203 ) -> DriverResult<PostingList> {
204 let scoring = scoring.ok_or_else(|| {
205 SQLError::Internal(
206 "OperatorTree::Term reached PhysicalRetrievalDriver without bound text scoring"
207 .into(),
208 )
209 })?;
210 if let Some(field) = field {
211 self.context
212 .text
213 .validate_text_search_field(self.table, field)?;
214 let mode = match scoring {
215 TextScoringMode::BM25 => {
216 uqa_scoring::ScoringMode::BM25(uqa_scoring::BM25Params::default())
217 }
218 TextScoringMode::BayesianBM25 => {
219 uqa_scoring::ScoringMode::BayesianBM25(self.bayesian_params_for(field)?)
220 }
221 TextScoringMode::CustomBM25(params) => uqa_scoring::ScoringMode::BM25(params),
222 TextScoringMode::CustomBayesianBM25(params) => {
223 uqa_scoring::ScoringMode::BayesianBM25(params)
224 }
225 };
226 return self
227 .context
228 .text
229 .search_leaf(
230 self.table,
231 field,
232 query,
233 &mode,
234 top_k.map_or(usize::MAX, |plan| plan.k),
235 top_k,
236 )
237 .map(|rows| scored_to_posting_list(&rows));
238 }
239 if top_k.is_some() {
240 return Err(SQLError::Internal(
241 "physical text top-k requires one concrete field".into(),
242 ));
243 }
244 if matches!(
245 scoring,
246 TextScoringMode::CustomBM25(_) | TextScoringMode::CustomBayesianBM25(_)
247 ) {
248 return Err(SQLError::TypeMismatch(
249 "explicit text scoring parameters require one concrete field".into(),
250 ));
251 }
252 let fields = self.context.text.fts_fields_for_table(self.table)?;
253 if fields.is_empty() {
254 return Err(SQLError::TypeMismatch(format!(
255 "text search: table `{}` has no text-indexed columns",
256 self.table
257 )));
258 }
259 let mut by_document = BTreeMap::<DocId, f64>::new();
260 for field in fields {
261 let mode = match scoring {
262 TextScoringMode::BM25 => {
263 uqa_scoring::ScoringMode::BM25(uqa_scoring::BM25Params::default())
264 }
265 TextScoringMode::BayesianBM25 => {
266 uqa_scoring::ScoringMode::BayesianBM25(self.bayesian_params_for(&field)?)
267 }
268 TextScoringMode::CustomBM25(_) | TextScoringMode::CustomBayesianBM25(_) => {
269 return Err(SQLError::Internal(
270 "custom all-field scoring passed validation without a concrete field"
271 .into(),
272 ));
273 }
274 };
275 for entry in
276 self.context
277 .text
278 .search_leaf(self.table, &field, query, &mode, usize::MAX, None)?
279 {
280 by_document
281 .entry(entry.doc_id)
282 .and_modify(|score| *score = score.max(entry.score))
283 .or_insert(entry.score);
284 }
285 }
286 Ok(scored_to_posting_list(
287 &by_document
288 .into_iter()
289 .map(|(doc_id, score)| ScoredEntry { doc_id, score })
290 .collect::<Vec<_>>(),
291 ))
292 }
293
294 fn execute_knn(
295 &self,
296 query_vector: &[f32],
297 k: usize,
298 field: &str,
299 ) -> DriverResult<PostingList> {
300 self.require_vector_query(field, query_vector)?;
301 self.context
302 .vector
303 .knn_search_leaf(
304 self.table,
305 field,
306 query_vector,
307 k,
308 self.diagnostics.as_ref(),
309 )
310 .map(|rows| scored_to_posting_list(&rows))
311 }
312
313 fn execute_filter(
314 &self,
315 field: &str,
316 predicate: &Predicate,
317 source: Option<&OperatorTree>,
318 ) -> DriverResult<PostingList> {
319 self.require_column(field)?;
320 if let Some(indexed) = self.value_index_scan(field, predicate)? {
324 return match source {
325 Some(child) => self
326 .execute_posting_node(child)
327 .map(|posting| posting.merge_intersection_owned(&indexed)),
328 None => Ok(indexed),
329 };
330 }
331 let candidates: Vec<DocId> = match source {
332 Some(child) => {
333 let inner = self.execute_posting_node(child)?;
334 if let Some(read) = self.context.relations.serializable_read(self.table)? {
335 for entry in inner.entries() {
336 read.observe_row(entry.doc_id)?;
337 }
338 }
339 inner.entries().iter().map(|e| e.doc_id).collect()
340 }
341 None => self.scan_doc_ids()?,
342 };
343 self.evaluate_filter_candidates(
344 field,
345 predicate,
346 filter::Candidates::Documents(&candidates),
347 )
348 }
349
350 fn execute_filter_candidates(
352 &self,
353 field: &str,
354 predicate: &Predicate,
355 candidates: filter::Candidates<'_>,
356 ) -> DriverResult<PostingList> {
357 self.require_column(field)?;
358 if let Some(indexed) = self.value_index_scan(field, predicate)? {
359 return Ok(indexed);
360 }
361 if let Some(read) = self.context.relations.serializable_read(self.table)? {
362 read.observe_scan()?;
363 }
364 self.evaluate_filter_candidates(field, predicate, candidates)
365 }
366
367 fn evaluate_filter_candidates(
368 &self,
369 field: &str,
370 predicate: &Predicate,
371 candidates: filter::Candidates<'_>,
372 ) -> DriverResult<PostingList> {
373 filter::evaluate(
374 self.context.relations,
375 self.table,
376 field,
377 predicate,
378 candidates,
379 || self.context.runtime.check_cancelled(),
380 )
381 }
382
383 fn scan_doc_ids(&self) -> DriverResult<Vec<DocId>> {
385 if let Some(read) = self.context.relations.serializable_read(self.table)? {
386 read.observe_scan()?;
387 }
388 self.context.relations.table_doc_ids(self.table)
389 }
390}