Skip to main content

uqa_execution/query/
expression.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Shared expression evaluation for physical filters, projections, and sorts.
8
9use crate::scalar::plan::{eval_physical_scalar, PhysicalEvalContext, QueryExpressionContext};
10use crate::{
11    ExecResult, ExpressionEvaluator, FunctionTypeResolver, RowSchemaExecution, ScalarExpr,
12    SharedExpressionEvaluator,
13};
14use std::sync::Arc;
15use uqa_core::{
16    memory::{MemoryReservation, ProductionControl},
17    Value,
18};
19use uqa_sql::{expr::RowLookup, SQLError, SQLParam};
20
21mod outer;
22#[cfg(test)]
23mod tests;
24pub(crate) use outer::with_outer_row_with_control;
25
26/// Scalar execution services that can intercept a function requiring its unevaluated argument expressions.
27pub trait ScalarExpressionContext: QueryExpressionContext {
28    fn intercept_function(
29        &self,
30        name: &str,
31        args: &[ScalarExpr],
32        row: &dyn RowLookup,
33        evaluate: &mut dyn FnMut(&ScalarExpr) -> Result<Value, SQLError>,
34    ) -> Result<Option<Value>, SQLError>;
35}
36
37pub struct ScopedExpressionEvaluator<'a> {
38    context: ExpressionContext<'a>,
39    params: &'a [SQLParam],
40    cancellation: uqa_core::CancellationToken,
41    _memory: Option<MemoryReservation>,
42}
43
44enum ExpressionContext<'a> {
45    Shared(Arc<dyn ScalarExpressionContext + 'a>),
46    Borrowed(&'a dyn ScalarExpressionContext),
47}
48impl<'a> AsRef<dyn ScalarExpressionContext + 'a> for ExpressionContext<'a> {
49    fn as_ref(&self) -> &(dyn ScalarExpressionContext + 'a) {
50        match self {
51            Self::Shared(context) => context.as_ref(),
52            Self::Borrowed(context) => *context,
53        }
54    }
55}
56impl<'a> std::ops::Deref for ExpressionContext<'a> {
57    type Target = dyn ScalarExpressionContext + 'a;
58    fn deref(&self) -> &Self::Target {
59        self.as_ref()
60    }
61}
62
63impl<'a> ScopedExpressionEvaluator<'a> {
64    pub fn shared(
65        context: Arc<dyn ScalarExpressionContext + 'a>,
66        params: &'a [SQLParam],
67        cancellation: uqa_core::CancellationToken,
68    ) -> SharedExpressionEvaluator<'a> {
69        Self::shared_with_control(
70            context,
71            params,
72            cancellation,
73            &ProductionControl::uncontrolled(),
74        )
75        .expect("ordinary expression evaluator")
76    }
77
78    pub fn shared_with_control(
79        context: Arc<dyn ScalarExpressionContext + 'a>,
80        params: &'a [SQLParam],
81        cancellation: uqa_core::CancellationToken,
82        control: &ProductionControl<'_>,
83    ) -> Result<SharedExpressionEvaluator<'a>, SQLError> {
84        Self::capture(
85            ExpressionContext::Shared(context),
86            params,
87            cancellation,
88            control,
89        )
90    }
91
92    /// A grouping or window evaluator borrows its already retained hook instead of recapturing the same lexical scope.
93    pub fn borrowed_with_control(
94        context: &'a dyn ScalarExpressionContext,
95        params: &'a [SQLParam],
96        cancellation: uqa_core::CancellationToken,
97        control: &ProductionControl<'_>,
98    ) -> Result<SharedExpressionEvaluator<'a>, SQLError> {
99        Self::capture(
100            ExpressionContext::Borrowed(context),
101            params,
102            cancellation,
103            control,
104        )
105    }
106
107    fn capture(
108        context: ExpressionContext<'a>,
109        params: &'a [SQLParam],
110        cancellation: uqa_core::CancellationToken,
111        control: &ProductionControl<'_>,
112    ) -> Result<SharedExpressionEvaluator<'a>, SQLError> {
113        let memory = control.reserve(size_of::<Self>())?;
114        Ok(Arc::new(Self {
115            context,
116            params,
117            cancellation,
118            _memory: memory,
119        }))
120    }
121
122    fn evaluate_physical_scoped(
123        &self,
124        expression: &ScalarExpr,
125        schema: &crate::RowSchema,
126        row: &crate::PhysicalRow,
127        states: Option<&crate::scalar::FunctionCallStates>,
128    ) -> ExecResult<Value> {
129        self.cancellation.check().map_err(SQLError::from)?;
130        let view = schema.view(row);
131        let hook = self.context.as_ref();
132        let mut context = PhysicalEvalContext::from_row_lookup(&view, self.params)
133            .with_row_schema(schema)
134            .with_function_hook(hook)
135            .with_subquery_runner(hook)
136            .with_physical_outer_row(schema, row);
137        if let Some(states) = states {
138            context = context.with_function_states(states);
139        }
140        if let ScalarExpr::Func {
141            binding: Some(binding),
142            ..
143        } = expression
144        {
145            hook.require_builtin_execute(binding)?;
146        }
147        if let Some((name, args)) = intercepted_call(expression, self) {
148            let mut evaluate = |expr: &ScalarExpr| {
149                eval_physical_scalar(expr, self.context.subquery_plans(), &context)
150            };
151            if let Some(value) =
152                self.context
153                    .intercept_function(name, args, &view, &mut evaluate)?
154            {
155                return Ok(value);
156            }
157        }
158        Ok(eval_physical_scalar(
159            expression,
160            self.context.subquery_plans(),
161            &context,
162        )?)
163    }
164}
165
166impl ExpressionEvaluator for ScopedExpressionEvaluator<'_> {
167    fn enum_labels(&self) -> Option<&dyn uqa_sql::expr::enums::EnumLabelCatalog> {
168        uqa_sql::expr::EngineHook::enum_labels(self.context.as_ref())
169    }
170
171    fn evaluate(&self, expression: &ScalarExpr, row: &dyn RowLookup) -> ExecResult<Value> {
172        self.cancellation.check().map_err(SQLError::from)?;
173        let hook = self.context.as_ref();
174        let context = PhysicalEvalContext::from_row_lookup(row, self.params)
175            .with_function_hook(hook)
176            .with_subquery_runner(hook);
177        if let ScalarExpr::Func {
178            binding: Some(binding),
179            ..
180        } = expression
181        {
182            hook.require_builtin_execute(binding)?;
183        }
184        if let Some((name, args)) = intercepted_call(expression, self) {
185            let mut evaluate = |expr: &ScalarExpr| {
186                eval_physical_scalar(expr, self.context.subquery_plans(), &context)
187            };
188            if let Some(value) = self
189                .context
190                .intercept_function(name, args, row, &mut evaluate)?
191            {
192                return Ok(value);
193            }
194        }
195        Ok(eval_physical_scalar(
196            expression,
197            self.context.subquery_plans(),
198            &context,
199        )?)
200    }
201
202    fn evaluate_physical(
203        &self,
204        expression: &ScalarExpr,
205        schema: &crate::RowSchema,
206        row: &crate::PhysicalRow,
207    ) -> ExecResult<Value> {
208        self.evaluate_physical_scoped(expression, schema, row, None)
209    }
210
211    fn evaluate_physical_with_function_states(
212        &self,
213        expression: &ScalarExpr,
214        schema: &crate::RowSchema,
215        row: &crate::PhysicalRow,
216        states: &crate::scalar::FunctionCallStates,
217    ) -> ExecResult<Value> {
218        self.evaluate_physical_scoped(expression, schema, row, Some(states))
219    }
220
221    fn parameters(&self) -> &[SQLParam] {
222        self.params
223    }
224
225    fn expression_type(
226        &self,
227        expression: &ScalarExpr,
228        schema: &crate::RowSchema,
229    ) -> Result<Option<uqa_sql::ast::ColumnType>, SQLError> {
230        crate::scalar_type_with_resolver(expression, schema, self.params, self)
231    }
232
233    fn bind_type_introspection(
234        &self,
235        expression: ScalarExpr,
236        schema: &crate::RowSchema,
237    ) -> ScalarExpr {
238        crate::bind_type_introspection_with_resolver(expression, schema, self.params, self)
239    }
240    fn bind_type_introspection_owned(
241        &self,
242        expression: uqa_sql::plan::OwnedScalarExpr,
243        schema: &crate::RowSchema,
244        control: &uqa_core::memory::ProductionControl<'_>,
245    ) -> Result<uqa_sql::plan::OwnedScalarExpr, SQLError> {
246        uqa_sql::bind_type_introspection_owned(expression, schema, self.params, Some(self), control)
247    }
248
249    fn expression_type_with_control(
250        &self,
251        expression: &ScalarExpr,
252        schema: &crate::RowSchema,
253        control: &uqa_core::memory::ProductionControl<'_>,
254    ) -> Result<Option<uqa_core::memory::Produced<uqa_sql::ColumnType>>, SQLError> {
255        uqa_sql::scalar_type_with_resolver_and_control(
256            expression,
257            schema,
258            self.params,
259            Some(self),
260            control,
261        )
262    }
263}
264
265fn intercepted_call<'expression>(
266    expression: &'expression ScalarExpr,
267    resolver: &dyn FunctionTypeResolver,
268) -> Option<(&'expression str, &'expression [ScalarExpr])> {
269    let ScalarExpr::Func {
270        name,
271        binding,
272        args,
273        ..
274    } = expression
275    else {
276        return None;
277    };
278    match binding {
279        Some(binding)
280            if binding.builtin
281                && binding.dispatch.is_none()
282                && binding.resolution_error.is_none() =>
283        {
284            Some((&binding.name, args))
285        }
286        None if !resolver.has_untyped_function(name) => Some((name, args)),
287        _ => None,
288    }
289}
290
291impl FunctionTypeResolver for ScopedExpressionEvaluator<'_> {
292    fn has_untyped_function_with_control(
293        &self,
294        name: &str,
295        control: &uqa_core::memory::ProductionControl<'_>,
296    ) -> Result<bool, SQLError> {
297        self.context
298            .has_untyped_function_with_control(name, control)
299    }
300
301    fn resolve_collation_name_with_control(
302        &self,
303        name: &str,
304        control: &uqa_core::memory::ProductionControl<'_>,
305    ) -> Result<Option<u32>, SQLError> {
306        self.context
307            .resolve_collation_name_with_control(name, control)
308    }
309
310    fn is_scalar_function_binding_with_control(
311        &self,
312        binding: &uqa_sql::ast::FunctionBinding,
313        control: &uqa_core::memory::ProductionControl<'_>,
314    ) -> Result<bool, SQLError> {
315        self.context
316            .is_scalar_function_binding_with_control(binding, control)
317    }
318
319    fn format_type_name_with_control(
320        &self,
321        ty: &uqa_sql::ColumnType,
322        control: &uqa_core::memory::ProductionControl<'_>,
323    ) -> Result<uqa_core::memory::Produced<String>, SQLError> {
324        self.context.format_type_name_with_control(ty, control)
325    }
326
327    fn resolve_type_name_with_control(
328        &self,
329        name: &str,
330        control: &uqa_core::memory::ProductionControl<'_>,
331    ) -> Result<Option<uqa_core::memory::Produced<uqa_sql::ColumnType>>, SQLError> {
332        FunctionTypeResolver::resolve_type_name_with_control(self.context.as_ref(), name, control)
333    }
334
335    fn resolve_scalar_subquery_type_with_control(
336        &self,
337        subquery: crate::SubqueryId,
338        outer_schema: &crate::RowSchema,
339        params: &[SQLParam],
340        control: &uqa_core::memory::ProductionControl<'_>,
341    ) -> Result<Option<uqa_core::memory::Produced<uqa_sql::ColumnType>>, SQLError> {
342        self.context.resolve_scalar_subquery_type_with_control(
343            subquery,
344            outer_schema,
345            params,
346            control,
347        )
348    }
349
350    fn resolve_function_type_with_control(
351        &self,
352        name: &str,
353        binding: Option<&uqa_sql::ast::FunctionBinding>,
354        argument_names: &[Option<String>],
355        argument_types: &[Option<uqa_sql::ColumnType>],
356        explicit_variadic: bool,
357        control: &uqa_core::memory::ProductionControl<'_>,
358    ) -> Result<Option<uqa_core::memory::Produced<uqa_sql::ColumnType>>, SQLError> {
359        self.context.resolve_function_type_with_control(
360            name,
361            binding,
362            argument_names,
363            argument_types,
364            explicit_variadic,
365            control,
366        )
367    }
368
369    fn resolve_function_overload_with_control(
370        &self,
371        name: &str,
372        binding: Option<&uqa_sql::ast::FunctionBinding>,
373        argument_names: &[Option<String>],
374        argument_types: &[Option<uqa_sql::ColumnType>],
375        explicit_variadic: bool,
376        control: &uqa_core::memory::ProductionControl<'_>,
377    ) -> Result<Option<uqa_core::memory::Produced<crate::ResolvedFunctionOverload>>, SQLError> {
378        self.context.resolve_function_overload_with_control(
379            name,
380            binding,
381            argument_names,
382            argument_types,
383            explicit_variadic,
384            control,
385        )
386    }
387
388    fn resolve_function_overload_with_builtins_and_control(
389        &self,
390        name: &str,
391        binding: Option<&uqa_sql::ast::FunctionBinding>,
392        argument_names: &[Option<String>],
393        argument_types: &[Option<uqa_sql::ColumnType>],
394        explicit_variadic: bool,
395        builtins: &[uqa_sql::BuiltinFunctionOverload],
396        control: &uqa_core::memory::ProductionControl<'_>,
397    ) -> Result<Option<uqa_core::memory::Produced<crate::ResolvedFunctionOverload>>, SQLError> {
398        self.context
399            .resolve_function_overload_with_builtins_and_control(
400                name,
401                binding,
402                argument_names,
403                argument_types,
404                explicit_variadic,
405                builtins,
406                control,
407            )
408    }
409
410    fn format_type_name(&self, ty: &uqa_sql::ColumnType) -> Result<String, SQLError> {
411        self.context.format_type_name(ty)
412    }
413
414    fn has_untyped_function(&self, name: &str) -> bool {
415        self.context.has_untyped_function(name)
416    }
417
418    fn resolve_type_name(&self, name: &str) -> Result<Option<uqa_sql::ast::ColumnType>, SQLError> {
419        FunctionTypeResolver::resolve_type_name(self.context.as_ref(), name)
420    }
421
422    fn resolve_collation_name(&self, name: &str) -> Result<Option<u32>, SQLError> {
423        self.context.resolve_collation_name(name)
424    }
425
426    fn enum_labels(&self) -> Option<&dyn uqa_sql::expr::enums::EnumLabelCatalog> {
427        FunctionTypeResolver::enum_labels(self.context.as_ref())
428    }
429
430    fn composite_types(&self) -> Option<&dyn uqa_sql::expr::composites::CompositeTypeCatalog> {
431        FunctionTypeResolver::composite_types(self.context.as_ref())
432    }
433
434    fn resolve_function_type(
435        &self,
436        name: &str,
437        binding: Option<&uqa_sql::ast::FunctionBinding>,
438        argument_names: &[Option<String>],
439        argument_types: &[Option<uqa_sql::ast::ColumnType>],
440        explicit_variadic: bool,
441    ) -> Result<Option<uqa_sql::ast::ColumnType>, SQLError> {
442        self.context.resolve_function_type(
443            name,
444            binding,
445            argument_names,
446            argument_types,
447            explicit_variadic,
448        )
449    }
450
451    fn resolve_function_overload(
452        &self,
453        name: &str,
454        binding: Option<&uqa_sql::ast::FunctionBinding>,
455        argument_names: &[Option<String>],
456        argument_types: &[Option<uqa_sql::ast::ColumnType>],
457        explicit_variadic: bool,
458    ) -> Result<Option<crate::ResolvedFunctionOverload>, SQLError> {
459        self.context.resolve_function_overload(
460            name,
461            binding,
462            argument_names,
463            argument_types,
464            explicit_variadic,
465        )
466    }
467
468    fn is_scalar_function_binding(
469        &self,
470        binding: &uqa_sql::ast::FunctionBinding,
471    ) -> Result<bool, SQLError> {
472        self.context.is_scalar_function_binding(binding)
473    }
474
475    fn resolve_function_overload_with_builtins(
476        &self,
477        name: &str,
478        binding: Option<&uqa_sql::ast::FunctionBinding>,
479        argument_names: &[Option<String>],
480        argument_types: &[Option<uqa_sql::ast::ColumnType>],
481        explicit_variadic: bool,
482        builtins: &[crate::BuiltinFunctionOverload],
483    ) -> Result<Option<crate::ResolvedFunctionOverload>, SQLError> {
484        self.context.resolve_function_overload_with_builtins(
485            name,
486            binding,
487            argument_names,
488            argument_types,
489            explicit_variadic,
490            builtins,
491        )
492    }
493
494    fn resolve_scalar_subquery_type(
495        &self,
496        subquery: crate::SubqueryId,
497        outer_schema: &crate::RowSchema,
498        params: &[SQLParam],
499    ) -> Result<Option<uqa_sql::ast::ColumnType>, SQLError> {
500        self.context
501            .resolve_scalar_subquery_type(subquery, outer_schema, params)
502    }
503}