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}
22
23impl RewriteDeferral {
24    pub fn is_deferred(&self) -> bool {
25        self.active.get()
26    }
27
28    pub fn defer(&self) -> RewriteDeferralGuard<'_> {
29        RewriteDeferralGuard {
30            state: self,
31            previous: self.active.replace(true),
32            physical: self.physical.take(),
33        }
34    }
35
36    pub(in crate::schema) fn require_physical_rewrite(&self, table: &str, column: &str) {
37        self.physical
38            .borrow_mut()
39            .entry(table.to_string())
40            .or_default()
41            .insert(column.to_string());
42    }
43
44    pub(in crate::schema) fn needs_physical_rewrite(&self, table: &str) -> bool {
45        self.physical.borrow().contains_key(table)
46    }
47
48    pub(in crate::schema) fn physical_columns(&self, table: &str) -> Vec<String> {
49        self.physical
50            .borrow()
51            .get(table)
52            .into_iter()
53            .flatten()
54            .cloned()
55            .collect()
56    }
57}
58
59pub struct RewriteDeferralGuard<'a> {
60    state: &'a RewriteDeferral,
61    previous: bool,
62    physical: std::collections::BTreeMap<String, std::collections::BTreeSet<String>>,
63}
64
65impl Drop for RewriteDeferralGuard<'_> {
66    fn drop(&mut self) {
67        self.state.active.set(self.previous);
68        self.state
69            .physical
70            .replace(std::mem::take(&mut self.physical));
71    }
72}
73
74pub struct RewriteRow {
75    pub original_id: DocId,
76    pub target_id: DocId,
77    pub document: Document,
78}
79
80/// 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.
81pub struct RewriteRows {
82    rows: BufferedIndexedSpill,
83}
84
85impl RewriteRows {
86    pub fn new(memory: &MemoryBudget) -> Self {
87        let relation = uqa_sql::ast::InternalRelationId::allocate();
88        Self {
89            rows: BufferedIndexedSpill::with_memory(
90                RowSchema::with_internal_relation_types(relation, vec![None; 3]),
91                memory,
92            ),
93        }
94    }
95
96    pub fn memory(&self) -> &MemoryBudget {
97        self.rows.memory()
98    }
99
100    pub fn len(&self) -> u64 {
101        self.rows.len()
102    }
103
104    pub fn is_empty(&self) -> bool {
105        self.rows.is_empty()
106    }
107
108    pub fn push(&mut self, original_id: DocId, document: Document) -> Result<(), SQLError> {
109        self.push_replacement(original_id, original_id, document)
110    }
111
112    pub fn push_replacement(
113        &mut self,
114        original_id: DocId,
115        target_id: DocId,
116        document: Document,
117    ) -> Result<(), SQLError> {
118        self.rows
119            .push(&PhysicalRow::from_values(vec![
120                Value::Bytes(original_id.to_le_bytes().to_vec()),
121                Value::Bytes(target_id.to_le_bytes().to_vec()),
122                Value::Map(document),
123            ]))
124            .map_err(physical_exec_error)
125    }
126
127    pub fn get(&mut self, position: u64) -> Result<RewriteRow, SQLError> {
128        let mut values = self
129            .rows
130            .get(position)
131            .map_err(physical_exec_error)?
132            .into_physical_values()
133            .into_iter();
134        let original_id = decode_identity(values.next())?;
135        let target_id = decode_identity(values.next())?;
136        let Some(Value::Map(document)) = values.next() else {
137            return Err(SQLError::Internal("rewritten row lost its document".into()));
138        };
139        Ok(RewriteRow {
140            original_id,
141            target_id,
142            document,
143        })
144    }
145
146    pub fn spill(&mut self) -> Result<(), SQLError> {
147        self.rows.spill().map_err(physical_exec_error)
148    }
149}
150
151/// Seal the input before evaluating callbacks or publishing any changed declaration.
152pub fn capture(
153    reads: &dyn crate::mutation::constraints::context::MutationRead,
154    table: &str,
155    memory: &MemoryBudget,
156    control: &uqa_storage::read_control::StorageReadControl,
157) -> Result<RewriteRows, SQLError> {
158    let mut result = RewriteRows::new(memory);
159    visit_document_ids(reads, table, control, &mut |id| {
160        if let Some(document) = reads.get_document(table, id)? {
161            result.push(id, document)?;
162        }
163        Ok(())
164    })?;
165    Ok(result)
166}
167
168/// Visit current document identities one budgeted page at a time; consumers may rewrite rows without retaining all identities.
169pub fn visit_document_ids(
170    reads: &dyn crate::mutation::constraints::context::MutationRead,
171    table: &str,
172    control: &uqa_storage::read_control::StorageReadControl,
173    visit: &mut dyn FnMut(DocId) -> Result<(), SQLError>,
174) -> Result<(), SQLError> {
175    let mut after = None;
176    let limit = (control.memory().limit() / (4 * std::mem::size_of::<DocId>()))
177        .clamp(1, crate::DEFAULT_BATCH_SIZE);
178    loop {
179        control.cancellation().check()?;
180        let ids = reads.live_table_doc_id_page(table, after, limit, control)?;
181        let Some(last) = ids.last().copied() else {
182            break;
183        };
184        after = Some(last);
185        for id in ids.iter().copied() {
186            control.cancellation().check()?;
187            visit(id)?;
188        }
189    }
190    Ok(())
191}
192
193fn decode_identity(value: Option<Value>) -> Result<DocId, SQLError> {
194    let Some(Value::Bytes(bytes)) = value else {
195        return Err(SQLError::Internal("rewritten row lost its identity".into()));
196    };
197    let bytes = bytes
198        .try_into()
199        .map_err(|_| SQLError::Internal("rewritten row has an invalid identity".into()))?;
200    Ok(DocId::from_le_bytes(bytes))
201}
202
203#[cfg(test)]
204mod tests;