Skip to main content

uqa_execution/operator_tree/driver/
mod.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Physical retrieval operator dispatch, graph execution, joins and fusion.
8
9use 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        // Indexed columns resolve through the value index in
321        // O(log n + k); the index refuses predicates it cannot answer
322        // with evaluated-scan semantics, so this never changes results.
323        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    /// Restrict physical reads to intersection support while retaining the leaf's logical predicate observation.
351    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    /// Enumerating a relation is a logical scan even when a later predicate yields no postings. Index hydration and planner statistics do not use this execution boundary.
384    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}