Skip to main content

uqa_execution/operator_tree/
runtime.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Retrieval-tree optimization, active-statement checks and physical execution.
8
9use super::driver::{context::PhysicalDriverContext, PhysicalRetrievalDriver};
10use super::{OperatorOutput, PlanExecutor};
11use uqa_core::PostingList;
12use uqa_operators::{OperatorTree, TextScoringMode};
13use uqa_sql::{SQLError, SQLParam};
14
15type DriverResult<T> = Result<T, SQLError>;
16
17pub trait RetrievalPlanOptimizer: Sync {
18    fn optimize(&self, table: &str, tree: &OperatorTree) -> DriverResult<OperatorTree>;
19}
20
21pub trait RetrievalTransactionState: Sync {
22    fn transaction_depth(&self) -> usize;
23}
24
25#[derive(Clone, Copy)]
26pub struct TreeExecutionContext<'a> {
27    pub driver: PhysicalDriverContext<'a>,
28    pub optimizer: &'a dyn RetrievalPlanOptimizer,
29    pub transaction: &'a dyn RetrievalTransactionState,
30}
31
32/// Execute below an existing statement boundary; calibration must already have a transaction.
33pub fn execute_tree(
34    context: &TreeExecutionContext<'_>,
35    table: &str,
36    signal_table: &str,
37    params: &[SQLParam],
38    tree: &OperatorTree,
39) -> DriverResult<OperatorOutput> {
40    if context.transaction.transaction_depth() == 0 && tree_may_persist_calibration(tree) {
41        return Err(SQLError::Internal(
42            "calibrating operator execution requires an active statement transaction".into(),
43        ));
44    }
45    optimize_and_execute_tree(context, table, signal_table, params, tree)
46}
47
48pub fn optimize_and_execute_tree(
49    context: &TreeExecutionContext<'_>,
50    table: &str,
51    signal_table: &str,
52    params: &[SQLParam],
53    tree: &OperatorTree,
54) -> DriverResult<OperatorOutput> {
55    validate_text_top_k_placement(tree)?;
56    let optimized = context.optimizer.optimize(table, tree)?;
57    execute_physical_tree(context, table, signal_table, params, &optimized)
58}
59
60pub fn execute_preoptimized_tree(
61    context: &TreeExecutionContext<'_>,
62    table: &str,
63    signal_table: &str,
64    params: &[SQLParam],
65    tree: &OperatorTree,
66) -> DriverResult<OperatorOutput> {
67    if context.transaction.transaction_depth() == 0 && tree_may_persist_calibration(tree) {
68        return Err(SQLError::Internal(
69            "calibrating operator execution requires an active statement transaction".into(),
70        ));
71    }
72    execute_physical_tree(context, table, signal_table, params, tree)
73}
74
75/// Optimize a relation-local tree at its ordinary active-statement boundary and capture eligible complete text scores before row delivery.
76pub(super) fn execute_captured_tree(
77    context: &TreeExecutionContext<'_>,
78    table: &str,
79    params: &[SQLParam],
80    tree: &OperatorTree,
81) -> DriverResult<crate::query::scored_input::ProducedScoredEntries> {
82    if context.transaction.transaction_depth() == 0 && tree_may_persist_calibration(tree) {
83        return Err(SQLError::Internal(
84            "calibrating operator execution requires an active statement transaction".into(),
85        ));
86    }
87    validate_text_top_k_placement(tree)?;
88    let optimized = context.optimizer.optimize(table, tree)?;
89    capture_scored_entries(context, table, table, params, &optimized, true)
90}
91
92/// Consume complete retrieval into its bounded SQL input owner when its score-only tree has direct cursors.
93pub(super) fn execute_preoptimized_scored_entries(
94    context: &TreeExecutionContext<'_>,
95    table: &str,
96    signal_table: &str,
97    params: &[SQLParam],
98    tree: &OperatorTree,
99    capture_complete_scores: bool,
100) -> DriverResult<crate::query::scored_input::ProducedScoredEntries> {
101    if context.transaction.transaction_depth() == 0 && tree_may_persist_calibration(tree) {
102        return Err(SQLError::Internal(
103            "calibrating operator execution requires an active statement transaction".into(),
104        ));
105    }
106    capture_scored_entries(
107        context,
108        table,
109        signal_table,
110        params,
111        tree,
112        capture_complete_scores,
113    )
114}
115
116fn capture_scored_entries(
117    context: &TreeExecutionContext<'_>,
118    table: &str,
119    signal_table: &str,
120    params: &[SQLParam],
121    tree: &OperatorTree,
122    capture_complete_scores: bool,
123) -> DriverResult<crate::query::scored_input::ProducedScoredEntries> {
124    validate_text_top_k_placement(tree)?;
125    let driver = PhysicalRetrievalDriver::new(context.driver, table, signal_table, params);
126    if capture_complete_scores {
127        if let Some(entries) = driver.capture_scored_input(tree)? {
128            return Ok(crate::query::scored_input::ProducedScoredEntries::Captured(
129                entries,
130            ));
131        }
132    }
133    let output = PlanExecutor::new(&driver).execute(tree)?;
134    let posting = expect_posting_output(output, "SQL WHERE")?;
135    Ok(super::driver::posting::posting_list_to_scored(&posting).into())
136}
137
138fn execute_physical_tree(
139    context: &TreeExecutionContext<'_>,
140    table: &str,
141    signal_table: &str,
142    params: &[SQLParam],
143    tree: &OperatorTree,
144) -> DriverResult<OperatorOutput> {
145    validate_text_top_k_placement(tree)?;
146    let driver = PhysicalRetrievalDriver::new(context.driver, table, signal_table, params);
147    let mut executor = PlanExecutor::new(&driver);
148    executor.execute(tree)
149}
150
151fn validate_text_top_k_placement(tree: &OperatorTree) -> DriverResult<()> {
152    let root_is_physical_text = matches!(tree, OperatorTree::Term { top_k: Some(_), .. });
153    let mut physical_text_nodes = 0_usize;
154    tree.visit(&mut |node| {
155        if matches!(node, OperatorTree::Term { top_k: Some(_), .. }) {
156            physical_text_nodes += 1;
157        }
158    });
159    if physical_text_nodes == usize::from(root_is_physical_text) {
160        Ok(())
161    } else {
162        Err(SQLError::Internal(
163            "physical text top-k is valid only as the root retrieval leaf".into(),
164        ))
165    }
166}
167
168pub fn tree_may_persist_calibration(tree: &OperatorTree) -> bool {
169    let mut may_persist = false;
170    tree.visit(&mut |node| {
171        may_persist |= matches!(
172            node,
173            OperatorTree::BayesianScore { .. }
174                | OperatorTree::Term {
175                    scoring: Some(TextScoringMode::BayesianBM25),
176                    ..
177                }
178                | OperatorTree::Phrase {
179                    scoring: Some(TextScoringMode::BayesianBM25),
180                    ..
181                }
182                | OperatorTree::BayesianMatchWithPrior { .. }
183                | OperatorTree::MultiFieldSearch { .. }
184        );
185    });
186    may_persist
187}
188
189pub fn expect_posting_output(output: OperatorOutput, context: &str) -> DriverResult<PostingList> {
190    match output {
191        OperatorOutput::Posting(result) => Ok(result),
192        OperatorOutput::Graph(result) => Ok(result.to_posting_list()),
193        OperatorOutput::Generalized(_) => Err(SQLError::TypeMismatch(format!(
194            "{context} requires single-document rows, but the physical plan produced join tuples"
195        ))),
196    }
197}
198
199#[cfg(test)]
200mod tests;