Skip to main content

uqa_execution/relational/
evaluator.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Expression-evaluation and row-predicate seams.
8
9use super::{
10    eval_scalar, Arc, ExecResult, RowSchema, SQLParam, ScalarEvalContext, ScalarExpr, Value,
11};
12use crate::RowSchemaExecution;
13use uqa_sql::ast::ColumnType;
14use uqa_sql::expr::RowLookup;
15use uqa_sql::SQLError;
16
17use crate::PhysicalRow;
18
19pub trait ExpressionEvaluator: Send + Sync {
20    fn evaluate(&self, expression: &ScalarExpr, row: &dyn RowLookup) -> ExecResult<Value>;
21
22    /// Borrow the same retained enum catalog used while evaluating expressions.
23    fn enum_labels(&self) -> Option<&dyn uqa_sql::expr::enums::EnumLabelCatalog> {
24        None
25    }
26
27    fn evaluate_physical(
28        &self,
29        expression: &ScalarExpr,
30        schema: &RowSchema,
31        row: &PhysicalRow,
32    ) -> ExecResult<Value> {
33        self.evaluate(expression, &schema.view(row))
34    }
35
36    /// Evaluate a prepared physical expression with its execution-owned function state.
37    fn evaluate_physical_with_function_states(
38        &self,
39        expression: &ScalarExpr,
40        schema: &RowSchema,
41        row: &PhysicalRow,
42        _states: &crate::scalar::FunctionCallStates,
43    ) -> ExecResult<Value> {
44        self.evaluate_physical(expression, schema, row)
45    }
46
47    /// Bound SQL parameters used by static type resolution. Implementations
48    /// that do not evaluate parameters may keep the empty default.
49    fn parameters(&self) -> &[SQLParam] {
50        &[]
51    }
52
53    fn expression_type(
54        &self,
55        expression: &ScalarExpr,
56        schema: &RowSchema,
57    ) -> Result<Option<ColumnType>, SQLError> {
58        crate::scalar_type(expression, schema, self.parameters())
59    }
60
61    /// Bind overloads and common-type coercions while this evaluator's declared-type context is still available.
62    fn bind_type_introspection(&self, expression: ScalarExpr, schema: &RowSchema) -> ScalarExpr {
63        crate::bind_type_introspection(expression, schema, self.parameters())
64    }
65
66    fn star_column_visible(&self, _column: &str) -> bool {
67        true
68    }
69
70    /// Decide wildcard visibility from the bound logical attribute rather
71    /// than its possibly colliding SQL label.
72    fn star_position_visible(&self, schema: &RowSchema, position: usize) -> bool {
73        schema.wildcard_position_visible(position)
74            && schema
75                .columns()
76                .get(position)
77                .is_none_or(|column| self.star_column_visible(column))
78    }
79
80    fn project_star(&self, row: &dyn RowLookup) -> ExecResult<Vec<(String, Value)>> {
81        let mut output = Vec::new();
82        row.visit_columns(&mut |column, value| {
83            if self.star_column_visible(column) {
84                output.push((column.to_string(), value.clone()));
85            }
86        });
87        Ok(output)
88    }
89}
90
91pub type SharedExpressionEvaluator<'a> = Arc<dyn ExpressionEvaluator + 'a>;
92
93pub trait RowPredicate: Send + Sync {
94    fn keep_physical(&self, schema: &RowSchema, row: &PhysicalRow) -> ExecResult<bool>;
95}
96
97pub type SharedRowPredicate<'a> = Arc<dyn RowPredicate + 'a>;
98
99pub(crate) struct DefaultExpressionEvaluator {
100    params: Vec<SQLParam>,
101}
102
103impl DefaultExpressionEvaluator {
104    pub(crate) fn shared(params: Vec<SQLParam>) -> SharedExpressionEvaluator<'static> {
105        Arc::new(Self { params })
106    }
107}
108
109impl ExpressionEvaluator for DefaultExpressionEvaluator {
110    fn evaluate(&self, expression: &ScalarExpr, row: &dyn RowLookup) -> ExecResult<Value> {
111        let context = ScalarEvalContext::from_row_lookup(row, &self.params);
112        Ok(eval_scalar(expression, &context)?)
113    }
114
115    fn evaluate_physical(
116        &self,
117        expression: &ScalarExpr,
118        schema: &RowSchema,
119        row: &PhysicalRow,
120    ) -> ExecResult<Value> {
121        let view = schema.view(row);
122        let context =
123            ScalarEvalContext::from_row_lookup(&view, &self.params).with_row_schema(schema);
124        Ok(eval_scalar(expression, &context)?)
125    }
126
127    fn parameters(&self) -> &[SQLParam] {
128        &self.params
129    }
130
131    fn evaluate_physical_with_function_states(
132        &self,
133        expression: &ScalarExpr,
134        schema: &RowSchema,
135        row: &PhysicalRow,
136        states: &crate::scalar::FunctionCallStates,
137    ) -> ExecResult<Value> {
138        let view = schema.view(row);
139        let context = ScalarEvalContext::from_row_lookup(&view, &self.params)
140            .with_row_schema(schema)
141            .with_function_states(states);
142        Ok(eval_scalar(expression, &context)?)
143    }
144}