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
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        // Indexed columns resolve through the value index in
279        // O(log n + k); the index refuses predicates it cannot answer
280        // with evaluated-scan semantics, so this never changes results.
281        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    /// Restrict physical reads to intersection support while retaining the leaf's logical predicate observation.
309    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    /// 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.
342    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}