Skip to main content

uqa_execution/aggregation/
rewrite.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Aggregate expression replacement, input extraction, and observation.
8
9use super::{
10    eval_scalar, AggregateAccumulator, AggregateAccumulatorTemplate, SQLError, ScalarEvalContext,
11    ScalarExpr, ScalarOrder, Value,
12};
13
14pub fn aggregate_input_value(
15    name: &str,
16    args: &[ScalarExpr],
17    order_by: &[ScalarOrder],
18    ctx: &ScalarEvalContext<'_>,
19) -> Result<Value, SQLError> {
20    if name.eq_ignore_ascii_case("count") && (args.is_empty() || matches!(args, [ScalarExpr::Star]))
21    {
22        return Ok(Value::Int(1));
23    }
24    // Ordered-set aggregates: the percentile / mode fraction is a
25    // direct positional argument; the value to fold comes from
26    // `WITHIN GROUP (ORDER BY ...)` which the compiler parks in
27    // `order_by[0]`.
28    if is_ordered_set_aggregate(name) {
29        return order_by
30            .first()
31            .map(|ob| eval_scalar(&ob.expr, ctx))
32            .transpose()
33            .map(|v| v.unwrap_or(Value::Null));
34    }
35    if name.eq_ignore_ascii_case("string_agg") {
36        let [value, delimiter] = args else {
37            return Err(SQLError::TypeMismatch(
38                "string_agg requires 2 arguments".into(),
39            ));
40        };
41        let value = eval_scalar(value, ctx)?;
42        let delimiter = eval_scalar(delimiter, ctx)?;
43        return Ok(if matches!(value, Value::Null) {
44            Value::Null
45        } else {
46            Value::List(vec![value, delimiter])
47        });
48    }
49    if is_json_object_aggregate(name) {
50        return match args {
51            [key_expr, value_expr] => {
52                let key = eval_scalar(key_expr, ctx)?;
53                if matches!(key, Value::Null) {
54                    return Err(json_object_aggregate_null_key(name));
55                }
56                let value = eval_scalar(value_expr, ctx)?;
57                Ok(Value::List(vec![key, value]))
58            }
59            _ => Err(SQLError::TypeMismatch(format!(
60                "{name} requires 2 arguments"
61            ))),
62        };
63    }
64    if is_json_array_aggregate(name) {
65        return match args {
66            [arg] => eval_scalar(arg, ctx),
67            _ => Err(SQLError::TypeMismatch(format!(
68                "{name} requires 1 argument"
69            ))),
70        };
71    }
72    let arg = args
73        .first()
74        .ok_or_else(|| SQLError::Internal("aggregate missing arg".into()))?;
75    eval_scalar(arg, ctx)
76}
77
78pub fn aggregate_input_values(
79    args: &[ScalarExpr],
80    ctx: &ScalarEvalContext<'_>,
81) -> Result<Vec<Value>, SQLError> {
82    args.iter()
83        .map(|arg| match arg {
84            ScalarExpr::Star => Ok(Value::Int(1)),
85            other => eval_scalar(other, ctx),
86        })
87        .collect()
88}
89
90pub fn new_aggregate_accumulators_with_budget(
91    context: &dyn crate::functions::AggregateFunctionRegistry,
92    aggregate_targets: &[ScalarExpr],
93    input_schema: &crate::RowSchema,
94    params: &[uqa_sql::SQLParam],
95    budget_bytes: usize,
96) -> Result<Vec<AggregateAccumulator>, SQLError> {
97    Ok(instantiate_aggregate_accumulators(
98        &aggregate_accumulator_templates(context, aggregate_targets, input_schema, params)?,
99        budget_bytes,
100    ))
101}
102
103pub fn aggregate_accumulator_templates(
104    context: &dyn crate::functions::AggregateFunctionRegistry,
105    aggregate_targets: &[ScalarExpr],
106    input_schema: &crate::RowSchema,
107    params: &[uqa_sql::SQLParam],
108) -> Result<Vec<AggregateAccumulatorTemplate>, SQLError> {
109    let has_enums = context
110        .enum_labels()
111        .is_some_and(uqa_sql::expr::enums::EnumLabelCatalog::has_enum_types);
112    aggregate_targets
113        .iter()
114        .map(|expression| match expression {
115            ScalarExpr::Func {
116                name,
117                args,
118                distinct,
119                order_by,
120                ..
121            } => {
122                let mut ordering_types = order_by
123                    .iter()
124                    .map(|key| {
125                        crate::scalar_type_with_resolver(&key.expr, input_schema, params, context)
126                    })
127                    .collect::<Result<Vec<_>, _>>()?;
128                if let Some(function) = context.registered_aggregate_function(name) {
129                    let mut template = AggregateAccumulatorTemplate::registered(function);
130                    if *distinct {
131                        ordering_types.extend(
132                            args.iter()
133                                .map(|argument| {
134                                    crate::scalar_type_with_resolver(
135                                        argument,
136                                        input_schema,
137                                        params,
138                                        context,
139                                    )
140                                })
141                                .collect::<Result<Vec<_>, _>>()?,
142                        );
143                        template = template.with_distinct_arguments(args.len());
144                    }
145                    return Ok(template
146                        .with_ordering(if has_enums { ordering_types.len() } else { 0 })
147                        .with_ordering_types(ordering_types));
148                }
149                let input_type = args
150                    .first()
151                    .map(|argument| {
152                        crate::scalar_type_with_resolver(argument, input_schema, params, context)
153                    })
154                    .transpose()?
155                    .flatten();
156                let mut template = AggregateAccumulatorTemplate::builtin(name, input_type.as_ref());
157                if *distinct {
158                    if is_json_object_aggregate(name) || name.eq_ignore_ascii_case("string_agg") {
159                        ordering_types.push(input_type.clone());
160                        ordering_types.extend(
161                            args.iter()
162                                .skip(1)
163                                .map(|argument| {
164                                    crate::scalar_type_with_resolver(
165                                        argument,
166                                        input_schema,
167                                        params,
168                                        context,
169                                    )
170                                })
171                                .collect::<Result<Vec<_>, _>>()?,
172                        );
173                        template = template.with_distinct_arguments(args.len());
174                    } else {
175                        ordering_types.push(if is_ordered_set_aggregate(name) {
176                            ordering_types.first().cloned().flatten()
177                        } else {
178                            input_type.clone()
179                        });
180                    }
181                }
182                Ok(template
183                    .with_ordering(if has_enums { ordering_types.len() } else { 0 })
184                    .with_ordering_types(ordering_types))
185            }
186            _ => Ok(AggregateAccumulatorTemplate::generic()),
187        })
188        .collect()
189}
190
191pub fn instantiate_aggregate_accumulators(
192    templates: &[AggregateAccumulatorTemplate],
193    budget_bytes: usize,
194) -> Vec<AggregateAccumulator> {
195    templates
196        .iter()
197        .map(|template| template.instantiate(budget_bytes))
198        .collect()
199}
200
201pub fn observe_aggregate(
202    acc: &mut AggregateAccumulator,
203    name: &str,
204    args: &[ScalarExpr],
205    distinct: bool,
206    order_by: &[ScalarOrder],
207    ctx: &ScalarEvalContext<'_>,
208) -> Result<(), SQLError> {
209    let enums = ctx
210        .function_hook()
211        .and_then(uqa_sql::expr::EngineHook::enum_labels);
212    if acc.registered.is_some() {
213        let values = uqa_sql::expr::enums::render_host_arguments(
214            ctx.function_hook()
215                .and_then(uqa_sql::expr::EngineHook::enum_labels),
216            &aggregate_input_values(args, ctx)?,
217        )?;
218        let mut sort_keys: Vec<super::ordering::AggregateSortKey> =
219            Vec::with_capacity(order_by.len());
220        for ob in order_by {
221            let v = eval_scalar(&ob.expr, ctx)?;
222            sort_keys.push(super::ordering::AggregateSortKey::ordered(v, ob));
223        }
224        if distinct {
225            return acc.distinct.insert(&Value::List(values), sort_keys, enums);
226        }
227        acc.observe_registered(values, sort_keys, enums)?;
228        return Ok(());
229    }
230
231    let value = aggregate_input_value(name, args, order_by, ctx)?;
232    observe_builtin_aggregate_value(acc, &value, distinct, order_by, ctx)
233}
234
235/// The accumulator's state plan decides whether a NULL input reaches the aggregate.
236pub fn observe_builtin_aggregate_value(
237    acc: &mut AggregateAccumulator,
238    value: &Value,
239    distinct: bool,
240    order_by: &[ScalarOrder],
241    ctx: &ScalarEvalContext<'_>,
242) -> Result<(), SQLError> {
243    let enums = ctx
244        .function_hook()
245        .and_then(uqa_sql::expr::EngineHook::enum_labels);
246    let mut sort_keys: Vec<super::ordering::AggregateSortKey> = Vec::with_capacity(order_by.len());
247    for ob in order_by {
248        let v = eval_scalar(&ob.expr, ctx)?;
249        sort_keys.push(super::ordering::AggregateSortKey::ordered(v, ob));
250    }
251    if distinct {
252        if acc.admits_null_input() || !matches!(value, Value::Null) {
253            acc.distinct.insert(value, sort_keys, enums)?;
254        }
255        return Ok(());
256    }
257    if order_by.is_empty() {
258        acc.observe_with_enum_catalog(value, enums)
259    } else {
260        acc.observe_with_sort_keys(value, sort_keys, enums)
261    }
262}
263
264pub fn is_json_array_aggregate(name: &str) -> bool {
265    name.eq_ignore_ascii_case("json_agg") || name.eq_ignore_ascii_case("jsonb_agg")
266}
267
268/// The transition-function error of `json_object_agg` and `jsonb_object_agg` for a NULL key.
269pub(super) fn json_object_aggregate_null_key(name: &str) -> SQLError {
270    if name.eq_ignore_ascii_case("jsonb_object_agg") {
271        SQLError::Routine {
272            sqlstate: "22023".into(),
273            message: "field name must not be null".into(),
274        }
275    } else {
276        SQLError::Routine {
277            sqlstate: "22004".into(),
278            message: "null value not allowed for object key".into(),
279        }
280    }
281}
282
283pub fn is_json_object_aggregate(name: &str) -> bool {
284    name.eq_ignore_ascii_case("json_object_agg") || name.eq_ignore_ascii_case("jsonb_object_agg")
285}
286
287pub fn is_ordered_set_aggregate(name: &str) -> bool {
288    name.eq_ignore_ascii_case("percentile_cont")
289        || name.eq_ignore_ascii_case("percentile_disc")
290        || name.eq_ignore_ascii_case("mode")
291}