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