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
23pub struct PhysicalAggregateExecutor<'a> {
24    context: std::sync::Arc<dyn QueryExpressionContext + 'a>,
25    params: &'a [SQLParam],
26
27    input_row_schema: RowSchema,
28    output_schema: RowSchema,
29    output_budget: usize,
30    sets: Vec<AggregateSet>,
31}
32
33impl<'a> PhysicalAggregateExecutor<'a> {
34    pub fn new(
35        context: std::sync::Arc<dyn QueryExpressionContext + 'a>,
36        statement: &QueryBlockPlan,
37        params: &'a [SQLParam],
38
39        input_schema: RowSchema,
40        output_schema: RowSchema,
41        work_mem_bytes: usize,
42    ) -> Result<Self, SQLError> {
43        let runtime = context;
44        let context = runtime.as_ref();
45        let statements = grouping_set_statements(context, statement)?;
46        let set_budget = (work_mem_bytes / statements.len().max(1)).max(1);
47        let sets = statements
48            .into_iter()
49            .map(|(statement, relaxed)| {
50                let mut support = uqa_sql::type_resolution::ComparisonKeySupport::default();
51                for key in &statement.group_by {
52                    if let Some(ty) =
53                        crate::scalar_type_with_resolver(key, &input_schema, params, context)?
54                    {
55                        support.include(&ty, context)?;
56                    }
57                }
58                support.require_implementation("GROUP BY")?;
59                if support.hashing
60                    && super::adaptive::supports_adaptive_grouping(context, &statement)
61                {
62                    return super::adaptive::AdaptiveAggregateSet::new(
63                        context,
64                        statement,
65                        relaxed,
66                        set_budget,
67                        &input_schema,
68                        params,
69                    )
70                    .map(|set| AggregateSet::Adaptive(Box::new(set)));
71                }
72                let phase_budget = (set_budget / 3).max(1);
73                let optimistic = if support.hashing
74                    && super::adaptive::supports_optimistic_grouping(context, &statement)
75                {
76                    Some(Box::new(
77                        super::adaptive::AdaptiveAggregateSet::new_optimistic(
78                            context,
79                            statement.clone(),
80                            relaxed,
81                            (set_budget / 2).max(1),
82                            phase_budget,
83                            &input_schema,
84                            params,
85                        )?,
86                    ))
87                } else {
88                    None
89                };
90                let input_budget = if optimistic.is_some() {
91                    (set_budget / 2).max(1)
92                } else {
93                    phase_budget
94                };
95                Ok(AggregateSet::Sorted {
96                    statement: Box::new(statement),
97                    relaxed,
98                    input: SpillBuffer::new(input_budget),
99                    phase_budget,
100                    optimistic,
101                })
102            })
103            .collect::<Result<Vec<_>, SQLError>>()?;
104        Ok(Self {
105            context: runtime,
106            params,
107
108            input_row_schema: input_schema,
109            output_schema,
110            output_budget: (work_mem_bytes / 3).max(1),
111            sets,
112        })
113    }
114
115    fn finish_set(&self, set: AggregateSet) -> Result<SpillBuffer, SQLError> {
116        match set {
117            AggregateSet::Adaptive(set) => {
118                (*set).finish(self.context.as_ref(), &self.output_schema, self.params)
119            }
120            AggregateSet::Sorted {
121                statement,
122                relaxed,
123                input,
124                phase_budget,
125                optimistic,
126            } => {
127                if let Some(optimistic) = optimistic {
128                    debug_assert!(!optimistic.is_abandoned());
129                    drop(input);
130                    return (*optimistic).finish(
131                        self.context.as_ref(),
132                        &self.output_schema,
133                        self.params,
134                    );
135                }
136                super::sort_fallback::aggregate_sorted_input(
137                    self.context.as_ref(),
138                    &statement,
139                    input,
140                    &self.input_row_schema,
141                    &self.output_schema,
142                    self.params,
143                    phase_budget,
144                    relaxed,
145                )
146            }
147        }
148    }
149}
150
151impl AggregateExecutor for PhysicalAggregateExecutor<'_> {
152    fn consume(&mut self, batch: Batch) -> ExecResult<()> {
153        for set in &mut self.sets {
154            match set {
155                AggregateSet::Adaptive(set) => {
156                    set.consume(self.context.as_ref(), &batch, self.params)?;
157                }
158                AggregateSet::Sorted {
159                    input, optimistic, ..
160                } => {
161                    input.push(batch.clone())?;
162                    if let Some(candidate) = optimistic.as_mut() {
163                        candidate.consume(self.context.as_ref(), &batch, self.params)?;
164                        if candidate.is_abandoned() {
165                            *optimistic = None;
166                        }
167                    }
168                }
169            }
170        }
171        Ok(())
172    }
173
174    fn supports_projected_rows(&self) -> bool {
175        self.sets.iter().all(|set| {
176            matches!(set, AggregateSet::Adaptive(set) if set.statement_subqueries_are_empty())
177        })
178    }
179
180    fn supports_storage_borrowed_rows(&self) -> bool {
181        self.sets.iter().all(|set| {
182            matches!(set, AggregateSet::Adaptive(set) if set.supports_storage_borrowed_rows())
183        })
184    }
185
186    fn consume_projected_row(&mut self, row: &ProjectedRow<'_, '_>) -> ExecResult<()> {
187        for set in &mut self.sets {
188            let AggregateSet::Adaptive(set) = set else {
189                return Err(crate::ExecError::Other(
190                    "sort aggregate cannot consume a projected row".into(),
191                ));
192            };
193            set.consume_projected_row(self.context.as_ref(), row, self.params)?;
194        }
195        Ok(())
196    }
197
198    fn finish(&mut self) -> ExecResult<SpillBuffer> {
199        let mut sets = std::mem::take(&mut self.sets);
200        if sets.len() == 1 {
201            let set = sets.pop().ok_or_else(|| {
202                crate::ExecError::Other("aggregate grouping set disappeared".into())
203            })?;
204            return self.finish_set(set).map_err(Into::into);
205        }
206
207        let mut output = SpillBuffer::new(self.output_budget);
208        let mut expected_output_rows = 0usize;
209        for set in sets {
210            let mut set_output = self.finish_set(set)?;
211            expected_output_rows = expected_output_rows
212                .checked_add(set_output.rows())
213                .ok_or_else(|| {
214                    crate::ExecError::Other("aggregate output row count overflow".into())
215                })?;
216            copy_output(&mut set_output, &mut output)?;
217        }
218        if output.rows() != expected_output_rows {
219            return Err(crate::ExecError::Other(format!(
220                "aggregate output retained {} rows, expected {expected_output_rows}",
221                output.rows()
222            )));
223        }
224        Ok(output)
225    }
226}
227
228fn grouping_set_statements(
229    context: &dyn QueryExpressionContext,
230    statement: &QueryBlockPlan,
231) -> Result<Vec<(QueryBlockPlan, bool)>, SQLError> {
232    let sets = if statement.grouping_sets.is_empty() {
233        vec![(statement.clone(), false)]
234    } else {
235        statement
236            .grouping_sets
237            .iter()
238            .map(|group_by| {
239                uqa_sql::semantics::aggregates::select_grouping_set(context, statement, group_by)
240                    .map(|active| (active, true))
241            })
242            .collect::<Result<Vec<_>, _>>()?
243    };
244    Ok(sets
245        .into_iter()
246        .map(|(mut statement, relaxed)| {
247            statement.order_by.clear();
248            statement.limit = None;
249            statement.with_ties = false;
250            statement.offset = None;
251            (statement, relaxed)
252        })
253        .collect())
254}
255
256fn copy_output(source: &mut SpillBuffer, destination: &mut SpillBuffer) -> ExecResult<()> {
257    let expected = source.rows();
258    let mut copied = 0usize;
259    for batch in source.drain()? {
260        let batch = batch?;
261        copied = copied
262            .checked_add(batch.rows.len())
263            .ok_or_else(|| crate::ExecError::Other("aggregate copied row count overflow".into()))?;
264        destination.push(batch)?;
265    }
266    if copied != expected {
267        return Err(crate::ExecError::Other(format!(
268            "aggregate spill drain returned {copied} rows, expected {expected}"
269        )));
270    }
271    Ok(())
272}