Skip to main content

uqa_execution/schema/columns/
rows.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Replay original and rewritten documents without retaining an unbounded row or identity vector.
8
9use crate::{physical::physical_exec_error, spill::BufferedIndexedSpill, PhysicalRow, RowSchema};
10use uqa_core::{memory::MemoryBudget, DocId, Value};
11use uqa_sql::SQLError;
12use uqa_storage::document_store::Document;
13pub mod changes;
14
15/// A statement-local scope postpones physical checks until the complete replacement rows exist.
16#[derive(Default)]
17pub struct RewriteDeferral {
18    active: std::cell::Cell<bool>,
19    physical:
20        std::cell::RefCell<std::collections::BTreeMap<String, std::collections::BTreeSet<String>>>,
21    not_null: std::cell::RefCell<Option<NotNullChecks>>,
22}
23
24#[derive(Default)]
25struct NotNullChecks {
26    relations: Vec<(String, std::collections::BTreeSet<String>)>,
27    positions: std::collections::BTreeMap<String, usize>,
28}
29
30impl RewriteDeferral {
31    pub fn is_deferred(&self) -> bool {
32        self.active.get()
33    }
34
35    pub fn defer(&self) -> RewriteDeferralGuard<'_> {
36        RewriteDeferralGuard {
37            state: self,
38            previous: self.active.replace(true),
39            physical: self.physical.take(),
40        }
41    }
42
43    pub(in crate::schema) fn defer_not_null(&self) -> NotNullDeferralGuard<'_> {
44        NotNullDeferralGuard {
45            state: self,
46            previous: self.not_null.replace(Some(NotNullChecks::default())),
47        }
48    }
49
50    pub(in crate::schema) fn retain_not_null_check(&self, table: &str, column: &str) -> bool {
51        let mut retained = self.not_null.borrow_mut();
52        let Some(checks) = retained.as_mut() else {
53            return false;
54        };
55        let position = *checks
56            .positions
57            .entry(table.to_string())
58            .or_insert_with(|| {
59                let position = checks.relations.len();
60                checks
61                    .relations
62                    .push((table.to_string(), std::collections::BTreeSet::new()));
63                position
64            });
65        checks.relations[position].1.insert(column.to_string());
66        true
67    }
68
69    pub(in crate::schema) fn require_physical_rewrite(&self, table: &str, column: &str) {
70        self.physical
71            .borrow_mut()
72            .entry(table.to_string())
73            .or_default()
74            .insert(column.to_string());
75    }
76
77    pub(in crate::schema) fn needs_physical_rewrite(&self, table: &str) -> bool {
78        self.physical.borrow().contains_key(table)
79    }
80
81    pub(in crate::schema) fn physical_columns(&self, table: &str) -> Vec<String> {
82        self.physical
83            .borrow()
84            .get(table)
85            .into_iter()
86            .flatten()
87            .cloned()
88            .collect()
89    }
90}
91
92pub(in crate::schema) struct NotNullDeferralGuard<'a> {
93    state: &'a RewriteDeferral,
94    previous: Option<NotNullChecks>,
95}
96
97impl NotNullDeferralGuard<'_> {
98    pub(in crate::schema) fn take_checks(
99        &self,
100    ) -> Vec<(String, std::collections::BTreeSet<String>)> {
101        self.state
102            .not_null
103            .take()
104            .map_or_else(Vec::new, |checks| checks.relations)
105    }
106}
107
108impl Drop for NotNullDeferralGuard<'_> {
109    fn drop(&mut self) {
110        self.state.not_null.replace(self.previous.take());
111    }
112}
113
114pub struct RewriteDeferralGuard<'a> {
115    state: &'a RewriteDeferral,
116    previous: bool,
117    physical: std::collections::BTreeMap<String, std::collections::BTreeSet<String>>,
118}
119
120impl Drop for RewriteDeferralGuard<'_> {
121    fn drop(&mut self) {
122        self.state.active.set(self.previous);
123        self.state
124            .physical
125            .replace(std::mem::take(&mut self.physical));
126    }
127}
128
129pub struct RewriteRow {
130    pub original_id: DocId,
131    pub target_id: DocId,
132    pub document: Document,
133}
134
135/// Original inputs, converted outputs and identity-remapped outputs share the same resident allowance. Encrypted spill retains exact value carriers and full-width document identities; replay holds one decoded row at a time.
136pub struct RewriteRows {
137    rows: BufferedIndexedSpill,
138}
139
140impl RewriteRows {
141    pub fn new(memory: &MemoryBudget) -> Self {
142        let relation = uqa_sql::ast::InternalRelationId::allocate();
143        Self {
144            rows: BufferedIndexedSpill::with_memory(
145                RowSchema::with_internal_relation_types(relation, vec![None; 3]),
146                memory,
147            ),
148        }
149    }
150
151    pub fn memory(&self) -> &MemoryBudget {
152        self.rows.memory()
153    }
154
155    pub fn len(&self) -> u64 {
156        self.rows.len()
157    }
158
159    pub fn is_empty(&self) -> bool {
160        self.rows.is_empty()
161    }
162
163    pub fn push(&mut self, original_id: DocId, document: Document) -> Result<(), SQLError> {
164        self.push_replacement(original_id, original_id, document)
165    }
166
167    pub fn push_replacement(
168        &mut self,
169        original_id: DocId,
170        target_id: DocId,
171        document: Document,
172    ) -> Result<(), SQLError> {
173        self.rows
174            .push(&PhysicalRow::from_values(vec![
175                Value::Bytes(original_id.to_le_bytes().to_vec()),
176                Value::Bytes(target_id.to_le_bytes().to_vec()),
177                Value::Map(document),
178            ]))
179            .map_err(physical_exec_error)
180    }
181
182    pub fn get(&mut self, position: u64) -> Result<RewriteRow, SQLError> {
183        let mut values = self
184            .rows
185            .get(position)
186            .map_err(physical_exec_error)?
187            .into_physical_values()
188            .into_iter();
189        let original_id = decode_identity(values.next())?;
190        let target_id = decode_identity(values.next())?;
191        let Some(Value::Map(document)) = values.next() else {
192            return Err(SQLError::Internal("rewritten row lost its document".into()));
193        };
194        Ok(RewriteRow {
195            original_id,
196            target_id,
197            document,
198        })
199    }
200
201    pub fn spill(&mut self) -> Result<(), SQLError> {
202        self.rows.spill().map_err(physical_exec_error)
203    }
204}
205
206/// Seal the input before evaluating callbacks or publishing any changed declaration.
207pub fn capture(
208    reads: &dyn crate::mutation::constraints::context::MutationRead,
209    table: &str,
210    memory: &MemoryBudget,
211    control: &uqa_storage::read_control::StorageReadControl,
212) -> Result<RewriteRows, SQLError> {
213    let mut result = RewriteRows::new(memory);
214    visit_document_ids(reads, table, control, &mut |id| {
215        if let Some(document) = reads.get_document(table, id)? {
216            result.push(id, document)?;
217        }
218        Ok(())
219    })?;
220    Ok(result)
221}
222
223/// Visit current document identities one budgeted page at a time; consumers may rewrite rows without retaining all identities.
224pub fn visit_document_ids(
225    reads: &dyn crate::mutation::constraints::context::MutationRead,
226    table: &str,
227    control: &uqa_storage::read_control::StorageReadControl,
228    visit: &mut dyn FnMut(DocId) -> Result<(), SQLError>,
229) -> Result<(), SQLError> {
230    let mut after = None;
231    let limit = (control.memory().limit() / (4 * std::mem::size_of::<DocId>()))
232        .clamp(1, crate::DEFAULT_BATCH_SIZE);
233    loop {
234        control.cancellation().check()?;
235        let ids = reads.live_table_doc_id_page(table, after, limit, control)?;
236        let Some(last) = ids.last().copied() else {
237            break;
238        };
239        after = Some(last);
240        for id in ids.iter().copied() {
241            control.cancellation().check()?;
242            visit(id)?;
243        }
244    }
245    Ok(())
246}
247
248fn decode_identity(value: Option<Value>) -> Result<DocId, SQLError> {
249    let Some(Value::Bytes(bytes)) = value else {
250        return Err(SQLError::Internal("rewritten row lost its identity".into()));
251    };
252    let bytes = bytes
253        .try_into()
254        .map_err(|_| SQLError::Internal("rewritten row has an invalid identity".into()))?;
255    Ok(DocId::from_le_bytes(bytes))
256}
257
258#[cfg(test)]
259mod tests;