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::Value;
16use uqa_sql::{expr::RowLookup, SQLError, SQLParam};
17
18#[cfg(test)]
19mod tests;
20
21/// Scalar execution services that can intercept a function requiring its unevaluated argument expressions.
22pub trait ScalarExpressionContext: QueryExpressionContext {
23    fn intercept_function(
24        &self,
25        name: &str,
26        args: &[ScalarExpr],
27        row: &dyn RowLookup,
28        evaluate: &mut dyn FnMut(&ScalarExpr) -> Result<Value, SQLError>,
29    ) -> Result<Option<Value>, SQLError>;
30}
31
32pub struct ScopedExpressionEvaluator<'a> {
33    context: Arc<dyn ScalarExpressionContext + 'a>,
34    params: &'a [SQLParam],
35    cancellation: uqa_core::CancellationToken,
36}
37
38impl<'a> ScopedExpressionEvaluator<'a> {
39    pub fn shared(
40        context: Arc<dyn ScalarExpressionContext + 'a>,
41        params: &'a [SQLParam],
42        cancellation: uqa_core::CancellationToken,
43    ) -> SharedExpressionEvaluator<'a> {
44        Arc::new(Self {
45            context,
46            params,
47            cancellation,
48        })
49    }
50
51    fn evaluate_physical_scoped(
52        &self,
53        expression: &ScalarExpr,
54        schema: &crate::RowSchema,
55        row: &crate::PhysicalRow,
56        states: Option<&crate::scalar::FunctionCallStates>,
57    ) -> ExecResult<Value> {
58        self.cancellation.check().map_err(SQLError::from)?;
59        let view = schema.view(row);
60        let hook = self.context.as_ref();
61        let mut context = PhysicalEvalContext::from_row_lookup(&view, self.params)
62            .with_row_schema(schema)
63            .with_function_hook(hook)
64            .with_subquery_runner(hook)
65            .with_physical_outer_row(schema, row);
66        if let Some(states) = states {
67            context = context.with_function_states(states);
68        }
69        if let ScalarExpr::Func {
70            binding: Some(binding),
71            ..
72        } = expression
73        {
74            hook.require_builtin_execute(binding)?;
75        }
76        if let Some((name, args)) = intercepted_call(expression, self) {
77            let mut evaluate = |expr: &ScalarExpr| {
78                eval_physical_scalar(expr, self.context.subquery_plans(), &context)
79            };
80            if let Some(value) =
81                self.context
82                    .intercept_function(name, args, &view, &mut evaluate)?
83            {
84                return Ok(value);
85            }
86        }
87        Ok(eval_physical_scalar(
88            expression,
89            self.context.subquery_plans(),
90            &context,
91        )?)
92    }
93}
94
95impl ExpressionEvaluator for ScopedExpressionEvaluator<'_> {
96    fn enum_labels(&self) -> Option<&dyn uqa_sql::expr::enums::EnumLabelCatalog> {
97        uqa_sql::expr::EngineHook::enum_labels(self.context.as_ref())
98    }
99
100    fn evaluate(&self, expression: &ScalarExpr, row: &dyn RowLookup) -> ExecResult<Value> {
101        self.cancellation.check().map_err(SQLError::from)?;
102        let hook = self.context.as_ref();
103        let context = PhysicalEvalContext::from_row_lookup(row, self.params)
104            .with_function_hook(hook)
105            .with_subquery_runner(hook);
106        if let ScalarExpr::Func {
107            binding: Some(binding),
108            ..
109        } = expression
110        {
111            hook.require_builtin_execute(binding)?;
112        }
113        if let Some((name, args)) = intercepted_call(expression, self) {
114            let mut evaluate = |expr: &ScalarExpr| {
115                eval_physical_scalar(expr, self.context.subquery_plans(), &context)
116            };
117            if let Some(value) = self
118                .context
119                .intercept_function(name, args, row, &mut evaluate)?
120            {
121                return Ok(value);
122            }
123        }
124        Ok(eval_physical_scalar(
125            expression,
126            self.context.subquery_plans(),
127            &context,
128        )?)
129    }
130
131    fn evaluate_physical(
132        &self,
133        expression: &ScalarExpr,
134        schema: &crate::RowSchema,
135        row: &crate::PhysicalRow,
136    ) -> ExecResult<Value> {
137        self.evaluate_physical_scoped(expression, schema, row, None)
138    }
139
140    fn evaluate_physical_with_function_states(
141        &self,
142        expression: &ScalarExpr,
143        schema: &crate::RowSchema,
144        row: &crate::PhysicalRow,
145        states: &crate::scalar::FunctionCallStates,
146    ) -> ExecResult<Value> {
147        self.evaluate_physical_scoped(expression, schema, row, Some(states))
148    }
149
150    fn parameters(&self) -> &[SQLParam] {
151        self.params
152    }
153
154    fn expression_type(
155        &self,
156        expression: &ScalarExpr,
157        schema: &crate::RowSchema,
158    ) -> Result<Option<uqa_sql::ast::ColumnType>, SQLError> {
159        crate::scalar_type_with_resolver(expression, schema, self.params, self)
160    }
161
162    fn bind_type_introspection(
163        &self,
164        expression: ScalarExpr,
165        schema: &crate::RowSchema,
166    ) -> ScalarExpr {
167        crate::bind_type_introspection_with_resolver(expression, schema, self.params, self)
168    }
169}
170
171fn intercepted_call<'expression>(
172    expression: &'expression ScalarExpr,
173    resolver: &dyn FunctionTypeResolver,
174) -> Option<(&'expression str, &'expression [ScalarExpr])> {
175    let ScalarExpr::Func {
176        name,
177        binding,
178        args,
179        ..
180    } = expression
181    else {
182        return None;
183    };
184    match binding {
185        Some(binding)
186            if binding.builtin
187                && binding.dispatch.is_none()
188                && binding.resolution_error.is_none() =>
189        {
190            Some((&binding.name, args))
191        }
192        None if !resolver.has_untyped_function(name) => Some((name, args)),
193        _ => None,
194    }
195}
196
197impl FunctionTypeResolver for ScopedExpressionEvaluator<'_> {
198    fn format_type_name(&self, ty: &uqa_sql::ColumnType) -> Result<String, SQLError> {
199        self.context.format_type_name(ty)
200    }
201
202    fn has_untyped_function(&self, name: &str) -> bool {
203        self.context.has_untyped_function(name)
204    }
205
206    fn resolve_type_name(&self, name: &str) -> Result<Option<uqa_sql::ast::ColumnType>, SQLError> {
207        FunctionTypeResolver::resolve_type_name(self.context.as_ref(), name)
208    }
209
210    fn resolve_collation_name(&self, name: &str) -> Result<Option<u32>, SQLError> {
211        self.context.resolve_collation_name(name)
212    }
213
214    fn enum_labels(&self) -> Option<&dyn uqa_sql::expr::enums::EnumLabelCatalog> {
215        FunctionTypeResolver::enum_labels(self.context.as_ref())
216    }
217
218    fn composite_types(&self) -> Option<&dyn uqa_sql::expr::composites::CompositeTypeCatalog> {
219        FunctionTypeResolver::composite_types(self.context.as_ref())
220    }
221
222    fn resolve_function_type(
223        &self,
224        name: &str,
225        binding: Option<&uqa_sql::ast::FunctionBinding>,
226        argument_names: &[Option<String>],
227        argument_types: &[Option<uqa_sql::ast::ColumnType>],
228        explicit_variadic: bool,
229    ) -> Result<Option<uqa_sql::ast::ColumnType>, SQLError> {
230        self.context.resolve_function_type(
231            name,
232            binding,
233            argument_names,
234            argument_types,
235            explicit_variadic,
236        )
237    }
238
239    fn resolve_function_overload(
240        &self,
241        name: &str,
242        binding: Option<&uqa_sql::ast::FunctionBinding>,
243        argument_names: &[Option<String>],
244        argument_types: &[Option<uqa_sql::ast::ColumnType>],
245        explicit_variadic: bool,
246    ) -> Result<Option<crate::ResolvedFunctionOverload>, SQLError> {
247        self.context.resolve_function_overload(
248            name,
249            binding,
250            argument_names,
251            argument_types,
252            explicit_variadic,
253        )
254    }
255
256    fn is_scalar_function_binding(
257        &self,
258        binding: &uqa_sql::ast::FunctionBinding,
259    ) -> Result<bool, SQLError> {
260        self.context.is_scalar_function_binding(binding)
261    }
262
263    fn resolve_function_overload_with_builtins(
264        &self,
265        name: &str,
266        binding: Option<&uqa_sql::ast::FunctionBinding>,
267        argument_names: &[Option<String>],
268        argument_types: &[Option<uqa_sql::ast::ColumnType>],
269        explicit_variadic: bool,
270        builtins: &[crate::BuiltinFunctionOverload],
271    ) -> Result<Option<crate::ResolvedFunctionOverload>, SQLError> {
272        self.context.resolve_function_overload_with_builtins(
273            name,
274            binding,
275            argument_names,
276            argument_types,
277            explicit_variadic,
278            builtins,
279        )
280    }
281
282    fn resolve_scalar_subquery_type(
283        &self,
284        subquery: crate::SubqueryId,
285        outer_schema: &crate::RowSchema,
286        params: &[SQLParam],
287    ) -> Result<Option<uqa_sql::ast::ColumnType>, SQLError> {
288        self.context
289            .resolve_scalar_subquery_type(subquery, outer_schema, params)
290    }
291}