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::query::consumer::QueryConsumerControl;
10use crate::{
11    physical::physical_exec_error,
12    query::{projection::physical_work_mem_bytes, runtime::QueryRuntimeView},
13    spill::{SpillDrain, SpillRows},
14    Batch, IndexedSpill, OwnedPhysicalRow, PhysicalRow, RowSchema, SpillBuffer,
15};
16use uqa_core::CancellationToken;
17use uqa_sql::SQLError;
18
19pub struct ReturningRows {
20    buffer: SpillBuffer,
21    schema: Option<RowSchema>,
22    pending: Vec<PhysicalRow>,
23    pending_bytes: usize,
24    delivery: QueryConsumerControl,
25    batch_bytes: usize,
26    cancellation: CancellationToken,
27}
28
29impl Default for ReturningRows {
30    fn default() -> Self {
31        Self::with_budget(0, CancellationToken::new())
32    }
33}
34
35impl ReturningRows {
36    pub fn new(runtime: QueryRuntimeView<'_>) -> Result<Self, SQLError> {
37        Ok(Self::with_budget(
38            physical_work_mem_bytes(runtime)?,
39            runtime.cancellation_token(),
40        ))
41    }
42
43    pub(crate) fn with_budget(bytes: usize, cancellation: CancellationToken) -> Self {
44        Self {
45            buffer: SpillBuffer::new(bytes / 2),
46            schema: None,
47            pending: Vec::new(),
48            pending_bytes: 0,
49            delivery: QueryConsumerControl::Continue,
50            batch_bytes: bytes / 2,
51            cancellation,
52        }
53    }
54
55    pub fn len(&self) -> usize {
56        self.buffer.rows() + self.pending.len()
57    }
58
59    pub fn is_empty(&self) -> bool {
60        self.len() == 0
61    }
62
63    pub(crate) fn schema(&self) -> Option<&RowSchema> {
64        self.schema.as_ref()
65    }
66
67    pub fn push_to(
68        &mut self,
69        row: OwnedPhysicalRow,
70        destination: Option<super::ReturningDestination<'_>>,
71    ) -> Result<(), SQLError> {
72        let Some(destination) = destination else {
73            return self.push(row);
74        };
75        self.cancellation.check()?;
76        if self.delivery == QueryConsumerControl::Continue {
77            self.delivery = match destination.consume(row)? {
78                QueryConsumerControl::Rewind => {
79                    return Err(SQLError::Internal(
80                        "a RETURNING receiver cannot rewind a mutation".into(),
81                    ))
82                }
83                control => control,
84            };
85        }
86        Ok(())
87    }
88
89    pub fn push(&mut self, row: OwnedPhysicalRow) -> Result<(), SQLError> {
90        self.cancellation.check()?;
91        self.len()
92            .checked_add(1)
93            .ok_or_else(|| SQLError::Internal("RETURNING row count overflow".into()))?;
94        let schema = self
95            .schema
96            .get_or_insert_with(|| RowSchema::new(row.schema.columns().to_vec()));
97        if schema.columns() != row.schema.columns() {
98            return Err(SQLError::Internal(
99                "RETURNING output columns changed".into(),
100            ));
101        }
102        // 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.
103        let projected = row.row.project_slots(row.schema.layout_slots());
104        drop(row);
105        let row = PhysicalRow::from_values(projected.into_physical_values());
106        let bytes = IndexedSpill::encoded_row_size(schema, &row).map_err(physical_exec_error)?;
107        if self
108            .pending_bytes
109            .checked_add(bytes)
110            .is_none_or(|bytes| bytes > self.batch_bytes)
111        {
112            self.flush()?;
113        }
114        self.pending_bytes = bytes
115            .checked_add(self.pending_bytes)
116            .ok_or_else(|| SQLError::Internal("RETURNING batch byte count overflow".into()))?;
117        self.pending.push(row);
118        if self.pending_bytes >= self.batch_bytes
119            || self.pending.len() == crate::batch::DEFAULT_BATCH_SIZE
120        {
121            self.flush()?;
122        }
123        Ok(())
124    }
125
126    fn flush(&mut self) -> Result<(), SQLError> {
127        if self.pending.is_empty() {
128            return Ok(());
129        }
130        self.cancellation.check()?;
131        let schema = self
132            .schema
133            .as_ref()
134            .expect("pending RETURNING rows have a schema");
135        let batch = Batch::from_physical_rows(schema.clone(), std::mem::take(&mut self.pending));
136        self.pending_bytes = 0;
137        self.buffer.push(batch).map_err(physical_exec_error)?;
138        Ok(())
139    }
140
141    pub(crate) fn into_batches(mut self) -> Result<ReturningBatchReader, SQLError> {
142        self.flush()?;
143        Ok(ReturningBatchReader {
144            rows: self.buffer.drain().map_err(physical_exec_error)?,
145            cancellation: self.cancellation,
146            failed: false,
147        })
148    }
149
150    pub fn into_rows(self) -> Result<ReturningRowReader, SQLError> {
151        let cancellation = self.cancellation.clone();
152        Ok(ReturningRowReader {
153            rows: SpillRows::new(self.into_batches()?),
154            cancellation,
155            failed: false,
156        })
157    }
158}
159
160pub struct ReturningRowReader {
161    rows: SpillRows<ReturningBatchReader>,
162    cancellation: CancellationToken,
163    failed: bool,
164}
165
166pub(crate) struct ReturningBatchReader {
167    rows: SpillDrain,
168    cancellation: CancellationToken,
169    failed: bool,
170}
171
172impl Iterator for ReturningBatchReader {
173    type Item = crate::physical::ExecResult<Batch>;
174
175    fn next(&mut self) -> Option<Self::Item> {
176        if self.failed {
177            return None;
178        }
179        let result = self
180            .cancellation
181            .check()
182            .map_err(SQLError::from)
183            .map_err(crate::physical::ExecError::from)
184            .and_then(|()| self.rows.next().transpose());
185        self.failed = result.is_err();
186        result.transpose()
187    }
188}
189
190impl Iterator for ReturningRowReader {
191    type Item = Result<OwnedPhysicalRow, SQLError>;
192
193    fn next(&mut self) -> Option<Self::Item> {
194        if self.failed {
195            return None;
196        }
197        let result = self
198            .cancellation
199            .check()
200            .map_err(SQLError::from)
201            .and_then(|()| self.rows.next().transpose().map_err(physical_exec_error));
202        self.failed = result.is_err();
203        result.transpose()
204    }
205}
206
207#[cfg(test)]
208mod tests;