Skip to main content

uqa_execution/aggregation/
registered_buffer.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Spillable ordered input buffering for registered aggregates.
8
9use super::ordering::{
10    compare_sort_keys, compare_sort_keys_with_catalog, minimum_by, sort_records,
11};
12use uqa_sql::expr::enums::{EnumComparisonState, EnumLabelCatalog};
13
14use super::{
15    read_bounded_json_spill_record, write_json_spill_record, BufReader, BufWriter, File,
16    JsonSpillRun, Ordering, SQLAggregateState, SQLError, Seek, SeekFrom, Value, Write,
17    AGGREGATE_MERGE_FAN_IN,
18};
19
20#[derive(Clone, serde::Deserialize, serde::Serialize)]
21pub struct RegisteredAggregateRecord {
22    pub(super) values: Vec<Value>,
23    pub(super) sort_keys: Vec<super::ordering::AggregateSortKey>,
24    pub(super) sequence: u64,
25}
26
27pub struct RegisteredAggregateBuffer {
28    pub(super) rows: Vec<RegisteredAggregateRecord>,
29    pub(super) runs: Vec<JsonSpillRun>,
30    pub(super) next_sequence: u64,
31    pub(super) budget_bytes: usize,
32    pub(super) memory_bytes: usize,
33    pub(super) comparison_states: Option<std::sync::Arc<[EnumComparisonState]>>,
34    pub(super) key_types: Option<std::sync::Arc<[Option<uqa_sql::ColumnType>]>>,
35}
36
37impl Default for RegisteredAggregateBuffer {
38    fn default() -> Self {
39        Self::new(64 * 1024 * 1024)
40    }
41}
42
43impl RegisteredAggregateBuffer {
44    pub(super) fn new(budget_bytes: usize) -> Self {
45        Self {
46            rows: Vec::new(),
47            runs: Vec::new(),
48            next_sequence: 0,
49            budget_bytes: budget_bytes.max(1),
50            memory_bytes: 0,
51            comparison_states: None,
52            key_types: None,
53        }
54    }
55
56    pub(super) fn is_empty(&self) -> bool {
57        self.rows.is_empty() && self.runs.is_empty()
58    }
59
60    pub(super) fn push(
61        &mut self,
62        values: Vec<Value>,
63        sort_keys: Vec<super::ordering::AggregateSortKey>,
64        enums: Option<&dyn EnumLabelCatalog>,
65    ) -> Result<(), SQLError> {
66        if !sort_keys.is_empty()
67            && self.comparison_states.is_none()
68            && enums.is_some_and(EnumLabelCatalog::has_enum_types)
69        {
70            self.comparison_states = Some(
71                (0..sort_keys.len())
72                    .map(|_| EnumComparisonState::default())
73                    .collect(),
74            );
75        }
76        let next_sequence = self.next_sequence.checked_add(1).ok_or_else(|| {
77            SQLError::Internal("registered aggregate value sequence overflow".into())
78        })?;
79        let record = RegisteredAggregateRecord {
80            values,
81            sort_keys,
82            sequence: self.next_sequence,
83        };
84        let bytes = serde_json::to_vec(&record)
85            .map_err(|error| {
86                SQLError::Internal(format!(
87                    "failed to size registered aggregate value: {error}"
88                ))
89            })?
90            .len()
91            .checked_add(1)
92            .ok_or_else(|| SQLError::Internal("registered aggregate value size overflow".into()))?;
93        if !self.rows.is_empty()
94            && self
95                .memory_bytes
96                .checked_add(bytes)
97                .is_none_or(|total| total > self.budget_bytes)
98        {
99            self.flush_run(enums)?;
100        }
101        let next_memory_bytes = self
102            .memory_bytes
103            .checked_add(bytes)
104            .ok_or_else(|| SQLError::Internal("registered aggregate value size overflow".into()))?;
105        self.rows.push(record);
106        self.memory_bytes = next_memory_bytes;
107        self.next_sequence = next_sequence;
108        if self.memory_bytes > self.budget_bytes {
109            self.flush_run(enums)?;
110        }
111        Ok(())
112    }
113
114    pub(super) fn observe_ordered_into(
115        &self,
116        state: &mut dyn SQLAggregateState,
117        enums: Option<&dyn EnumLabelCatalog>,
118    ) -> Result<(), SQLError> {
119        if self.runs.is_empty() {
120            let mut rows = self.rows.clone();
121            sort_records(&mut rows, |left, right| {
122                compare_registered_aggregate_records_with_catalog(
123                    left,
124                    right,
125                    enums,
126                    self.comparison_states.as_deref().unwrap_or_default(),
127                    self.key_types.as_deref().unwrap_or_default(),
128                )
129            })?;
130            for row in rows {
131                state.observe(&row.values)?;
132            }
133            return Ok(());
134        }
135
136        let mut rows = self.rows.clone();
137        sort_records(&mut rows, |left, right| {
138            compare_registered_aggregate_records_with_catalog(
139                left,
140                right,
141                enums,
142                self.comparison_states.as_deref().unwrap_or_default(),
143                self.key_types.as_deref().unwrap_or_default(),
144            )
145        })?;
146        let mut readers = Vec::with_capacity(self.runs.len() + usize::from(!rows.is_empty()));
147        if !rows.is_empty() {
148            readers.push(RegisteredAggregateRunReader::memory(rows));
149        }
150        for run in &self.runs {
151            readers.push(RegisteredAggregateRunReader::file(run)?);
152        }
153
154        while let Some((idx, _)) = minimum_by(
155            readers
156                .iter()
157                .enumerate()
158                .filter_map(|(idx, reader)| reader.current().map(|record| (idx, record))),
159            |(_, a), (_, b)| {
160                compare_registered_aggregate_records_with_catalog(
161                    a,
162                    b,
163                    enums,
164                    self.comparison_states.as_deref().unwrap_or_default(),
165                    self.key_types.as_deref().unwrap_or_default(),
166                )
167            },
168        )? {
169            let record = readers[idx].take_current()?;
170            state.observe(&record.values)?;
171        }
172        Ok(())
173    }
174
175    pub(super) fn flush_run(
176        &mut self,
177        enums: Option<&dyn EnumLabelCatalog>,
178    ) -> Result<(), SQLError> {
179        if self.rows.is_empty() {
180            return Ok(());
181        }
182        sort_records(&mut self.rows, |left, right| {
183            compare_registered_aggregate_records_with_catalog(
184                left,
185                right,
186                enums,
187                self.comparison_states.as_deref().unwrap_or_default(),
188                self.key_types.as_deref().unwrap_or_default(),
189            )
190        })?;
191        let mut run = uqa_storage::temporary_file::TemporaryFile::new().map_err(|err| {
192            SQLError::Internal(format!(
193                "failed to create registered aggregate spill file: {err}"
194            ))
195        })?;
196        let mut max_record_bytes = 0;
197        {
198            let mut writer = BufWriter::new(run.as_file_mut());
199            for row in self.rows.drain(..) {
200                let record_bytes =
201                    write_json_spill_record(&mut writer, &row, "registered aggregate spill row")?;
202                max_record_bytes = max_record_bytes.max(record_bytes);
203            }
204            writer.flush().map_err(|err| {
205                SQLError::Internal(format!(
206                    "failed to flush registered aggregate spill file: {err}"
207                ))
208            })?;
209        }
210        run.as_file_mut().seek(SeekFrom::Start(0)).map_err(|err| {
211            SQLError::Internal(format!(
212                "failed to rewind registered aggregate spill file: {err}"
213            ))
214        })?;
215        self.runs.push(JsonSpillRun {
216            file: run,
217            max_record_bytes,
218        });
219        self.memory_bytes = 0;
220        if self.runs.len() >= AGGREGATE_MERGE_FAN_IN {
221            let inputs = self
222                .runs
223                .drain(..AGGREGATE_MERGE_FAN_IN)
224                .collect::<Vec<_>>();
225            self.runs.push(merge_registered_aggregate_runs_with_catalog(
226                inputs,
227                enums,
228                self.comparison_states.as_deref().unwrap_or_default(),
229                self.key_types.as_deref().unwrap_or_default(),
230            )?);
231        }
232        Ok(())
233    }
234}
235
236pub enum RegisteredAggregateRunReader {
237    Memory {
238        rows: std::vec::IntoIter<RegisteredAggregateRecord>,
239        current: Option<RegisteredAggregateRecord>,
240    },
241    File {
242        reader: BufReader<File>,
243        current: Option<RegisteredAggregateRecord>,
244        max_record_bytes: usize,
245    },
246}
247
248impl RegisteredAggregateRunReader {
249    pub(super) fn memory(rows: Vec<RegisteredAggregateRecord>) -> Self {
250        let mut rows = rows.into_iter();
251        let current = rows.next();
252        Self::Memory { rows, current }
253    }
254
255    pub(super) fn file(run: &JsonSpillRun) -> Result<Self, SQLError> {
256        let file = run.file.reopen().map_err(|err| {
257            SQLError::Internal(format!(
258                "failed to reopen registered aggregate spill file: {err}"
259            ))
260        })?;
261        let mut reader = BufReader::new(file);
262        let current = read_registered_aggregate_record(&mut reader, run.max_record_bytes)?;
263        Ok(Self::File {
264            reader,
265            current,
266            max_record_bytes: run.max_record_bytes,
267        })
268    }
269
270    pub(super) fn current(&self) -> Option<&RegisteredAggregateRecord> {
271        match self {
272            Self::Memory { current, .. } | Self::File { current, .. } => current.as_ref(),
273        }
274    }
275
276    pub(super) fn take_current(&mut self) -> Result<RegisteredAggregateRecord, SQLError> {
277        match self {
278            Self::Memory { rows, current } => {
279                let record = current.take().ok_or_else(|| {
280                    SQLError::Internal("registered aggregate memory run exhausted".into())
281                })?;
282                *current = rows.next();
283                Ok(record)
284            }
285            Self::File {
286                reader,
287                current,
288                max_record_bytes,
289            } => {
290                let record = current.take().ok_or_else(|| {
291                    SQLError::Internal("registered aggregate spill run exhausted".into())
292                })?;
293                *current = read_registered_aggregate_record(reader, *max_record_bytes)?;
294                Ok(record)
295            }
296        }
297    }
298}
299
300pub fn read_registered_aggregate_record(
301    reader: &mut impl std::io::BufRead,
302    max_record_bytes: usize,
303) -> Result<Option<RegisteredAggregateRecord>, SQLError> {
304    let Some(record) =
305        read_bounded_json_spill_record(reader, max_record_bytes, "registered aggregate spill row")?
306    else {
307        return Ok(None);
308    };
309    serde_json::from_slice(&record).map(Some).map_err(|err| {
310        SQLError::Internal(format!(
311            "failed to deserialize registered aggregate spill row: {err}"
312        ))
313    })
314}
315
316pub fn merge_registered_aggregate_runs(runs: Vec<JsonSpillRun>) -> Result<JsonSpillRun, SQLError> {
317    merge_registered_aggregate_runs_with_catalog(runs, None, &[], &[])
318}
319
320fn merge_registered_aggregate_runs_with_catalog(
321    runs: Vec<JsonSpillRun>,
322    enums: Option<&dyn EnumLabelCatalog>,
323    states: &[EnumComparisonState],
324    types: &[Option<uqa_sql::ColumnType>],
325) -> Result<JsonSpillRun, SQLError> {
326    let mut readers = runs
327        .iter()
328        .map(RegisteredAggregateRunReader::file)
329        .collect::<Result<Vec<_>, _>>()?;
330    let mut output = uqa_storage::temporary_file::TemporaryFile::new().map_err(|error| {
331        SQLError::Internal(format!(
332            "failed to create registered aggregate merge run: {error}"
333        ))
334    })?;
335    let mut max_record_bytes = 0;
336    {
337        let mut writer = BufWriter::new(output.as_file_mut());
338        while let Some((index, _)) = minimum_by(
339            readers
340                .iter()
341                .enumerate()
342                .filter_map(|(index, reader)| reader.current().map(|record| (index, record))),
343            |(_, left), (_, right)| {
344                compare_registered_aggregate_records_with_catalog(left, right, enums, states, types)
345            },
346        )? {
347            let record = readers[index].take_current()?;
348            let record_bytes =
349                write_json_spill_record(&mut writer, &record, "registered aggregate merge row")?;
350            max_record_bytes = max_record_bytes.max(record_bytes);
351        }
352        writer.flush().map_err(|error| {
353            SQLError::Internal(format!(
354                "failed to flush registered aggregate merge run: {error}"
355            ))
356        })?;
357    }
358    output
359        .as_file_mut()
360        .seek(SeekFrom::Start(0))
361        .map_err(|error| {
362            SQLError::Internal(format!(
363                "failed to rewind registered aggregate merge run: {error}"
364            ))
365        })?;
366    Ok(JsonSpillRun {
367        file: output,
368        max_record_bytes,
369    })
370}
371
372pub fn compare_registered_aggregate_records(
373    a: &RegisteredAggregateRecord,
374    b: &RegisteredAggregateRecord,
375) -> Result<Ordering, SQLError> {
376    let ordering = compare_sort_keys(&a.sort_keys, &b.sort_keys)?;
377    Ok(ordering.then_with(|| a.sequence.cmp(&b.sequence)))
378}
379
380fn compare_registered_aggregate_records_with_catalog(
381    a: &RegisteredAggregateRecord,
382    b: &RegisteredAggregateRecord,
383    enums: Option<&dyn EnumLabelCatalog>,
384    states: &[EnumComparisonState],
385    types: &[Option<uqa_sql::ColumnType>],
386) -> Result<Ordering, SQLError> {
387    let ordering =
388        compare_sort_keys_with_catalog(&a.sort_keys, &b.sort_keys, enums, states, types)?;
389    Ok(ordering.then_with(|| a.sequence.cmp(&b.sequence)))
390}