uqa_execution/operator_tree/
runtime.rs1use 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
32pub 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
75pub(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
92pub(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;