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