Skip to main content

uqa_execution/aggregation/
executor.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! `QueryExpressionContext` adapter selecting adaptive or sort aggregation per grouping set.
8
9use super::{QueryBlockPlan, QueryExpressionContext, SQLError, SQLParam, SpillBuffer};
10use crate::{AggregateExecutor, Batch, ExecResult, ProjectedRow, RowSchema};
11
12enum AggregateSet {
13    Adaptive(Box<super::adaptive::AdaptiveAggregateSet>),
14    Sorted {
15        statement: Box<QueryBlockPlan>,
16        relaxed: bool,
17        input: SpillBuffer,
18        phase_budget: usize,
19        optimistic: Option<Box<super::adaptive::AdaptiveAggregateSet>>,
20    },
21}
22
23impl AggregateSet {
24    fn close(&mut self) -> Result<(), SQLError> {
25        match self {
26            Self::Adaptive(set) => set.close(),
27            Self::Sorted { optimistic, .. } => {
28                optimistic.as_mut().map_or(Ok(()), |set| set.close())
29            }
30        }
31    }
32}
33
34pub struct PhysicalAggregateExecutor<'a> {
35    context: std::sync::Arc<dyn QueryExpressionContext + 'a>,
36    params: &'a [SQLParam],
37
38    input_row_schema: RowSchema,
39    output_schema: RowSchema,
40    output_budget: usize,
41    outer: Option<super::AggregateOuterRow>,
42    sets: Option<Vec<AggregateSet>>,
43}
44
45impl<'a> PhysicalAggregateExecutor<'a> {
46    pub fn new(
47        context: std::sync::Arc<dyn QueryExpressionContext + 'a>,
48        statement: &QueryBlockPlan,
49        params: &'a [SQLParam],
50
51        input_schema: RowSchema,
52        output_schema: RowSchema,
53        work_mem_bytes: usize,
54    ) -> Result<Self, SQLError> {
55        Self::with_outer_scope(
56            context,
57            statement,
58            params,
59            input_schema,
60            output_schema,
61            work_mem_bytes,
62            None,
63        )
64    }
65
66    pub(crate) fn with_outer_scope(
67        context: std::sync::Arc<dyn QueryExpressionContext + 'a>,
68        statement: &QueryBlockPlan,
69        params: &'a [SQLParam],
70        input_schema: RowSchema,
71        output_schema: RowSchema,
72        work_mem_bytes: usize,
73        outer: Option<super::AggregateOuterRow>,
74    ) -> Result<Self, SQLError> {
75        let runtime = context;
76        let context = runtime.as_ref();
77        let statements = grouping_set_statements(context, statement)?;
78        let set_budget = (work_mem_bytes / statements.len().max(1)).max(1);
79        let sets = statements
80            .into_iter()
81            .map(|(statement, relaxed)| {
82                let mut support = uqa_sql::type_resolution::ComparisonKeySupport::default();
83                for key in &statement.group_by {
84                    if let Some(ty) =
85                        crate::scalar_type_with_resolver(key, &input_schema, params, context)?
86                    {
87                        support.include(&ty, context)?;
88                    }
89                }
90                support.require_implementation("GROUP BY")?;
91                if support.hashing
92                    && super::adaptive::supports_adaptive_grouping(context, &statement)
93                {
94                    return super::adaptive::AdaptiveAggregateSet::new(
95                        context,
96                        statement,
97                        relaxed,
98                        set_budget,
99                        &input_schema,
100                        params,
101                        outer.as_ref(),
102                    )
103                    .map(|set| AggregateSet::Adaptive(Box::new(set)));
104                }
105                let phase_budget = (set_budget / 3).max(1);
106                let optimistic = if support.hashing
107                    && super::adaptive::supports_optimistic_grouping(context, &statement)
108                {
109                    Some(Box::new(
110                        super::adaptive::AdaptiveAggregateSet::new_optimistic(
111                            context,
112                            statement.clone(),
113                            relaxed,
114                            (set_budget / 2).max(1),
115                            phase_budget,
116                            &input_schema,
117                            params,
118                            outer.as_ref(),
119                        )?,
120                    ))
121                } else {
122                    None
123                };
124                let input_budget = if optimistic.is_some() {
125                    (set_budget / 2).max(1)
126                } else {
127                    phase_budget
128                };
129                Ok(AggregateSet::Sorted {
130                    statement: Box::new(statement),
131                    relaxed,
132                    input: SpillBuffer::new(input_budget),
133                    phase_budget,
134                    optimistic,
135                })
136            })
137            .collect::<Result<Vec<_>, SQLError>>()?;
138        Ok(Self {
139            context: runtime,
140            params,
141
142            input_row_schema: input_schema,
143            output_schema,
144            output_budget: (work_mem_bytes / 3).max(1),
145            outer,
146            sets: Some(sets),
147        })
148    }
149
150    fn finish_set(&self, set: AggregateSet) -> Result<SpillBuffer, SQLError> {
151        match set {
152            AggregateSet::Adaptive(set) => {
153                (*set).finish(self.context.as_ref(), &self.output_schema, self.params)
154            }
155            AggregateSet::Sorted {
156                statement,
157                relaxed,
158                input,
159                phase_budget,
160                optimistic,
161            } => {
162                if let Some(optimistic) = optimistic {
163                    debug_assert!(!optimistic.is_abandoned());
164                    drop(input);
165                    return (*optimistic).finish(
166                        self.context.as_ref(),
167                        &self.output_schema,
168                        self.params,
169                    );
170                }
171                super::sort_fallback::aggregate_sorted_input(
172                    self.context.as_ref(),
173                    &statement,
174                    input,
175                    &self.input_row_schema,
176                    &self.output_schema,
177                    self.params,
178                    phase_budget,
179                    relaxed,
180                    self.outer.as_ref(),
181                )
182            }
183        }
184    }
185}
186
187impl AggregateExecutor for PhysicalAggregateExecutor<'_> {
188    fn consume(&mut self, batch: Batch) -> ExecResult<()> {
189        let sets = self
190            .sets
191            .as_mut()
192            .ok_or_else(|| crate::ExecError::Other("aggregate executor is closed".into()))?;
193        for set in sets {
194            match set {
195                AggregateSet::Adaptive(set) => {
196                    set.consume(self.context.as_ref(), &batch, self.params)?;
197                }
198                AggregateSet::Sorted {
199                    input, optimistic, ..
200                } => {
201                    input.push(batch.clone())?;
202                    if let Some(candidate) = optimistic.as_mut() {
203                        candidate.consume(self.context.as_ref(), &batch, self.params)?;
204                        if candidate.is_abandoned() {
205                            *optimistic = None;
206                        }
207                    }
208                }
209            }
210        }
211        Ok(())
212    }
213
214    fn supports_projected_rows(&self) -> bool {
215        self.sets.as_ref().is_some_and(|sets| {
216            sets.iter().all(|set| {
217            matches!(set, AggregateSet::Adaptive(set) if set.statement_subqueries_are_empty())
218        })
219        })
220    }
221
222    fn supports_storage_borrowed_rows(&self) -> bool {
223        self.sets.as_ref().is_some_and(|sets| {
224            sets.iter().all(|set| {
225            matches!(set, AggregateSet::Adaptive(set) if set.supports_storage_borrowed_rows())
226        })
227        })
228    }
229
230    fn consume_projected_row(&mut self, row: &ProjectedRow<'_, '_>) -> ExecResult<()> {
231        let sets = self
232            .sets
233            .as_mut()
234            .ok_or_else(|| crate::ExecError::Other("aggregate executor is closed".into()))?;
235        for set in sets {
236            let AggregateSet::Adaptive(set) = set else {
237                return Err(crate::ExecError::Other(
238                    "sort aggregate cannot consume a projected row".into(),
239                ));
240            };
241            set.consume_projected_row(self.context.as_ref(), row, self.params)?;
242        }
243        Ok(())
244    }
245
246    fn finish(&mut self) -> ExecResult<SpillBuffer> {
247        let mut sets = self
248            .sets
249            .take()
250            .ok_or_else(|| crate::ExecError::Other("aggregate executor is closed".into()))?;
251        if sets.len() == 1 {
252            let set = sets.pop().ok_or_else(|| {
253                crate::ExecError::Other("aggregate grouping set disappeared".into())
254            })?;
255            return self.finish_set(set).map_err(Into::into);
256        }
257
258        let mut output = SpillBuffer::new(self.output_budget);
259        let mut expected_output_rows = 0usize;
260        let mut remaining = sets.into_iter();
261        let execution = (|| {
262            for set in remaining.by_ref() {
263                let mut set_output = self.finish_set(set)?;
264                expected_output_rows = expected_output_rows
265                    .checked_add(set_output.rows())
266                    .ok_or_else(|| {
267                        crate::ExecError::Other("aggregate output row count overflow".into())
268                    })?;
269                copy_output(&mut set_output, &mut output)?;
270            }
271            if output.rows() != expected_output_rows {
272                return Err(crate::ExecError::Other(format!(
273                    "aggregate output retained {} rows, expected {expected_output_rows}",
274                    output.rows()
275                )));
276            }
277            Ok(output)
278        })();
279        let mut close = Ok(());
280        for mut set in remaining {
281            close = super::state::with_cleanup(close, set.close());
282        }
283        crate::physical::with_cleanup(
284            execution,
285            close.map_err(Into::into),
286            "close aggregate grouping sets",
287        )
288    }
289
290    fn close(&mut self) -> ExecResult<()> {
291        let Some(sets) = self.sets.take() else {
292            return Ok(());
293        };
294        let mut result = Ok(());
295        for mut set in sets {
296            result = super::state::with_cleanup(result, set.close());
297        }
298        result.map_err(Into::into)
299    }
300}
301
302fn grouping_set_statements(
303    context: &dyn QueryExpressionContext,
304    statement: &QueryBlockPlan,
305) -> Result<Vec<(QueryBlockPlan, bool)>, SQLError> {
306    let sets = if statement.grouping_sets.is_empty() {
307        vec![(statement.clone(), false)]
308    } else {
309        statement
310            .grouping_sets
311            .iter()
312            .map(|group_by| {
313                uqa_sql::semantics::aggregates::select_grouping_set(context, statement, group_by)
314                    .map(|active| (active, true))
315            })
316            .collect::<Result<Vec<_>, _>>()?
317    };
318    Ok(sets
319        .into_iter()
320        .map(|(mut statement, relaxed)| {
321            statement.order_by.clear();
322            statement.limit = None;
323            statement.with_ties = false;
324            statement.offset = None;
325            (statement, relaxed)
326        })
327        .collect())
328}
329
330fn copy_output(source: &mut SpillBuffer, destination: &mut SpillBuffer) -> ExecResult<()> {
331    let expected = source.rows();
332    let mut copied = 0usize;
333    for batch in source.drain()? {
334        let batch = batch?;
335        copied = copied
336            .checked_add(batch.rows.len())
337            .ok_or_else(|| crate::ExecError::Other("aggregate copied row count overflow".into()))?;
338        destination.push(batch)?;
339    }
340    if copied != expected {
341        return Err(crate::ExecError::Other(format!(
342            "aggregate spill drain returned {copied} rows, expected {expected}"
343        )));
344    }
345    Ok(())
346}