Skip to main content

uqa_execution/mutation/returning/
rows.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Ordered RETURNING values detach from source fragments and spill in bounded batches.
8
9use crate::{
10    physical::physical_exec_error,
11    query::{projection::physical_work_mem_bytes, runtime::QueryRuntimeView},
12    spill::{SpillDrain, SpillRows},
13    Batch, IndexedSpill, OwnedPhysicalRow, PhysicalRow, RowSchema, SpillBuffer,
14};
15use uqa_core::CancellationToken;
16use uqa_sql::SQLError;
17
18pub struct ReturningRows {
19    buffer: SpillBuffer,
20    schema: Option<RowSchema>,
21    pending: Vec<PhysicalRow>,
22    pending_bytes: usize,
23    batch_bytes: usize,
24    cancellation: CancellationToken,
25}
26
27impl Default for ReturningRows {
28    fn default() -> Self {
29        Self::with_budget(0, CancellationToken::new())
30    }
31}
32
33impl ReturningRows {
34    pub fn new(runtime: QueryRuntimeView<'_>) -> Result<Self, SQLError> {
35        Ok(Self::with_budget(
36            physical_work_mem_bytes(runtime)?,
37            runtime.cancellation_token(),
38        ))
39    }
40
41    pub(crate) fn with_budget(bytes: usize, cancellation: CancellationToken) -> Self {
42        Self {
43            buffer: SpillBuffer::new(bytes / 2),
44            schema: None,
45            pending: Vec::new(),
46            pending_bytes: 0,
47            batch_bytes: bytes / 2,
48            cancellation,
49        }
50    }
51
52    pub fn len(&self) -> usize {
53        self.buffer.rows() + self.pending.len()
54    }
55
56    pub fn is_empty(&self) -> bool {
57        self.len() == 0
58    }
59
60    pub(crate) fn schema(&self) -> Option<&RowSchema> {
61        self.schema.as_ref()
62    }
63
64    pub fn push(&mut self, row: OwnedPhysicalRow) -> Result<(), SQLError> {
65        self.cancellation.check()?;
66        self.len()
67            .checked_add(1)
68            .ok_or_else(|| SQLError::Internal("RETURNING row count overflow".into()))?;
69        let schema = self
70            .schema
71            .get_or_insert_with(|| RowSchema::new(row.schema.columns().to_vec()));
72        if schema.columns() != row.schema.columns() {
73            return Err(SQLError::Internal(
74                "RETURNING output columns changed".into(),
75            ));
76        }
77        // A projected row may share an entire OLD/NEW document. Keep only its output slots; the final result binder still owns declared types and collations.
78        let projected = row.row.project_slots(row.schema.layout_slots());
79        drop(row);
80        let row = PhysicalRow::from_values(projected.into_physical_values());
81        let bytes = IndexedSpill::encoded_row_size(schema, &row).map_err(physical_exec_error)?;
82        if self
83            .pending_bytes
84            .checked_add(bytes)
85            .is_none_or(|bytes| bytes > self.batch_bytes)
86        {
87            self.flush()?;
88        }
89        self.pending_bytes = bytes
90            .checked_add(self.pending_bytes)
91            .ok_or_else(|| SQLError::Internal("RETURNING batch byte count overflow".into()))?;
92        self.pending.push(row);
93        if self.pending_bytes >= self.batch_bytes
94            || self.pending.len() == crate::batch::DEFAULT_BATCH_SIZE
95        {
96            self.flush()?;
97        }
98        Ok(())
99    }
100
101    fn flush(&mut self) -> Result<(), SQLError> {
102        if self.pending.is_empty() {
103            return Ok(());
104        }
105        self.cancellation.check()?;
106        let schema = self
107            .schema
108            .as_ref()
109            .expect("pending RETURNING rows have a schema");
110        let batch = Batch::from_physical_rows(schema.clone(), std::mem::take(&mut self.pending));
111        self.pending_bytes = 0;
112        self.buffer.push(batch).map_err(physical_exec_error)?;
113        Ok(())
114    }
115
116    pub(crate) fn into_batches(mut self) -> Result<ReturningBatchReader, SQLError> {
117        self.flush()?;
118        Ok(ReturningBatchReader {
119            rows: self.buffer.drain().map_err(physical_exec_error)?,
120            cancellation: self.cancellation,
121            failed: false,
122        })
123    }
124
125    pub fn into_rows(self) -> Result<ReturningRowReader, SQLError> {
126        let cancellation = self.cancellation.clone();
127        Ok(ReturningRowReader {
128            rows: SpillRows::new(self.into_batches()?),
129            cancellation,
130            failed: false,
131        })
132    }
133}
134
135pub struct ReturningRowReader {
136    rows: SpillRows<ReturningBatchReader>,
137    cancellation: CancellationToken,
138    failed: bool,
139}
140
141pub(crate) struct ReturningBatchReader {
142    rows: SpillDrain,
143    cancellation: CancellationToken,
144    failed: bool,
145}
146
147impl Iterator for ReturningBatchReader {
148    type Item = crate::physical::ExecResult<Batch>;
149
150    fn next(&mut self) -> Option<Self::Item> {
151        if self.failed {
152            return None;
153        }
154        let result = self
155            .cancellation
156            .check()
157            .map_err(SQLError::from)
158            .map_err(crate::physical::ExecError::from)
159            .and_then(|()| self.rows.next().transpose());
160        self.failed = result.is_err();
161        result.transpose()
162    }
163}
164
165impl Iterator for ReturningRowReader {
166    type Item = Result<OwnedPhysicalRow, SQLError>;
167
168    fn next(&mut self) -> Option<Self::Item> {
169        if self.failed {
170            return None;
171        }
172        let result = self
173            .cancellation
174            .check()
175            .map_err(SQLError::from)
176            .and_then(|()| self.rows.next().transpose().map_err(physical_exec_error));
177        self.failed = result.is_err();
178        result.transpose()
179    }
180}
181
182#[cfg(test)]
183mod tests;