Skip to main content

uqa_execution/schema/columns/rows/
changes.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Index surviving transaction changes after a rewrite's original rows were retained.
8
9use crate::row_locks::{publication::TransactionRowChange, PendingRowChangeKind};
10use uqa_core::{memory::MemoryBudget, CancellationToken, DocId};
11use uqa_sql::SQLError;
12use uqa_storage::{
13    mvcc::{PrivateRecordChanges, PrivateRecordSnapshot, RecordWrite, VersionError},
14    read_control::StorageReadControl,
15};
16
17/// Borrow the current transaction's surviving row changes in outer-to-inner frame order and append order within each frame. The slices and their order must remain stable for one visit; committing an inner frame appends its changes to its parent, while rollback removes them.
18pub trait RewriteRowChanges {
19    fn storage_generation(&self, table: &str) -> Result<[u8; 16], SQLError>;
20    fn visit_changes(
21        &self,
22        visit: &mut dyn FnMut(&[TransactionRowChange]) -> Result<(), SQLError>,
23    ) -> Result<(), SQLError>;
24}
25
26/// Retain the length of the transaction's current prefix. The enclosing statement must keep that prefix alive until all relation rewrites finish.
27pub fn marker(owner: &dyn RewriteRowChanges) -> Result<usize, SQLError> {
28    let mut length = 0_usize;
29    owner.visit_changes(&mut |changes| {
30        length = length
31            .checked_add(changes.len())
32            .ok_or_else(|| SQLError::Internal("column rewrite change marker overflowed".into()))?;
33        Ok(())
34    })?;
35    Ok(length)
36}
37
38/// The final presence of each changed identity, including deleted rows. Its immutable private root and spill readers share the rewrite's allowance and cancellation signal.
39pub struct ChangedRows {
40    snapshot: Option<PrivateRecordSnapshot>,
41    control: StorageReadControl,
42}
43
44/// Index only changes still present after `marker`. A rewrite removes its source identity and adds its successor in their respective storage generations; repeated changes retain only the final presence. No row payload or complete change log is copied.
45pub fn capture_since(
46    owner: &dyn RewriteRowChanges,
47    marker: usize,
48    generation: [u8; 16],
49    memory: &MemoryBudget,
50    cancellation: &CancellationToken,
51) -> Result<ChangedRows, SQLError> {
52    cancellation.check()?;
53    let control = StorageReadControl::new(memory, cancellation);
54    let records = PrivateRecordChanges::new(memory);
55    let mut skip = marker;
56    owner.visit_changes(&mut |changes| {
57        cancellation.check()?;
58        let skipped = skip.min(changes.len());
59        skip -= skipped;
60        for change in &changes[skipped..] {
61            cancellation.check()?;
62            note_change(&records, change, generation, &control)?;
63        }
64        Ok(())
65    })?;
66    if skip != 0 {
67        return Err(SQLError::Internal(
68            "column rewrite change marker no longer belongs to this transaction".into(),
69        ));
70    }
71    cancellation.check()?;
72    let snapshot = records
73        .has_written()
74        .then(|| records.snapshot().map_err(storage_error))
75        .transpose()?;
76    Ok(ChangedRows { snapshot, control })
77}
78
79fn note_change(
80    records: &PrivateRecordChanges,
81    change: &TransactionRowChange,
82    generation: [u8; 16],
83    control: &StorageReadControl,
84) -> Result<(), SQLError> {
85    if change.source_generation == generation {
86        note(
87            records,
88            change.pending.key.doc_id,
89            matches!(
90                change.pending.kind,
91                PendingRowChangeKind::Insert | PendingRowChangeKind::Update
92            ),
93            control,
94        )?;
95    }
96    if let PendingRowChangeKind::Rewrite(successor) = change.pending.kind {
97        if change.successor_generation == Some(generation) {
98            note(records, successor.doc_id, true, control)?;
99        }
100    }
101    Ok(())
102}
103
104fn note(
105    records: &PrivateRecordChanges,
106    id: DocId,
107    present: bool,
108    control: &StorageReadControl,
109) -> Result<(), SQLError> {
110    records
111        .apply(
112            &[RecordWrite {
113                key: &id.to_be_bytes(),
114                expected: None,
115                value: Some(&[u8::from(present)]),
116            }],
117            control,
118        )
119        .map_err(storage_error)
120}
121
122impl ChangedRows {
123    /// Whether no change of the selected generation was recorded. A final deletion remains a changed identity.
124    pub fn is_empty(&self) -> bool {
125        self.snapshot.is_none()
126    }
127
128    pub fn get(&self, id: DocId) -> Result<Option<bool>, SQLError> {
129        self.control.cancellation().check()?;
130        let Some(snapshot) = &self.snapshot else {
131            return Ok(None);
132        };
133        snapshot
134            .get(&id.to_be_bytes(), &self.control)
135            .map_err(storage_error)?
136            .map(|write| presence(write.value()))
137            .transpose()
138    }
139
140    /// Visit every changed identity once in increasing numeric order, including tombstones. Callback errors stop replay immediately and release its readers.
141    pub fn visit(
142        &self,
143        visit: &mut dyn FnMut(DocId, bool) -> Result<(), SQLError>,
144    ) -> Result<(), SQLError> {
145        self.control.cancellation().check()?;
146        let Some(snapshot) = &self.snapshot else {
147            return Ok(());
148        };
149        let mut cursor = snapshot
150            .cursor(&[], None, &self.control)
151            .map_err(storage_error)?;
152        while let Some(entry) = cursor.next(&self.control).map_err(storage_error)? {
153            let id = DocId::from_be_bytes(entry.key().try_into().map_err(|_| {
154                SQLError::Internal("a changed rewrite row has an invalid identity".into())
155            })?);
156            let present = {
157                let write = entry.read(&self.control).map_err(storage_error)?;
158                presence(write.value())?
159            };
160            drop(entry);
161            visit(id, present)?;
162        }
163        Ok(())
164    }
165}
166
167fn presence(value: Option<&[u8]>) -> Result<bool, SQLError> {
168    match value {
169        Some([0]) => Ok(false),
170        Some([1]) => Ok(true),
171        _ => Err(SQLError::Internal(
172            "a changed rewrite row has an invalid presence".into(),
173        )),
174    }
175}
176
177fn storage_error(error: VersionError) -> SQLError {
178    crate::storage_errors::storage_error(
179        "retain changed column rewrite rows",
180        &error.into_storage_error(),
181    )
182}
183
184#[cfg(test)]
185mod tests;