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