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