Skip to main content

uqa_execution/
projected_predicate.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Scalar predicates compiled against positional storage projections.
8
9use uqa_core::Value;
10use uqa_sql::ast::BinaryOp;
11use uqa_sql::expr::IntegerWidth;
12use uqa_sql::{SQLError, SQLParam};
13
14use crate::{RowSchema, ScalarExpr};
15
16mod compile;
17mod evaluate;
18
19/// A predicate whose column lookups are resolved once to projection slots.
20/// Unsupported expressions return `None` and continue through the canonical
21/// map-backed evaluator.
22pub struct ProjectedPredicate {
23    expression: ProjectedExpr,
24}
25
26pub(super) enum ProjectedIntPredicate {
27    Comparison {
28        field: usize,
29        op: BinaryOp,
30        literal: i64,
31        field_on_left: bool,
32    },
33    Between {
34        field: usize,
35        low: i64,
36        high: i64,
37    },
38}
39
40pub(super) enum ProjectedExpr {
41    Field(usize),
42    Literal(Value),
43    Binary {
44        op: BinaryOp,
45        lhs: Box<Self>,
46        rhs: Box<Self>,
47        integer_width: Option<IntegerWidth>,
48        real_arithmetic: bool,
49    },
50    UnaryMinus(Box<Self>),
51    IntFieldComparison {
52        field: usize,
53        op: BinaryOp,
54        literal: i64,
55        field_on_left: bool,
56    },
57    Not(Box<Self>),
58    And(Vec<Self>),
59    IntFieldConjunction(Vec<ProjectedIntPredicate>),
60    Or(Vec<Self>),
61    IsNull {
62        expression: Box<Self>,
63        negated: bool,
64    },
65    Between {
66        expression: Box<Self>,
67        low: Box<Self>,
68        high: Box<Self>,
69    },
70    IntFieldBetween {
71        field: usize,
72        low: i64,
73        high: i64,
74    },
75    InList {
76        expression: Box<Self>,
77        list: Vec<Self>,
78        negated: bool,
79    },
80    Like {
81        expression: Box<Self>,
82        pattern: uqa_sql::expr::CompiledLikePattern,
83    },
84    Cast {
85        expression: Box<Self>,
86        ty: String,
87    },
88}
89
90impl ProjectedPredicate {
91    pub fn compile(
92        expression: &ScalarExpr,
93        fields: &[String],
94        params: &[SQLParam],
95    ) -> Result<Option<Self>, SQLError> {
96        Self::compile_with_schema(expression, &RowSchema::new(fields.to_vec()), params)
97    }
98
99    /// Compile against structured SQL identities instead of interpreting punctuation in public labels as qualification metadata.
100    pub fn compile_with_schema(
101        expression: &ScalarExpr,
102        schema: &RowSchema,
103        params: &[SQLParam],
104    ) -> Result<Option<Self>, SQLError> {
105        let expression = uqa_sql::bind_type_introspection(expression.clone(), schema, params);
106        Self::compile_bound(&expression, schema, params)
107    }
108
109    pub(crate) fn compile_bound(
110        expression: &ScalarExpr,
111        schema: &RowSchema,
112        params: &[SQLParam],
113    ) -> Result<Option<Self>, SQLError> {
114        match compile::compile(expression, schema, params) {
115            Ok(expression) => Ok(expression.map(|expression| Self { expression })),
116            Err(SQLError::Unsupported(_)) => Ok(None),
117            Err(error) => Err(error),
118        }
119    }
120
121    #[inline]
122    pub fn keep(&self, values: &[&Value]) -> Result<bool, SQLError> {
123        evaluate::keep(&self.expression, values)
124    }
125
126    /// Evaluate against backend-owned values through a positional projection without constructing an intermediate reference array. A `usize::MAX` projection slot reads as SQL NULL.
127    #[inline]
128    pub fn keep_indexed(&self, values: &[Value], projection: &[usize]) -> Result<bool, SQLError> {
129        evaluate::keep_indexed(&self.expression, values, projection)
130    }
131
132    /// Evaluate directly against a composite physical row. Column names and
133    /// qualifiers were resolved to logical positions during compilation, so
134    /// the hot path neither builds a named row nor allocates a reference list.
135    #[inline]
136    pub fn keep_row(&self, row: &crate::PhysicalRowView<'_>) -> Result<bool, SQLError> {
137        evaluate::keep_row(&self.expression, row)
138    }
139}
140
141#[cfg(test)]
142mod tests {
143    use super::*;
144    use crate::RowSchemaExecution;
145    use crate::{eval_scalar, ScalarEvalContext};
146    use uqa_sql::ast::ColumnType;
147    use uqa_sql::expr::truthy;
148
149    #[test]
150    fn positional_predicate_preserves_null_and_short_circuit_semantics() {
151        let expression = ScalarExpr::And(vec![
152            ScalarExpr::Between {
153                expr: Box::new(ScalarExpr::Column("x".into())),
154                low: Box::new(ScalarExpr::Literal(Value::Int(2))),
155                high: Box::new(ScalarExpr::Literal(Value::Int(4))),
156            },
157            ScalarExpr::IsNull {
158                expr: Box::new(ScalarExpr::Column("y".into())),
159                negated: false,
160            },
161        ]);
162        let predicate = ProjectedPredicate::compile(&expression, &["x".into(), "y".into()], &[])
163            .unwrap()
164            .unwrap();
165        assert!(predicate.keep(&[&Value::Int(3), &Value::Null]).unwrap());
166        assert!(!predicate.keep(&[&Value::Int(5), &Value::Null]).unwrap());
167        assert!(!predicate.keep(&[&Value::Null, &Value::Null]).unwrap());
168
169        let stored = [Value::Null, Value::Int(3)];
170        assert!(predicate.keep_indexed(&stored, &[1, 0]).unwrap());
171        assert!(!predicate.keep_indexed(&stored, &[usize::MAX, 0]).unwrap());
172    }
173
174    #[test]
175    fn projected_q1_and_q6_predicates_match_the_canonical_evaluator() {
176        let fields = vec!["discount".into(), "quantity".into(), "ship_day".into()];
177        let q6 = ScalarExpr::And(vec![
178            ScalarExpr::Between {
179                expr: Box::new(ScalarExpr::Column("ship_day".into())),
180                low: Box::new(ScalarExpr::Param(1)),
181                high: Box::new(ScalarExpr::Literal(Value::Int(2_190))),
182            },
183            ScalarExpr::Between {
184                expr: Box::new(ScalarExpr::Column("discount".into())),
185                low: Box::new(ScalarExpr::Literal(Value::Int(2))),
186                high: Box::new(ScalarExpr::Literal(Value::Int(8))),
187            },
188            ScalarExpr::Binary {
189                op: BinaryOp::Greater,
190                lhs: Box::new(ScalarExpr::Literal(Value::Int(40))),
191                rhs: Box::new(ScalarExpr::Column("quantity".into())),
192            },
193        ]);
194        let params = vec![SQLParam::typed_scalar(
195            Value::Int(365),
196            ColumnType::SmallInteger,
197        )];
198        let predicate = ProjectedPredicate::compile(&q6, &fields, &params)
199            .unwrap()
200            .unwrap();
201        assert!(matches!(
202            &predicate.expression,
203            ProjectedExpr::IntFieldConjunction(items) if items.len() == 3
204        ));
205        let discounts = [Value::Null, Value::Int(1), Value::Int(2), Value::Int(8)];
206        let quantities = [
207            Value::Null,
208            Value::Int(39),
209            Value::Int(40),
210            Value::Float(39.5),
211        ];
212        let ship_days = [
213            Value::Null,
214            Value::Int(364),
215            Value::Int(365),
216            Value::Int(2_190),
217            Value::Int(2_191),
218        ];
219        for discount in &discounts {
220            for quantity in &quantities {
221                for ship_day in &ship_days {
222                    assert_projected_parity(
223                        &q6,
224                        &predicate,
225                        &fields,
226                        &[discount.clone(), quantity.clone(), ship_day.clone()],
227                        &params,
228                    );
229                }
230            }
231        }
232
233        let q1 = ScalarExpr::Binary {
234            op: BinaryOp::LessEqual,
235            lhs: Box::new(ScalarExpr::Column("ship_day".into())),
236            rhs: Box::new(ScalarExpr::Literal(Value::Int(2_449))),
237        };
238        let predicate = ProjectedPredicate::compile(&q1, &fields, &[])
239            .unwrap()
240            .unwrap();
241        for ship_day in [Value::Null, Value::Int(2_449), Value::Int(2_450)] {
242            assert_projected_parity(
243                &q1,
244                &predicate,
245                &fields,
246                &[Value::Int(0), Value::Int(0), ship_day],
247                &[],
248            );
249        }
250    }
251
252    #[test]
253    fn projected_integer_comparisons_match_every_canonical_operator_and_operand_order() {
254        let fields = vec!["value".into()];
255        for op in [
256            BinaryOp::Equal,
257            BinaryOp::NotEqual,
258            BinaryOp::Less,
259            BinaryOp::LessEqual,
260            BinaryOp::Greater,
261            BinaryOp::GreaterEqual,
262        ] {
263            for field_on_left in [true, false] {
264                let field = ScalarExpr::Column("value".into());
265                let literal = ScalarExpr::Literal(Value::Int(7));
266                let expression = ScalarExpr::Binary {
267                    op,
268                    lhs: Box::new(if field_on_left {
269                        field.clone()
270                    } else {
271                        literal.clone()
272                    }),
273                    rhs: Box::new(if field_on_left {
274                        literal.clone()
275                    } else {
276                        field.clone()
277                    }),
278                };
279                let predicate = ProjectedPredicate::compile(&expression, &fields, &[])
280                    .unwrap()
281                    .unwrap();
282                for value in [
283                    Value::Null,
284                    Value::Int(6),
285                    Value::Int(7),
286                    Value::Int(8),
287                    Value::Float(7.0),
288                ] {
289                    assert_projected_parity(&expression, &predicate, &fields, &[value], &[]);
290                }
291            }
292        }
293    }
294
295    #[test]
296    fn projected_like_predicates_match_the_canonical_evaluator() {
297        for (operator, pattern) in [
298            ("LIKE", "%"),
299            ("LIKE", "%green%"),
300            ("LIKE", "%special%requests%"),
301            ("LIKE", "a_c"),
302            ("ILIKE", "%GREEN%"),
303        ] {
304            let expression = parsed_expression(&format!("text {operator} '{pattern}'"));
305            let fields = vec!["text".into()];
306            let predicate = ProjectedPredicate::compile(&expression, &fields, &[])
307                .unwrap()
308                .unwrap();
309            for value in [
310                Value::Str("forest green part".into()),
311                Value::FixedChar("GREEN   ".into()),
312                Value::Str("a-c".into()),
313                Value::Str("special pending requests".into()),
314                Value::Null,
315            ] {
316                assert_projected_parity(&expression, &predicate, &fields, &[value], &[]);
317            }
318        }
319    }
320
321    #[test]
322    fn qualified_like_runs_directly_on_a_composite_physical_row() {
323        let expression = parsed_expression("o.comment NOT LIKE '%special%requests%'");
324        let left_schema =
325            crate::RowSchema::with_qualified_types("c", vec!["id".into()], vec![None]);
326        let right_schema =
327            crate::RowSchema::with_qualified_types("o", vec!["comment".into()], vec![None]);
328        let schema = crate::RowSchema::join(&left_schema, &right_schema, std::iter::empty());
329        let predicate = ProjectedPredicate::compile_with_schema(&expression, &schema, &[])
330            .unwrap()
331            .unwrap();
332
333        let accepted = crate::PhysicalRow::concat(
334            &crate::PhysicalRow::from_values(vec![Value::Int(1)]),
335            &crate::PhysicalRow::from_values(vec![Value::Str("ordinary order".into())]),
336        );
337        let rejected = crate::PhysicalRow::concat(
338            &crate::PhysicalRow::from_values(vec![Value::Int(1)]),
339            &crate::PhysicalRow::from_values(vec![Value::Str("special pending requests".into())]),
340        );
341        assert!(predicate.keep_row(&schema.view(&accepted)).unwrap());
342        assert!(!predicate.keep_row(&schema.view(&rejected)).unwrap());
343    }
344
345    fn parsed_expression(source: &str) -> ScalarExpr {
346        let uqa_sql::Statement::Select(mut query) = uqa_sql::compile(&format!("SELECT {source}"))
347            .unwrap()
348            .remove(0)
349        else {
350            panic!("scalar SELECT");
351        };
352        uqa_sql::plan::ExpressionPlan::lower(query.projections.remove(0).expr).scalar
353    }
354
355    #[test]
356    fn projected_predicate_folds_typed_literals_once() {
357        let expression = ScalarExpr::Binary {
358            op: BinaryOp::Less,
359            lhs: Box::new(ScalarExpr::Column("day".into())),
360            rhs: Box::new(ScalarExpr::Cast {
361                implicit: false,
362                expr: Box::new(ScalarExpr::Literal(Value::Str("1995-03-15".into()))),
363                ty: "date".into(),
364            }),
365        };
366        let predicate = ProjectedPredicate::compile(&expression, &["day".into()], &[])
367            .unwrap()
368            .unwrap();
369
370        let ProjectedExpr::Binary { rhs, .. } = &predicate.expression else {
371            panic!("expected a compiled comparison");
372        };
373        assert!(matches!(
374            rhs.as_ref(),
375            ProjectedExpr::Literal(Value::Temporal(_))
376        ));
377    }
378
379    #[test]
380    fn projected_predicate_preserves_unary_minus_integer_width() {
381        let expression = ScalarExpr::Binary {
382            op: BinaryOp::Equal,
383            lhs: Box::new(ScalarExpr::UnaryMinus(Box::new(ScalarExpr::Cast {
384                implicit: false,
385                expr: Box::new(ScalarExpr::Column("x".into())),
386                ty: "smallint".into(),
387            }))),
388            rhs: Box::new(ScalarExpr::Literal(Value::Int(-1))),
389        };
390        let predicate = ProjectedPredicate::compile(&expression, &["x".into()], &[])
391            .unwrap()
392            .unwrap();
393
394        assert!(predicate.keep(&[&Value::Int(1)]).unwrap());
395        let error = predicate
396            .keep(&[&Value::Int(i64::from(i16::MIN))])
397            .expect_err("negating smallint minimum must overflow");
398        assert_eq!(error.sqlstate(), Some("22003"));
399    }
400
401    fn assert_projected_parity(
402        expression: &ScalarExpr,
403        predicate: &ProjectedPredicate,
404        fields: &[String],
405        values: &[Value],
406        params: &[SQLParam],
407    ) {
408        let row = fields
409            .iter()
410            .cloned()
411            .zip(values.iter().cloned())
412            .collect::<uqa_sql::ResultRow>();
413        let expected = eval_scalar(expression, &ScalarEvalContext::new(Some(&row), params))
414            .map(|value| truthy(&value));
415        let references = values.iter().collect::<Vec<_>>();
416        let actual = predicate.keep(&references);
417        match (expected, actual) {
418            (Ok(expected), Ok(actual)) => assert_eq!(actual, expected, "row: {row:?}"),
419            (Err(expected), Err(actual)) => assert_eq!(actual.to_string(), expected.to_string()),
420            (expected, actual) => panic!("projected result {actual:?} != canonical {expected:?}"),
421        }
422    }
423}