Skip to main content

uqa_execution/relational/
aggregate.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Blocking hash/sort aggregation and aggregate folds.
8
9use super::{
10    compare_values, eval_scalar, Batch, DefaultExpressionEvaluator, ExecError, ExecResult,
11    PhysicalOperator, RowSchema, SQLParam, ScalarEvalContext, ScalarExpr, SortKey, Value,
12};
13use crate::ProjectedRow;
14
15mod adaptive;
16mod fold;
17mod partial;
18mod sort_fallback;
19
20pub(super) use fold::value_to_f64;
21#[cfg(test)]
22pub(super) use fold::{finalise_fold, AggFold};
23
24#[derive(Debug, Clone, Copy, PartialEq, Eq)]
25pub enum AggregateKind {
26    Count,
27    CountStar,
28    Sum,
29    Avg,
30    Min,
31    Max,
32}
33
34#[derive(Debug, Clone)]
35pub struct AggregateSpec {
36    pub kind: AggregateKind,
37    /// Argument to the aggregate. Ignored for `CountStar`.
38    pub arg: Option<ScalarExpr>,
39    /// Output column alias.
40    pub alias: String,
41    /// `COUNT(DISTINCT x)` / `SUM(DISTINCT x)` / etc.
42    pub distinct: bool,
43}
44
45/// Blocking group-by + aggregate. Pulls every row from the child
46/// during `open`, hashes each row by its group key, and folds the
47/// aggregates over each group's row set. Groups are emitted in the
48/// order they were first observed.
49pub trait AggregateExecutor: Send {
50    /// Consume one child batch. Implementations that need a blocking input must
51    /// enforce their own byte budget here; the physical operator never creates
52    /// an unbounded intermediate row vector.
53    fn consume(&mut self, batch: Batch) -> ExecResult<()>;
54
55    /// Whether this executor can fold a borrowed, positional row without a
56    /// materialized `ResultRow`. A source checks this before advancing.
57    fn supports_projected_rows(&self) -> bool {
58        false
59    }
60
61    /// Whether projected-row consumption is guaranteed not to call back into the engine while a storage backend lends its row values. Sources use this stricter capability before invoking an executor under a backend read borrow.
62    fn supports_storage_borrowed_rows(&self) -> bool {
63        false
64    }
65
66    /// Fold one projected row. Implementations advertising support must
67    /// preserve the same expression and aggregate semantics as [`Self::consume`].
68    fn consume_projected_row(&mut self, _row: &ProjectedRow<'_, '_>) -> ExecResult<()> {
69        Err(ExecError::Other(
70            "aggregate executor does not accept projected rows".into(),
71        ))
72    }
73
74    /// Finalize all groups into a byte-bounded, disk-backed output stream.
75    /// The row-oriented SQL API may materialize that stream at its public API
76    /// boundary, but physical operators must not create an unbounded result
77    /// vector first.
78    fn finish(&mut self) -> ExecResult<crate::spill::SpillBuffer>;
79
80    /// Release retained state after completion or early termination. Cleanup
81    /// errors must reach the statement before it can report success or commit.
82    /// Repeated calls must not release the same resources again.
83    fn close(&mut self) -> ExecResult<()> {
84        Ok(())
85    }
86}
87
88pub struct HashAggregate<'a> {
89    child: Box<dyn PhysicalOperator + 'a>,
90    group_keys: Vec<(String, ScalarExpr)>,
91    aggregates: Vec<AggregateSpec>,
92    params: Vec<SQLParam>,
93    schema: RowSchema,
94    executor: Option<Box<dyn AggregateExecutor + 'a>>,
95    work_mem_bytes: usize,
96    output: Option<crate::spill::SpillDrain>,
97    output_spilled: bool,
98}
99
100impl HashAggregate<'static> {
101    const DEFAULT_WORK_MEM_BYTES: usize = 64 * 1024 * 1024;
102
103    pub fn new(
104        child: Box<dyn PhysicalOperator>,
105        group_keys: Vec<(String, ScalarExpr)>,
106        aggregates: Vec<AggregateSpec>,
107        params: Vec<SQLParam>,
108    ) -> Self {
109        Self::new_with_work_mem(
110            child,
111            group_keys,
112            aggregates,
113            params,
114            Self::DEFAULT_WORK_MEM_BYTES,
115        )
116    }
117
118    pub fn new_with_work_mem(
119        child: Box<dyn PhysicalOperator>,
120        group_keys: Vec<(String, ScalarExpr)>,
121        aggregates: Vec<AggregateSpec>,
122        params: Vec<SQLParam>,
123        work_mem_bytes: usize,
124    ) -> Self {
125        let mut cols: Vec<String> = group_keys.iter().map(|(n, _)| n.clone()).collect();
126        for a in &aggregates {
127            cols.push(a.alias.clone());
128        }
129        let schema = RowSchema::new(cols);
130        Self {
131            child,
132            group_keys,
133            aggregates,
134            params,
135            schema,
136            executor: None,
137            work_mem_bytes,
138            output: None,
139            output_spilled: false,
140        }
141    }
142}
143
144impl<'a> HashAggregate<'a> {
145    /// Construct a physical aggregate backed by the engine's full aggregate
146    /// registry. Input is delivered incrementally through
147    /// [`AggregateExecutor::consume`].
148    pub fn with_executor(
149        child: Box<dyn PhysicalOperator + 'a>,
150        output_schema: Vec<String>,
151        executor: Box<dyn AggregateExecutor + 'a>,
152    ) -> Self {
153        let types = vec![None; output_schema.len()];
154        Self::with_typed_executor(child, output_schema, types, executor)
155    }
156
157    pub fn with_typed_executor(
158        child: Box<dyn PhysicalOperator + 'a>,
159        output_schema: Vec<String>,
160        output_types: Vec<Option<uqa_sql::ast::ColumnType>>,
161        executor: Box<dyn AggregateExecutor + 'a>,
162    ) -> Self {
163        Self {
164            child,
165            group_keys: Vec::new(),
166            aggregates: Vec::new(),
167            params: Vec::new(),
168            schema: RowSchema::with_types(output_schema, output_types),
169            executor: Some(executor),
170            work_mem_bytes: 0,
171            output: None,
172            output_spilled: false,
173        }
174    }
175
176    /// Whether final aggregate rows exceeded their output budget and were
177    /// written to disk during the current/most recent invocation.
178    pub fn output_has_spilled(&self) -> bool {
179        self.output_spilled
180    }
181}
182
183impl PhysicalOperator for HashAggregate<'_> {
184    fn row_schema(&self) -> &RowSchema {
185        &self.schema
186    }
187
188    fn open(&mut self) -> ExecResult<()> {
189        self.child.open()?;
190        self.output_spilled = false;
191        if let Some(executor) = self.executor.as_mut() {
192            let consumed_directly = executor.supports_projected_rows()
193                && self.child.consume_into_aggregate(executor.as_mut())?;
194            if !consumed_directly {
195                while let Some(batch) = self.child.next()? {
196                    executor.consume(batch)?;
197                }
198            }
199            let mut output = executor.finish()?;
200            self.output_spilled = output.has_spilled();
201            self.output = Some(output.drain()?);
202            return Ok(());
203        }
204        let mut output = if adaptive::supported(&self.group_keys, &self.aggregates) {
205            let mut aggregate = adaptive::AdaptiveBuiltinAggregate::new(
206                &self.group_keys,
207                &self.aggregates,
208                &self.params,
209                self.work_mem_bytes,
210            );
211            while let Some(batch) = self.child.next()? {
212                aggregate.consume(batch)?;
213            }
214            aggregate.finish(self.schema.clone())?
215        } else {
216            sort_fallback::execute(
217                self.child.as_mut(),
218                &self.group_keys,
219                &self.aggregates,
220                &self.params,
221                self.schema.clone(),
222                self.work_mem_bytes,
223            )?
224        };
225        self.output_spilled = output.has_spilled();
226        self.output = Some(output.drain()?);
227        Ok(())
228    }
229
230    fn next(&mut self) -> ExecResult<Option<Batch>> {
231        let Some(output) = self.output.as_mut() else {
232            return Ok(None);
233        };
234        output.next().transpose()
235    }
236
237    fn close(&mut self) -> ExecResult<()> {
238        self.output = None;
239        let executor = self
240            .executor
241            .as_mut()
242            .map_or(Ok(()), |executor| executor.close());
243        crate::physical::with_cleanup(executor, self.child.close(), "close aggregate input")
244    }
245}
246
247// -------------------------------------------------------------------------
248// Window
249// -------------------------------------------------------------------------