uqa-sql 0.6.3

PostgreSQL-compatible SQL compiler built on libpg_query
Documentation
//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

//! GROUP BY input-column precedence and output-name fallback after source binding.

use std::borrow::Cow;

use crate::plan::{ProjectionPlan, QueryBlockPlan};
use crate::routines::RoutineResolution;
use crate::{RowSchema, SQLError, SQLParam, ScalarExpr};

/// An unqualified input column wins even when its lookup is ambiguous. Output names are considered only for a whole bare name, never inside an expression. `schema` holds the query's own columns over `outer`, the scope of the queries that enclose it, whose columns do not take a name before an output column.
pub fn resolve_grouping_expression<'a>(
    routines: &dyn RoutineResolution,
    expression: &'a ScalarExpr,
    projections: &'a [ProjectionPlan],
    schema: &RowSchema,
    outer: Option<&RowSchema>,
    params: &[SQLParam],
) -> Result<Cow<'a, ScalarExpr>, SQLError> {
    let resolved = resolve_grouping_expression_reference(
        routines,
        expression,
        projections,
        schema,
        outer,
        params,
    )?;
    Ok(if std::ptr::eq(resolved, expression) {
        Cow::Borrowed(expression)
    } else {
        Cow::Owned(resolved.clone())
    })
}

/// Borrow the original grouped expression or its projection, preserving input-literal identity during prepared analysis.
pub(crate) fn resolve_grouping_expression_reference<'a>(
    routines: &dyn RoutineResolution,
    expression: &'a ScalarExpr,
    projections: &'a [ProjectionPlan],
    schema: &RowSchema,
    outer: Option<&RowSchema>,
    params: &[SQLParam],
) -> Result<&'a ScalarExpr, SQLError> {
    resolve_grouping_expression_reference_with_control(
        routines,
        expression,
        projections,
        schema,
        outer,
        params,
        &uqa_core::memory::ProductionControl::uncontrolled(),
    )
}

pub(crate) fn resolve_grouping_expression_reference_with_control<'a>(
    routines: &dyn RoutineResolution,
    expression: &'a ScalarExpr,
    projections: &'a [ProjectionPlan],
    schema: &RowSchema,
    outer: Option<&RowSchema>,
    params: &[SQLParam],
    control: &uqa_core::memory::ProductionControl<'_>,
) -> Result<&'a ScalarExpr, SQLError> {
    control.check()?;
    let mut resolved = expression;
    if let Some(name) = grouping_output_name(expression, schema, outer) {
        let mut matches = projections
            .iter()
            .filter(|projection| crate::semantics::projection_label_at(projection) == name);
        if let Some(first) = matches.next() {
            resolved = &first.expr;
            let mut identity = None;
            for candidate in matches {
                control.check()?;
                let first_identity = match &identity {
                    Some(identity) => identity,
                    None => identity.insert(super::expression_identity_with_control(
                        routines, resolved, schema, params, control,
                    )?),
                };
                if *first_identity
                    != super::expression_identity_with_control(
                        routines,
                        &candidate.expr,
                        schema,
                        params,
                        control,
                    )?
                {
                    return Err(SQLError::Routine {
                        sqlstate: "42702".into(),
                        message: control
                            .format(format_args!("GROUP BY \"{name}\" is ambiguous"))?
                            .into_parts()
                            .0,
                    });
                }
            }
        }
    }
    if crate::semantics::aggregates::contains_aggregate(
        &|name: &str| routines.has_registered_aggregate_function(name),
        resolved,
    ) {
        return Err(SQLError::Routine {
            sqlstate: "42803".into(),
            message: "aggregate functions are not allowed in GROUP BY".into(),
        });
    }
    if resolved.contains_window() {
        return Err(SQLError::Routine {
            sqlstate: "42P20".into(),
            message: "window functions are not allowed in GROUP BY".into(),
        });
    }
    Ok(resolved)
}

/// A bare GROUP BY name can select an output only when no input column at this query level takes it. Compound expressions and enclosing columns do not select outputs.
pub fn grouping_output_name<'a>(
    expression: &'a ScalarExpr,
    schema: &RowSchema,
    outer: Option<&RowSchema>,
) -> Option<&'a str> {
    match expression {
        ScalarExpr::Column(name) if !is_input_column(schema, outer, name) => Some(name),
        _ => None,
    }
}

/// Whether `name` is a column of the query's own sources, ambiguous or not, in `schema`, which holds those columns over `outer`: `findTargetlistEntrySQL92` looks for a GROUP BY name among the columns of the query's own level only.
fn is_input_column(schema: &RowSchema, outer: Option<&RowSchema>, name: &str) -> bool {
    if !schema.has_unqualified_column(name) {
        return false;
    }
    let Some(outer) = outer else {
        return true;
    };
    let own_width = schema
        .physical_width()
        .saturating_sub(outer.physical_width());
    schema.column_slot(name).is_none_or(|slot| slot < own_width)
}

/// Bind grouping expressions before storing a query or executing its aggregation. Returns whether an output name was replaced.
pub fn bind_grouping_names(
    routines: &dyn RoutineResolution,
    statement: &mut QueryBlockPlan,
    schema: &RowSchema,
    outer: Option<&RowSchema>,
    params: &[SQLParam],
) -> Result<bool, SQLError> {
    let mut changed = false;
    for expression in statement
        .group_by
        .iter_mut()
        .chain(statement.grouping_sets.iter_mut().flatten())
    {
        if let Cow::Owned(resolved) = resolve_grouping_expression(
            routines,
            expression,
            &statement.projections,
            schema,
            outer,
            params,
        )? {
            *expression = resolved;
            changed = true;
        }
    }
    Ok(changed)
}

/// Bind the original GROUP BY sequence while transferring each selected scalar's independent constructor owner.
pub fn bind_grouping_names_owned(
    routines: &dyn RoutineResolution,
    mut query: crate::plan::MutableQueryPlan,
    schema: &RowSchema,
    outer: Option<&RowSchema>,
    params: &[SQLParam],
    control: &uqa_core::memory::ProductionControl<'_>,
) -> Result<crate::plan::MutableQueryPlan, SQLError> {
    control.check()?;
    let crate::plan::RelationalPlan::QueryBlock(block) = &query.root else {
        return Err(SQLError::Internal(
            "grouping names require a query block".into(),
        ));
    };
    let groups = block.group_by.len();
    let sets = block.grouping_sets.len();
    for index in 0..groups {
        query = bind_owned_grouping_slot(
            routines,
            query,
            crate::plan::QueryScalarSlot::GroupBy(index),
            schema,
            outer,
            params,
            control,
        )?;
    }
    for set in 0..sets {
        let crate::plan::RelationalPlan::QueryBlock(block) = &query.root else {
            unreachable!("original grouping block")
        };
        let count = block.grouping_sets[set].len();
        for expression in 0..count {
            query = bind_owned_grouping_slot(
                routines,
                query,
                crate::plan::QueryScalarSlot::GroupingSet { set, expression },
                schema,
                outer,
                params,
                control,
            )?;
        }
    }
    Ok(query)
}

fn bind_owned_grouping_slot(
    routines: &dyn RoutineResolution,
    query: crate::plan::MutableQueryPlan,
    slot: crate::plan::QueryScalarSlot,
    schema: &RowSchema,
    outer: Option<&RowSchema>,
    params: &[SQLParam],
    control: &uqa_core::memory::ProductionControl<'_>,
) -> Result<crate::plan::MutableQueryPlan, SQLError> {
    query.map_scalar_with_parent(slot, control, |parent, expression| {
        let crate::plan::RelationalPlan::QueryBlock(block) = &parent.root else {
            unreachable!("original grouping block")
        };
        let selected = resolve_grouping_expression_reference_with_control(
            routines,
            &expression,
            &block.projections,
            schema,
            outer,
            params,
            control,
        )?;
        if std::ptr::eq(selected, std::ptr::from_ref(&*expression)) {
            Ok(expression)
        } else {
            Ok(selected.copy_for_rewrite(control)?)
        }
    })
}