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