Skip to main content

uqa_sql/semantics/
grouping_sets.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! PostgreSQL-compatible grouping-set preparation after input schema binding.
8
9use std::collections::HashSet;
10
11use crate::ast::ColumnType;
12use crate::{RowSchema, ScalarExpr, ScalarFrameBound};
13use uqa_core::Value;
14
15use crate::{plan::QueryBlockPlan, FunctionTypeResolver, SQLError, SQLParam};
16
17mod expressions;
18mod names;
19pub(crate) use names::resolve_grouping_expression_reference;
20pub use names::{bind_grouping_names, grouping_output_name, resolve_grouping_expression};
21mod validation;
22pub use validation::validate_grouped_expressions;
23#[cfg(test)]
24mod tests;
25
26/// Resolve grouping names against the input before expanding output aliases and deduplicating `GROUP BY DISTINCT` sets. Equivalent qualified and unqualified columns share one identity without conflating expressions that `PostgreSQL` resolves to different operator inputs.
27pub fn prepare_grouping_sets(
28    engine: &dyn crate::routines::RoutineResolution,
29    statement: &QueryBlockPlan,
30    schema: &RowSchema,
31    params: &[SQLParam],
32) -> Result<Option<QueryBlockPlan>, SQLError> {
33    if statement.group_by.is_empty() && statement.grouping_sets.is_empty() {
34        return Ok(None);
35    }
36
37    let mut prepared = statement.clone();
38    let changed = prepare_grouping_sets_in_place(engine, &mut prepared, schema, None, params)?;
39    Ok(changed.then_some(prepared))
40}
41
42/// Finalize analyzed grouping identity before scalar optimization can erase it.
43pub(crate) fn prepare_grouping_sets_in_place(
44    engine: &dyn crate::routines::RoutineResolution,
45    prepared: &mut QueryBlockPlan,
46    schema: &RowSchema,
47    outer: Option<&RowSchema>,
48    params: &[SQLParam],
49) -> Result<bool, SQLError> {
50    let mut changed = bind_grouping_names(engine, prepared, schema, outer, params)?;
51    changed |= expressions::bind_grouping_expressions(engine, prepared, schema, params)?;
52    if !prepared.group_distinct {
53        return Ok(changed);
54    }
55    analyze_distinct_grouping(engine, prepared, schema, outer, params)?.apply(prepared)?;
56    Ok(true)
57}
58
59/// Pre-optimization grouping identities. The stored SQL keeps its original DISTINCT clause and sets; this selection belongs only to its analyzed executable copy.
60#[derive(Debug, Clone)]
61pub struct AnalyzedGroupingSets {
62    original_count: usize,
63    retained: Vec<usize>,
64}
65
66impl AnalyzedGroupingSets {
67    pub(crate) fn copy_with(
68        &self,
69        copying: &mut crate::plan::copy::Copying<'_>,
70    ) -> Result<Self, SQLError> {
71        Ok(Self {
72            original_count: self.original_count,
73            retained: copying.map(self.retained.iter(), |_, position| Ok(*position))?,
74        })
75    }
76
77    /// Remove only sets that were equal before optimization, preserving multiplicity when distinct expressions later fold to the same value.
78    pub fn apply(self, block: &mut QueryBlockPlan) -> Result<(), SQLError> {
79        if !block.group_distinct || block.grouping_sets.len() != self.original_count {
80            return Err(SQLError::Internal(
81                "analyzed grouping selection lost its original sets".into(),
82            ));
83        }
84        let mut retained = self.retained.into_iter().peekable();
85        let mut index = 0;
86        block.grouping_sets.retain(|_| {
87            let keep = retained.peek() == Some(&index);
88            if keep {
89                retained.next();
90            }
91            index += 1;
92            keep
93        });
94        block.group_distinct = false;
95        Ok(())
96    }
97}
98
99pub(crate) fn analyze_distinct_grouping(
100    engine: &dyn crate::routines::RoutineResolution,
101    block: &QueryBlockPlan,
102    schema: &RowSchema,
103    outer: Option<&RowSchema>,
104    params: &[SQLParam],
105) -> Result<AnalyzedGroupingSets, SQLError> {
106    let mut seen = HashSet::with_capacity(block.grouping_sets.len());
107    let mut retained = Vec::with_capacity(block.grouping_sets.len());
108    for (index, set) in block.grouping_sets.iter().enumerate() {
109        let mut identity = set
110            .iter()
111            .map(|expression| {
112                let expression = resolve_grouping_expression_reference(
113                    engine,
114                    expression,
115                    &block.projections,
116                    schema,
117                    outer,
118                    params,
119                )?;
120                expression_identity(engine, expression, schema, params)
121            })
122            .collect::<Result<Vec<_>, _>>()?;
123        identity.sort_unstable();
124        identity.dedup();
125        if seen.insert(identity) {
126            retained.push(index);
127        }
128    }
129    Ok(AnalyzedGroupingSets {
130        original_count: block.grouping_sets.len(),
131        retained,
132    })
133}
134
135pub(crate) fn expression_identity(
136    engine: &dyn FunctionTypeResolver,
137    expression: &ScalarExpr,
138    schema: &RowSchema,
139    params: &[SQLParam],
140) -> Result<Vec<u8>, SQLError> {
141    let expression =
142        crate::bind_type_introspection_with_resolver(expression.clone(), schema, params, engine);
143    let expression = normalize_expression(engine, expression, schema, params)?;
144    serde_json::to_vec(&expression).map_err(|error| {
145        SQLError::Internal(format!(
146            "serialize GROUP BY DISTINCT expression identity: {error}"
147        ))
148    })
149}
150
151#[expect(
152    clippy::too_many_lines,
153    reason = "preserves SELECT schema and row identity"
154)]
155fn normalize_expression(
156    engine: &dyn FunctionTypeResolver,
157    expression: ScalarExpr,
158    schema: &RowSchema,
159    params: &[SQLParam],
160) -> Result<ScalarExpr, SQLError> {
161    Ok(match expression {
162        ScalarExpr::RetainedLiteral(mut literal) => {
163            let normalized = normalize_expression(engine, literal.materialize()?, schema, params)?;
164            match normalized {
165                ScalarExpr::TypedLiteral {
166                    bound_type: Some(ty),
167                    ty: declaration,
168                    collation_oid,
169                    ..
170                } => {
171                    literal.ty = ty;
172                    literal.collation_oid = collation_oid;
173                    literal.declaration = Some(declaration);
174                    ScalarExpr::RetainedLiteral(literal)
175                }
176                ScalarExpr::Literal(_) => {
177                    literal.collation_oid = None;
178                    literal.declaration = None;
179                    ScalarExpr::RetainedLiteral(literal)
180                }
181                other => other,
182            }
183        }
184        ScalarExpr::Column(column) => schema
185            .column_slot(&column)
186            .map_or(ScalarExpr::Column(column), ScalarExpr::Position),
187        ScalarExpr::QualifiedColumn { qualifier, column } => {
188            schema.qualified_slot(&qualifier, &column).map_or(
189                ScalarExpr::QualifiedColumn { qualifier, column },
190                ScalarExpr::Position,
191            )
192        }
193        ScalarExpr::Func {
194            order_syntax,
195            name,
196            binding,
197            args,
198            distinct,
199            order_by,
200            filter,
201        } => {
202            let name = canonical_function_name(name);
203            let argument_types = args
204                .iter()
205                .map(|argument| expression_type(engine, argument, schema, params))
206                .collect::<Result<Vec<_>, _>>()?;
207            let targets = crate::builtin_function_argument_targets(&name, &argument_types);
208            ScalarExpr::Func {
209                order_syntax,
210                name,
211                binding,
212                args: args
213                    .into_iter()
214                    .zip(targets)
215                    .map(|(argument, target)| {
216                        normalize_unknown_literal(engine, argument, target.as_ref(), schema, params)
217                    })
218                    .collect::<Result<Vec<_>, _>>()?,
219                distinct,
220                order_by: order_by
221                    .into_iter()
222                    .map(|mut order| {
223                        order.expr = normalize_expression(engine, order.expr, schema, params)?;
224                        Ok(order)
225                    })
226                    .collect::<Result<Vec<_>, SQLError>>()?,
227                filter: filter
228                    .map(|expression| {
229                        normalize_expression(engine, *expression, schema, params).map(Box::new)
230                    })
231                    .transpose()?,
232            }
233        }
234        ScalarExpr::Array(items) => {
235            ScalarExpr::Array(normalize_items(engine, items, schema, params)?)
236        }
237        ScalarExpr::Row(items) => ScalarExpr::Row(normalize_items(engine, items, schema, params)?),
238        ScalarExpr::CompositeRow {
239            items,
240            binding,
241            bound_type,
242        } => ScalarExpr::CompositeRow {
243            items: normalize_items(engine, items, schema, params)?,
244            binding: binding.clone(),
245            bound_type: bound_type.clone(),
246        },
247        ScalarExpr::Binary { op, lhs, rhs } => {
248            let left_type = expression_type(engine, &lhs, schema, params)?;
249            let right_type = expression_type(engine, &rhs, schema, params)?;
250            ScalarExpr::Binary {
251                op,
252                lhs: Box::new(normalize_unknown_literal(
253                    engine,
254                    *lhs,
255                    left_type.is_none().then_some(right_type.as_ref()).flatten(),
256                    schema,
257                    params,
258                )?),
259                rhs: Box::new(normalize_unknown_literal(
260                    engine,
261                    *rhs,
262                    right_type.is_none().then_some(left_type.as_ref()).flatten(),
263                    schema,
264                    params,
265                )?),
266            }
267        }
268        ScalarExpr::UnaryMinus(expression) => {
269            let expression = normalize_expression(engine, *expression, schema, params)?;
270            if let ScalarExpr::Literal(
271                value @ (Value::Int(_) | Value::Float(_) | Value::Decimal(_)),
272            ) = &expression
273            {
274                ScalarExpr::Literal(crate::expr::negate_value(value, None)?)
275            } else {
276                ScalarExpr::UnaryMinus(Box::new(expression))
277            }
278        }
279        ScalarExpr::Not(expression) => ScalarExpr::Not(Box::new(normalize_expression(
280            engine,
281            *expression,
282            schema,
283            params,
284        )?)),
285        ScalarExpr::And(items) => ScalarExpr::And(normalize_items(engine, items, schema, params)?),
286        ScalarExpr::Or(items) => ScalarExpr::Or(normalize_items(engine, items, schema, params)?),
287        ScalarExpr::IsNull { expr, negated } => ScalarExpr::IsNull {
288            expr: Box::new(normalize_expression(engine, *expr, schema, params)?),
289            negated,
290        },
291        ScalarExpr::Between { expr, low, high } => {
292            let target = expression_type(engine, &expr, schema, params)?;
293            ScalarExpr::Between {
294                expr: Box::new(normalize_expression(engine, *expr, schema, params)?),
295                low: Box::new(normalize_unknown_literal(
296                    engine,
297                    *low,
298                    target.as_ref(),
299                    schema,
300                    params,
301                )?),
302                high: Box::new(normalize_unknown_literal(
303                    engine,
304                    *high,
305                    target.as_ref(),
306                    schema,
307                    params,
308                )?),
309            }
310        }
311        ScalarExpr::InList {
312            expr,
313            list,
314            negated,
315        } => {
316            let target = expression_type(engine, &expr, schema, params)?;
317            ScalarExpr::InList {
318                expr: Box::new(normalize_expression(engine, *expr, schema, params)?),
319                list: list
320                    .into_iter()
321                    .map(|item| {
322                        normalize_unknown_literal(engine, item, target.as_ref(), schema, params)
323                    })
324                    .collect::<Result<Vec<_>, _>>()?,
325                negated,
326            }
327        }
328        ScalarExpr::WindowCall {
329            name,
330            args,
331            mut spec,
332            filter,
333            modifiers,
334        } => {
335            spec.partition_by = normalize_items(engine, spec.partition_by, schema, params)?;
336            for order in &mut spec.order_by {
337                order.expr = normalize_expression(engine, order.expr.clone(), schema, params)?;
338            }
339            if let Some(frame) = &mut spec.frame {
340                normalize_frame_bound(engine, &mut frame.start, schema, params)?;
341                normalize_frame_bound(engine, &mut frame.end, schema, params)?;
342            }
343            ScalarExpr::WindowCall {
344                modifiers,
345                name: canonical_function_name(name),
346                args: normalize_items(engine, args, schema, params)?,
347                spec,
348                filter: filter
349                    .map(|expression| {
350                        normalize_expression(engine, *expression, schema, params).map(Box::new)
351                    })
352                    .transpose()?,
353            }
354        }
355        ScalarExpr::Case {
356            base,
357            when,
358            else_branch,
359        } => ScalarExpr::Case {
360            base: base
361                .map(|expression| {
362                    normalize_expression(engine, *expression, schema, params).map(Box::new)
363                })
364                .transpose()?,
365            when: when
366                .into_iter()
367                .map(|(condition, result)| {
368                    Ok((
369                        normalize_expression(engine, condition, schema, params)?,
370                        normalize_expression(engine, result, schema, params)?,
371                    ))
372                })
373                .collect::<Result<Vec<_>, SQLError>>()?,
374            else_branch: else_branch
375                .map(|expression| {
376                    normalize_expression(engine, *expression, schema, params).map(Box::new)
377                })
378                .transpose()?,
379        },
380        ScalarExpr::Collated {
381            expr,
382            ty,
383            collation,
384        } => {
385            let mut expression = normalize_expression(engine, *expr, schema, params)?;
386            match (&mut expression, collation.implicit_oid()) {
387                (
388                    ScalarExpr::TypedLiteral {
389                        bound_type,
390                        collation_oid,
391                        ..
392                    },
393                    Some(oid),
394                ) if bound_type.as_ref() == Some(&ty) => {
395                    *collation_oid = Some(oid);
396                    normalize_expression(engine, expression, schema, params)?
397                }
398                _ => ScalarExpr::Collated {
399                    expr: Box::new(expression),
400                    ty,
401                    collation,
402                },
403            }
404        }
405        ScalarExpr::Cast { expr, ty, .. } => {
406            let source_type = expression_type(engine, &expr, schema, params)?;
407            let target_type = crate::type_resolution::resolve_declared_column_type(
408                engine,
409                &ColumnType::Named(ty),
410            )?;
411            let expression = normalize_expression(engine, *expr, schema, params)?;
412            if source_type.as_ref() == Some(&target_type) {
413                expression
414            } else if input_requires_catalog(&target_type) {
415                ScalarExpr::Cast {
416                    implicit: false,
417                    expr: Box::new(expression),
418                    ty: target_type.catalog_name(),
419                }
420            } else if let ScalarExpr::Literal(value @ Value::Str(_)) = &expression {
421                let input_type = if matches!(
422                    target_type.without_temporal_modifiers(),
423                    ColumnType::Interval
424                ) {
425                    target_type.clone()
426                } else {
427                    target_type.without_type_modifiers()
428                };
429                let value = crate::expr::cast_value(value, &input_type.sql_name())?;
430                let input = normalize_expression(
431                    engine,
432                    ScalarExpr::TypedLiteral {
433                        collation_oid: None,
434                        composite_source: None,
435                        value,
436                        ty: input_type.catalog_name(),
437                        bound_type: Some(input_type.clone()),
438                        parameter_index: None,
439                    },
440                    schema,
441                    params,
442                )?;
443                if input_type == target_type {
444                    input
445                } else {
446                    ScalarExpr::Cast {
447                        implicit: false,
448                        expr: Box::new(input),
449                        ty: target_type.catalog_name(),
450                    }
451                }
452            } else if let ScalarExpr::Literal(Value::Null) = expression {
453                ScalarExpr::TypedLiteral {
454                    collation_oid: None,
455                    composite_source: None,
456                    value: Value::Null,
457                    ty: target_type.catalog_name(),
458                    bound_type: Some(target_type),
459                    parameter_index: None,
460                }
461            } else {
462                ScalarExpr::Cast {
463                    implicit: false,
464                    expr: Box::new(expression),
465                    ty: target_type.catalog_name(),
466                }
467            }
468        }
469        ScalarExpr::InSubquery {
470            expr,
471            subquery,
472            negated,
473        } => ScalarExpr::InSubquery {
474            expr: Box::new(normalize_expression(engine, *expr, schema, params)?),
475            subquery,
476            negated,
477        },
478        ScalarExpr::TypedLiteral {
479            value,
480            ty,
481            bound_type,
482            parameter_index,
483            collation_oid,
484            composite_source,
485        } => {
486            let literal = ScalarExpr::Literal(value.clone());
487            let declared = match bound_type {
488                Some(ty) => ty,
489                None => crate::type_resolution::resolve_declared_column_type(
490                    engine,
491                    &ColumnType::Named(ty),
492                )?,
493            };
494            let collation_oid = collation_oid.filter(|oid| {
495                i64::from(*oid) != crate::catalog::type_metadata::pg_type_collation_oid(&declared)
496            });
497            if parameter_index.is_none()
498                && composite_source.is_none()
499                && collation_oid.is_none()
500                && expression_type(engine, &literal, schema, params)?.as_ref() == Some(&declared)
501            {
502                literal
503            } else {
504                ScalarExpr::TypedLiteral {
505                    collation_oid,
506                    composite_source,
507                    value,
508                    ty: declared.catalog_name(),
509                    bound_type: Some(declared),
510                    parameter_index,
511                }
512            }
513        }
514        expression @ (ScalarExpr::Star
515        | ScalarExpr::QualifiedStar(_)
516        | ScalarExpr::Default
517        | ScalarExpr::Position(_)
518        | ScalarExpr::InternalColumn(_)
519        | ScalarExpr::Literal(_)
520        | ScalarExpr::Param(_)
521        | ScalarExpr::ScalarSubquery(_)
522        | ScalarExpr::Exists { .. }) => expression,
523    })
524}
525
526fn input_requires_catalog(ty: &ColumnType) -> bool {
527    match ty {
528        ColumnType::Named(_)
529        | ColumnType::Domain { .. }
530        | ColumnType::Enum(_)
531        | ColumnType::Composite(_)
532        | ColumnType::Regproc
533        | ColumnType::Regprocedure
534        | ColumnType::Regclass
535        | ColumnType::Regcollation
536        | ColumnType::Regnamespace
537        | ColumnType::Regrole
538        | ColumnType::Regtype
539        | ColumnType::Record
540        | ColumnType::AnyArray => true,
541        ColumnType::Array(element) => input_requires_catalog(element),
542        _ => false,
543    }
544}
545
546fn normalize_items(
547    engine: &dyn FunctionTypeResolver,
548    items: Vec<ScalarExpr>,
549    schema: &RowSchema,
550    params: &[SQLParam],
551) -> Result<Vec<ScalarExpr>, SQLError> {
552    items
553        .into_iter()
554        .map(|item| normalize_expression(engine, item, schema, params))
555        .collect()
556}
557
558fn normalize_unknown_literal(
559    engine: &dyn FunctionTypeResolver,
560    expression: ScalarExpr,
561    target: Option<&ColumnType>,
562    schema: &RowSchema,
563    params: &[SQLParam],
564) -> Result<ScalarExpr, SQLError> {
565    if matches!(expression, ScalarExpr::Literal(Value::Null)) {
566        if let Some(target) = target {
567            return normalize_expression(
568                engine,
569                ScalarExpr::Cast {
570                    implicit: true,
571                    expr: Box::new(expression),
572                    ty: target.catalog_name(),
573                },
574                schema,
575                params,
576            );
577        }
578    }
579    normalize_expression(engine, expression, schema, params)
580}
581
582fn normalize_frame_bound(
583    engine: &dyn FunctionTypeResolver,
584    bound: &mut ScalarFrameBound,
585    schema: &RowSchema,
586    params: &[SQLParam],
587) -> Result<(), SQLError> {
588    match bound {
589        ScalarFrameBound::Preceding(expression) | ScalarFrameBound::Following(expression) => {
590            **expression = normalize_expression(engine, (**expression).clone(), schema, params)?;
591        }
592        ScalarFrameBound::UnboundedPreceding
593        | ScalarFrameBound::UnboundedFollowing
594        | ScalarFrameBound::CurrentRow => {}
595    }
596    Ok(())
597}
598
599fn expression_type(
600    engine: &dyn FunctionTypeResolver,
601    expression: &ScalarExpr,
602    schema: &RowSchema,
603    params: &[SQLParam],
604) -> Result<Option<ColumnType>, SQLError> {
605    crate::scalar_type_with_resolver(expression, schema, params, engine)
606}
607
608fn canonical_function_name(name: String) -> String {
609    let lower = name.to_ascii_lowercase();
610    match lower.strip_prefix("pg_catalog.") {
611        Some(unqualified) => unqualified.to_owned(),
612        None => lower,
613    }
614}