Skip to main content

uqa_execution/scalar/
plan.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Physical expression plans and query-backed subquery evaluation.
8
9use uqa_core::Value;
10use uqa_sql::expr::{EngineHook, RowLookup};
11use uqa_sql::plan::{ExpressionPlan, QueryPlan};
12use uqa_sql::{ResultRow, SQLError, SQLParam};
13
14use crate::{
15    eval_scalar, PhysicalRow, RowSchema, ScalarEvalContext, ScalarExpr, ScalarSubqueryRunner,
16    SubqueryId, SubqueryResult,
17};
18
19/// Expression services needed by physical grouping and window operators.
20/// Implementations retain statement scope without exposing catalog mutation or engine state.
21pub trait QueryExpressionContext:
22    EngineHook + PhysicalSubqueryRunner + crate::functions::AggregateFunctionRegistry
23{
24    fn expression_evaluator<'a>(
25        &'a self,
26        params: &'a [SQLParam],
27    ) -> Result<crate::SharedExpressionEvaluator<'a>, SQLError>;
28
29    fn subquery_plans(&self) -> &[QueryPlan];
30}
31
32pub trait PhysicalSubqueryRunner {
33    fn execute_subquery(
34        &self,
35        subquery: SubqueryId,
36        plan: &QueryPlan,
37        outer_row: PhysicalOuterRow<'_>,
38        params: &[SQLParam],
39    ) -> Result<SubqueryResult, SQLError>;
40
41    fn row_subquery_value(
42        &self,
43        subquery: SubqueryId,
44        plan: &QueryPlan,
45        outer_row: PhysicalOuterRow<'_>,
46        params: &[SQLParam],
47    ) -> Result<Option<crate::OwnedPhysicalRow>, SQLError> {
48        self.execute_subquery(subquery, plan, outer_row, params)?
49            .into_single_row()
50    }
51
52    fn scalar_subquery_value(
53        &self,
54        subquery: SubqueryId,
55        plan: &QueryPlan,
56        outer_row: PhysicalOuterRow<'_>,
57        params: &[SQLParam],
58    ) -> Result<Value, SQLError> {
59        self.execute_subquery(subquery, plan, outer_row, params)?
60            .into_scalar_value()
61    }
62
63    fn subquery_exists(
64        &self,
65        subquery: SubqueryId,
66        plan: &QueryPlan,
67        outer_row: PhysicalOuterRow<'_>,
68        params: &[SQLParam],
69    ) -> Result<bool, SQLError> {
70        self.execute_subquery(subquery, plan, outer_row, params)?
71            .into_exists()
72    }
73
74    fn subquery_contains_selected(
75        &self,
76        subquery: SubqueryId,
77        plan: &QueryPlan,
78        needle: crate::scalar::SubqueryNeedle<'_>,
79        outer_row: PhysicalOuterRow<'_>,
80        params: &[SQLParam],
81    ) -> Result<Option<bool>, SQLError> {
82        needle.control.check()?;
83        self.execute_subquery(subquery, plan, outer_row, params)?
84            .contains_with_engine_and_control(needle.value, needle.engine, &needle.control)
85    }
86
87    fn subquery_contains(
88        &self,
89        subquery: SubqueryId,
90        plan: &QueryPlan,
91        needle: &Value,
92        outer_row: PhysicalOuterRow<'_>,
93        params: &[SQLParam],
94    ) -> Result<Option<bool>, SQLError> {
95        self.execute_subquery(subquery, plan, outer_row, params)?
96            .contains(needle)
97    }
98}
99
100#[derive(Clone, Copy)]
101pub enum PhysicalOuterRow<'a> {
102    Absent,
103    Physical {
104        schema: &'a RowSchema,
105        row: &'a PhysicalRow,
106    },
107}
108
109impl PhysicalOuterRow<'_> {
110    pub fn is_some(self) -> bool {
111        matches!(self, Self::Physical { .. })
112    }
113}
114
115pub struct PhysicalEvalContext<'a> {
116    row: Option<&'a ResultRow>,
117    row_lookup: Option<&'a dyn RowLookup>,
118    row_schema: Option<&'a RowSchema>,
119    params: &'a [SQLParam],
120    function_hook: Option<&'a dyn EngineHook>,
121    subquery_runner: Option<&'a dyn PhysicalSubqueryRunner>,
122    physical_outer_row: Option<(&'a RowSchema, &'a PhysicalRow)>,
123    retrieval_predicate: Option<&'a super::context::RetrievalPredicate<'a>>,
124    function_states: Option<&'a super::FunctionCallStates>,
125}
126
127impl<'a> PhysicalEvalContext<'a> {
128    pub fn new(row: Option<&'a ResultRow>, params: &'a [SQLParam]) -> Self {
129        Self {
130            row,
131            row_lookup: row.map(|row| row as &dyn RowLookup),
132            row_schema: None,
133            params,
134            function_hook: None,
135            subquery_runner: None,
136            physical_outer_row: None,
137            retrieval_predicate: None,
138            function_states: None,
139        }
140    }
141
142    pub fn from_row_lookup(row: &'a dyn RowLookup, params: &'a [SQLParam]) -> Self {
143        Self {
144            row: None,
145            row_lookup: Some(row),
146            row_schema: None,
147            params,
148            function_hook: None,
149            subquery_runner: None,
150            physical_outer_row: None,
151            retrieval_predicate: None,
152            function_states: None,
153        }
154    }
155
156    pub fn with_function_hook(mut self, hook: &'a dyn EngineHook) -> Self {
157        self.function_hook = Some(hook);
158        self
159    }
160
161    pub fn with_function_states(mut self, states: &'a super::FunctionCallStates) -> Self {
162        self.function_states = Some(states);
163        self
164    }
165
166    pub(crate) fn with_retrieval_predicate(
167        mut self,
168        predicate: &'a super::context::RetrievalPredicate<'a>,
169    ) -> Self {
170        self.retrieval_predicate = Some(predicate);
171        self
172    }
173
174    pub fn with_row_schema(mut self, schema: &'a RowSchema) -> Self {
175        self.row_schema = Some(schema);
176        self
177    }
178
179    pub fn with_subquery_runner(mut self, runner: &'a dyn PhysicalSubqueryRunner) -> Self {
180        self.subquery_runner = Some(runner);
181        self
182    }
183
184    pub fn with_physical_outer_row(mut self, schema: &'a RowSchema, row: &'a PhysicalRow) -> Self {
185        self.physical_outer_row = Some((schema, row));
186        self
187    }
188}
189
190pub fn eval_physical(
191    expression: &ExpressionPlan,
192    context: &PhysicalEvalContext<'_>,
193) -> Result<Value, SQLError> {
194    eval_physical_scalar(&expression.scalar, &expression.subqueries, context)
195}
196
197pub fn eval_physical_call_arguments(
198    arguments: &[ExpressionPlan],
199    context: &PhysicalEvalContext<'_>,
200) -> Result<Vec<(Option<String>, Value)>, SQLError> {
201    let (decoded, _) = analyze_physical_call_arguments(arguments)?;
202    arguments
203        .iter()
204        .zip(decoded)
205        .map(|(plan, argument)| {
206            Ok((
207                argument.name.map(str::to_string),
208                eval_physical_scalar(argument.value, &plan.subqueries, context)?,
209            ))
210        })
211        .collect()
212}
213
214pub use uqa_sql::ir::analyze_expression_call_arguments as analyze_physical_call_arguments;
215
216pub fn eval_physical_scalar(
217    expression: &ScalarExpr,
218    subqueries: &[QueryPlan],
219    context: &PhysicalEvalContext<'_>,
220) -> Result<Value, SQLError> {
221    let subqueries = PlanSubqueryArena::new(subqueries, context.subquery_runner);
222    let mut scalar_context = context.row_lookup.map_or_else(
223        || ScalarEvalContext::new(context.row, context.params),
224        |row| ScalarEvalContext::from_row_lookup(row, context.params),
225    );
226    if let Some(hook) = context.function_hook {
227        scalar_context = scalar_context.with_function_hook(hook);
228    }
229    if let Some(states) = context.function_states {
230        scalar_context = scalar_context.with_function_states(states);
231    }
232    if let Some(predicate) = context.retrieval_predicate {
233        scalar_context = scalar_context.with_retrieval_predicate(predicate);
234    }
235    if let Some(schema) = context.row_schema {
236        scalar_context = scalar_context.with_row_schema(schema);
237    }
238    if context.subquery_runner.is_some() {
239        scalar_context = scalar_context.with_subquery_runner(&subqueries);
240    }
241    if let Some((schema, row)) = context.physical_outer_row {
242        scalar_context = scalar_context.with_physical_outer_row(schema, row);
243    }
244    eval_scalar(expression, &scalar_context)
245}
246
247pub struct PlanSubqueryArena<'a> {
248    plans: &'a [QueryPlan],
249    runner: Option<&'a dyn PhysicalSubqueryRunner>,
250}
251
252impl<'a> PlanSubqueryArena<'a> {
253    pub fn new(plans: &'a [QueryPlan], runner: Option<&'a dyn PhysicalSubqueryRunner>) -> Self {
254        Self { plans, runner }
255    }
256}
257
258impl ScalarSubqueryRunner for PlanSubqueryArena<'_> {
259    fn execute_subquery(
260        &self,
261        subquery: SubqueryId,
262        _outer_row: Option<&dyn RowLookup>,
263        params: &[SQLParam],
264    ) -> Result<SubqueryResult, SQLError> {
265        let plan = self.plans.get(subquery).ok_or_else(|| {
266            SQLError::Internal(format!(
267                "physical scalar subquery slot {subquery} is out of bounds"
268            ))
269        })?;
270        self.runner
271            .ok_or_else(|| {
272                SQLError::Unsupported("physical subquery requires a plan runner".into())
273            })?
274            .execute_subquery(subquery, plan, PhysicalOuterRow::Absent, params)
275    }
276
277    fn execute_subquery_physical(
278        &self,
279        subquery: SubqueryId,
280        outer_schema: &RowSchema,
281        outer_row: &PhysicalRow,
282        params: &[SQLParam],
283    ) -> Result<SubqueryResult, SQLError> {
284        let plan = self.plan(subquery)?;
285        self.runner()?.execute_subquery(
286            subquery,
287            plan,
288            PhysicalOuterRow::Physical {
289                schema: outer_schema,
290                row: outer_row,
291            },
292            params,
293        )
294    }
295
296    fn scalar_subquery_value(
297        &self,
298        subquery: SubqueryId,
299        _outer_row: Option<&dyn RowLookup>,
300        params: &[SQLParam],
301    ) -> Result<Value, SQLError> {
302        let plan = self.plan(subquery)?;
303        self.runner()?
304            .scalar_subquery_value(subquery, plan, PhysicalOuterRow::Absent, params)
305    }
306
307    fn scalar_subquery_value_physical(
308        &self,
309        subquery: SubqueryId,
310        outer_schema: &RowSchema,
311        outer_row: &PhysicalRow,
312        params: &[SQLParam],
313    ) -> Result<Value, SQLError> {
314        let plan = self.plan(subquery)?;
315        self.runner()?.scalar_subquery_value(
316            subquery,
317            plan,
318            PhysicalOuterRow::Physical {
319                schema: outer_schema,
320                row: outer_row,
321            },
322            params,
323        )
324    }
325
326    fn subquery_exists(
327        &self,
328        subquery: SubqueryId,
329        _outer_row: Option<&dyn RowLookup>,
330        params: &[SQLParam],
331    ) -> Result<bool, SQLError> {
332        let plan = self.plan(subquery)?;
333        self.runner()?
334            .subquery_exists(subquery, plan, PhysicalOuterRow::Absent, params)
335    }
336
337    fn subquery_exists_physical(
338        &self,
339        subquery: SubqueryId,
340        outer_schema: &RowSchema,
341        outer_row: &PhysicalRow,
342        params: &[SQLParam],
343    ) -> Result<bool, SQLError> {
344        let plan = self.plan(subquery)?;
345        self.runner()?.subquery_exists(
346            subquery,
347            plan,
348            PhysicalOuterRow::Physical {
349                schema: outer_schema,
350                row: outer_row,
351            },
352            params,
353        )
354    }
355
356    fn subquery_contains_selected(
357        &self,
358        subquery: SubqueryId,
359        needle: crate::scalar::SubqueryNeedle<'_>,
360        _outer_row: Option<&dyn RowLookup>,
361        params: &[SQLParam],
362    ) -> Result<Option<bool>, SQLError> {
363        let plan = self.plan(subquery)?;
364        self.runner()?.subquery_contains_selected(
365            subquery,
366            plan,
367            needle,
368            PhysicalOuterRow::Absent,
369            params,
370        )
371    }
372
373    fn subquery_contains_selected_physical(
374        &self,
375        subquery: SubqueryId,
376        needle: crate::scalar::SubqueryNeedle<'_>,
377        outer_schema: &RowSchema,
378        outer_row: &PhysicalRow,
379        params: &[SQLParam],
380    ) -> Result<Option<bool>, SQLError> {
381        let plan = self.plan(subquery)?;
382        self.runner()?.subquery_contains_selected(
383            subquery,
384            plan,
385            needle,
386            PhysicalOuterRow::Physical {
387                schema: outer_schema,
388                row: outer_row,
389            },
390            params,
391        )
392    }
393
394    fn subquery_contains(
395        &self,
396        subquery: SubqueryId,
397        needle: &Value,
398        _outer_row: Option<&dyn RowLookup>,
399        params: &[SQLParam],
400    ) -> Result<Option<bool>, SQLError> {
401        let plan = self.plan(subquery)?;
402        self.runner()?
403            .subquery_contains(subquery, plan, needle, PhysicalOuterRow::Absent, params)
404    }
405
406    fn subquery_contains_physical(
407        &self,
408        subquery: SubqueryId,
409        needle: &Value,
410        outer_schema: &RowSchema,
411        outer_row: &PhysicalRow,
412        params: &[SQLParam],
413    ) -> Result<Option<bool>, SQLError> {
414        let plan = self.plan(subquery)?;
415        self.runner()?.subquery_contains(
416            subquery,
417            plan,
418            needle,
419            PhysicalOuterRow::Physical {
420                schema: outer_schema,
421                row: outer_row,
422            },
423            params,
424        )
425    }
426}
427
428impl PlanSubqueryArena<'_> {
429    fn plan(&self, subquery: SubqueryId) -> Result<&QueryPlan, SQLError> {
430        self.plans.get(subquery).ok_or_else(|| {
431            SQLError::Internal(format!(
432                "physical scalar subquery slot {subquery} is out of bounds"
433            ))
434        })
435    }
436
437    fn runner(&self) -> Result<&dyn PhysicalSubqueryRunner, SQLError> {
438        self.runner
439            .ok_or_else(|| SQLError::Unsupported("physical subquery requires a plan runner".into()))
440    }
441}
442
443#[cfg(test)]
444mod tests {
445    use uqa_core::Value;
446    use uqa_sql::ast::{BinaryOp, Expr, FunctionBinding, FunctionDispatch};
447    use uqa_sql::plan::ExpressionPlan;
448    use uqa_sql::SQLParam;
449
450    use super::{
451        analyze_physical_call_arguments, eval_physical, eval_physical_call_arguments,
452        PhysicalEvalContext,
453    };
454
455    #[test]
456    fn physical_expression_plan_evaluates_the_scalar_field() {
457        let expression = ExpressionPlan::lower(Expr::Binary {
458            op: BinaryOp::Multiply,
459            lhs: Box::new(Expr::Param(1)),
460            rhs: Box::new(Expr::Literal(Value::Int(3))),
461        });
462        let params = [SQLParam::Scalar(Value::Int(7))];
463        assert_eq!(
464            eval_physical(&expression, &PhysicalEvalContext::new(None, &params)).unwrap(),
465            Value::Int(21)
466        );
467    }
468
469    #[test]
470    fn physical_call_arguments_preserve_and_unwrap_explicit_variadic_syntax() {
471        let variadic_binding = FunctionBinding::dispatched(FunctionDispatch::VariadicArgument);
472        let variadic = Expr::Func {
473            order_syntax: uqa_sql::ast::FunctionOrderSyntax::Ordinary,
474            name: variadic_binding.name.clone(),
475            binding: Some(variadic_binding),
476            args: vec![Expr::Literal(Value::Int(42))],
477            distinct: false,
478            order_by: Vec::new(),
479            filter: None,
480        };
481        let named_binding = FunctionBinding::dispatched(FunctionDispatch::NamedArgument);
482        let named = Expr::Func {
483            order_syntax: uqa_sql::ast::FunctionOrderSyntax::Ordinary,
484            name: named_binding.name.clone(),
485            binding: Some(named_binding),
486            args: vec![Expr::Literal(Value::Str("items".into())), variadic],
487            distinct: false,
488            order_by: Vec::new(),
489            filter: None,
490        };
491        let arguments = vec![ExpressionPlan::lower(named)];
492
493        let (decoded, explicit_variadic) = analyze_physical_call_arguments(&arguments).unwrap();
494        assert!(explicit_variadic);
495        assert_eq!(decoded[0].name, Some("items"));
496        assert_eq!(
497            eval_physical_call_arguments(&arguments, &PhysicalEvalContext::new(None, &[]),)
498                .unwrap(),
499            vec![(Some("items".into()), Value::Int(42))]
500        );
501    }
502}