Skip to main content

uqa_sql/semantics/
expression_shape.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Expression traversal, qualifier analysis, and safe qualification.
8
9use super::collect_from_qualifiers;
10use crate::plan::SourcePlan;
11use crate::ScalarExpr;
12use std::collections::BTreeSet;
13
14pub fn expr_contains_function(expression: &ScalarExpr) -> bool {
15    let mut contains_function = false;
16    expression.visit(&mut |part| {
17        contains_function |= matches!(
18            part,
19            ScalarExpr::Func { .. } | ScalarExpr::WindowCall { .. }
20        );
21    });
22    contains_function
23}
24
25pub fn flatten_and_filter_parts(expr: &ScalarExpr) -> Vec<&ScalarExpr> {
26    match expr {
27        ScalarExpr::And(items) => items.iter().flat_map(flatten_and_filter_parts).collect(),
28        other => vec![other],
29    }
30}
31
32pub fn from_qualifier_set(from: &SourcePlan) -> BTreeSet<String> {
33    let mut qualifiers = Vec::new();
34    collect_from_qualifiers(from, &mut qualifiers);
35    qualifiers.into_iter().collect()
36}
37
38pub fn expr_qualifiers(expr: &ScalarExpr) -> BTreeSet<String> {
39    let mut qualifiers = BTreeSet::new();
40    collect_expr_qualifiers(expr, &mut qualifiers);
41    qualifiers
42}
43
44pub fn collect_expr_qualifiers(expr: &ScalarExpr, qualifiers: &mut BTreeSet<String>) {
45    expr.visit(&mut |part| match part {
46        ScalarExpr::QualifiedColumn { qualifier, .. } | ScalarExpr::QualifiedStar(qualifier) => {
47            qualifiers.insert(qualifier.clone());
48        }
49        _ => {}
50    });
51}
52
53pub fn expr_has_unqualified_column(expr: &ScalarExpr) -> bool {
54    let mut found = false;
55    expr.visit(&mut |part| {
56        found |= matches!(part, ScalarExpr::Column(_));
57    });
58    found
59}
60
61#[expect(
62    clippy::too_many_lines,
63    reason = "preserves SELECT schema and row identity"
64)]
65pub fn qualify_unqualified_columns(expr: &ScalarExpr, qualifier: &str) -> ScalarExpr {
66    match expr {
67        ScalarExpr::Column(column) => ScalarExpr::qualified_column(qualifier, column),
68        ScalarExpr::Default
69        | ScalarExpr::Position(_)
70        | ScalarExpr::InternalColumn(_)
71        | ScalarExpr::QualifiedColumn { .. }
72        | ScalarExpr::QualifiedStar(_)
73        | ScalarExpr::Literal(_)
74        | ScalarExpr::TypedLiteral { .. }
75        | ScalarExpr::RetainedLiteral(_)
76        | ScalarExpr::Param(_)
77        | ScalarExpr::Star => expr.clone(),
78        ScalarExpr::Array(items) => ScalarExpr::Array(
79            items
80                .iter()
81                .map(|item| qualify_unqualified_columns(item, qualifier))
82                .collect(),
83        ),
84        ScalarExpr::Row(items) => ScalarExpr::Row(
85            items
86                .iter()
87                .map(|item| qualify_unqualified_columns(item, qualifier))
88                .collect(),
89        ),
90        ScalarExpr::CompositeRow {
91            items,
92            binding,
93            bound_type,
94        } => ScalarExpr::CompositeRow {
95            items: items
96                .iter()
97                .map(|item| qualify_unqualified_columns(item, qualifier))
98                .collect(),
99            binding: binding.clone(),
100            bound_type: bound_type.clone(),
101        },
102        ScalarExpr::And(items) => ScalarExpr::And(
103            items
104                .iter()
105                .map(|item| qualify_unqualified_columns(item, qualifier))
106                .collect(),
107        ),
108        ScalarExpr::Or(items) => ScalarExpr::Or(
109            items
110                .iter()
111                .map(|item| qualify_unqualified_columns(item, qualifier))
112                .collect(),
113        ),
114        ScalarExpr::Binary { op, lhs, rhs } => ScalarExpr::Binary {
115            op: *op,
116            lhs: Box::new(qualify_unqualified_columns(lhs, qualifier)),
117            rhs: Box::new(qualify_unqualified_columns(rhs, qualifier)),
118        },
119        ScalarExpr::Not(inner) => {
120            ScalarExpr::Not(Box::new(qualify_unqualified_columns(inner, qualifier)))
121        }
122        ScalarExpr::UnaryMinus(inner) => {
123            ScalarExpr::UnaryMinus(Box::new(qualify_unqualified_columns(inner, qualifier)))
124        }
125        ScalarExpr::IsNull { expr, negated } => ScalarExpr::IsNull {
126            expr: Box::new(qualify_unqualified_columns(expr, qualifier)),
127            negated: *negated,
128        },
129        ScalarExpr::Between { expr, low, high } => ScalarExpr::Between {
130            expr: Box::new(qualify_unqualified_columns(expr, qualifier)),
131            low: Box::new(qualify_unqualified_columns(low, qualifier)),
132            high: Box::new(qualify_unqualified_columns(high, qualifier)),
133        },
134        ScalarExpr::InList {
135            expr,
136            list,
137            negated,
138        } => ScalarExpr::InList {
139            expr: Box::new(qualify_unqualified_columns(expr, qualifier)),
140            list: list
141                .iter()
142                .map(|item| qualify_unqualified_columns(item, qualifier))
143                .collect(),
144            negated: *negated,
145        },
146        ScalarExpr::Func {
147            order_syntax,
148            name,
149            binding,
150            args,
151            distinct,
152            order_by,
153            filter,
154        } => ScalarExpr::Func {
155            order_syntax: *order_syntax,
156            name: name.clone(),
157            binding: binding.clone(),
158            args: args
159                .iter()
160                .map(|arg| qualify_unqualified_columns(arg, qualifier))
161                .collect(),
162            distinct: *distinct,
163            order_by: order_by.clone(),
164            filter: filter
165                .as_ref()
166                .map(|filter| Box::new(qualify_unqualified_columns(filter, qualifier))),
167        },
168        ScalarExpr::WindowCall {
169            name,
170            args,
171            spec,
172            filter,
173            modifiers,
174        } => ScalarExpr::WindowCall {
175            modifiers: *modifiers,
176            name: name.clone(),
177            args: args
178                .iter()
179                .map(|arg| qualify_unqualified_columns(arg, qualifier))
180                .collect(),
181            spec: spec.clone(),
182            filter: filter
183                .as_ref()
184                .map(|filter| Box::new(qualify_unqualified_columns(filter, qualifier))),
185        },
186        ScalarExpr::Case {
187            base,
188            when,
189            else_branch,
190        } => ScalarExpr::Case {
191            base: base
192                .as_ref()
193                .map(|expr| Box::new(qualify_unqualified_columns(expr, qualifier))),
194            when: when
195                .iter()
196                .map(|(cond, result)| {
197                    (
198                        qualify_unqualified_columns(cond, qualifier),
199                        qualify_unqualified_columns(result, qualifier),
200                    )
201                })
202                .collect(),
203            else_branch: else_branch
204                .as_ref()
205                .map(|expr| Box::new(qualify_unqualified_columns(expr, qualifier))),
206        },
207        ScalarExpr::Collated {
208            expr,
209            ty,
210            collation,
211        } => ScalarExpr::Collated {
212            expr: Box::new(qualify_unqualified_columns(expr, qualifier)),
213            ty: ty.clone(),
214            collation: *collation,
215        },
216        ScalarExpr::Cast { expr, ty, implicit } => ScalarExpr::Cast {
217            implicit: *implicit,
218            expr: Box::new(qualify_unqualified_columns(expr, qualifier)),
219            ty: ty.clone(),
220        },
221        ScalarExpr::InSubquery {
222            expr,
223            subquery,
224            negated,
225        } => ScalarExpr::InSubquery {
226            expr: Box::new(qualify_unqualified_columns(expr, qualifier)),
227            subquery: *subquery,
228            negated: *negated,
229        },
230        ScalarExpr::ScalarSubquery(_) | ScalarExpr::Exists { .. } => expr.clone(),
231    }
232}
233
234/// True when the expression can never evaluate to SQL NULL for any
235/// row: registered search functions, IS NULL tests, and boolean
236/// combinations thereof. Anything referencing column comparisons may
237/// yield NULL, so set-complement `NOT` would be unsound for it.
238pub fn expr_is_null_free(expr: &ScalarExpr) -> bool {
239    match expr {
240        ScalarExpr::Func { name, .. } => crate::registry::is_registered(name),
241        ScalarExpr::IsNull { .. } => true,
242        ScalarExpr::Exists { .. } => true,
243        ScalarExpr::Literal(v) => !matches!(v, uqa_core::Value::Null),
244        ScalarExpr::And(parts) | ScalarExpr::Or(parts) => parts.iter().all(expr_is_null_free),
245        ScalarExpr::Not(inner) => expr_is_null_free(inner),
246        _ => false,
247    }
248}
249
250#[cfg(test)]
251mod tests {
252    use super::{expr_contains_function, expr_has_unqualified_column, expr_qualifiers, ScalarExpr};
253    use crate::ast::{FrameExclusion, FrameMode};
254    use crate::{ScalarFrameBound, ScalarWindowFrame, ScalarWindowSpec};
255
256    #[test]
257    fn expression_shape_uses_complete_scalar_traversal() {
258        let expression = ScalarExpr::WindowCall {
259            name: "sum".into(),
260            args: vec![ScalarExpr::QualifiedColumn {
261                qualifier: "orders".into(),
262                column: "amount".into(),
263            }],
264            spec: ScalarWindowSpec {
265                definition: None,
266                partition_by: Vec::new(),
267                order_by: Vec::new(),
268                frame: Some(ScalarWindowFrame {
269                    mode: FrameMode::Rows,
270                    start: ScalarFrameBound::Preceding(Box::new(ScalarExpr::Column(
271                        "frame_width".into(),
272                    ))),
273                    end: ScalarFrameBound::CurrentRow,
274                    between: true,
275                    exclusion: FrameExclusion::NoOthers,
276                }),
277            },
278            filter: None,
279            modifiers: crate::ast::WindowCallModifiers::default(),
280        };
281        assert!(expr_contains_function(&expression));
282        assert!(expr_has_unqualified_column(&expression));
283        assert_eq!(
284            expr_qualifiers(&expression),
285            std::collections::BTreeSet::from(["orders".into()])
286        );
287    }
288}