Skip to main content

uqa_execution/mutation/rules/
rows.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Ordered event images retain one complete source schema and bounded encoded rows.
8
9use std::borrow::Cow;
10use std::sync::Arc;
11
12use parking_lot::Mutex;
13use uqa_core::{CancellationToken, Value};
14use uqa_sql::SQLError;
15
16use crate::mutation::prepared::{decode_prepared_doc_id, encode_prepared_doc_id};
17use crate::physical::physical_exec_error;
18use crate::spill::{decode_physical_row_record, encode_physical_row_record, BufferedIndexedSpill};
19use crate::{OwnedPhysicalRow, PhysicalRow, RowSchema};
20
21use super::RuleRowImage;
22
23const WIDTH: usize = 8;
24const VERSION: i64 = 1;
25
26pub struct RuleRowBuffer {
27    rows: BufferedIndexedSpill,
28    context_schema: Option<RowSchema>,
29    cancellation: CancellationToken,
30}
31
32impl RuleRowBuffer {
33    pub fn new(bytes: usize, cancellation: CancellationToken) -> Self {
34        Self {
35            rows: BufferedIndexedSpill::new(RowSchema::new(vec![String::new(); WIDTH]), bytes),
36            context_schema: None,
37            cancellation,
38        }
39    }
40
41    pub fn push(&mut self, row: RuleRowImage) -> Result<(), SQLError> {
42        self.cancellation.check()?;
43        if self.rows.len() == usize::MAX as u64 {
44            return Err(invalid("event count exceeds the addressable index range"));
45        }
46        let mut context_schema = None;
47        let context = if let Some(context) = row.context {
48            if self
49                .context_schema
50                .as_ref()
51                .is_some_and(|schema| *schema != context.schema)
52            {
53                return Err(invalid("source schema changed within one event query"));
54            }
55            let encoded = encode_physical_row_record(&context.row, context.schema.physical_width())
56                .map_err(physical_exec_error)?;
57            context_schema = Some(context.schema);
58            Value::Bytes(encoded)
59        } else {
60            Value::Null
61        };
62        self.rows
63            .push(&PhysicalRow::from_values(vec![
64                Value::Int(VERSION),
65                row.old_storage_table.map_or(Value::Null, Value::Str),
66                row.old_doc_id.map_or(Value::Null, encode_prepared_doc_id),
67                row.old.map_or(Value::Null, Value::Map),
68                row.new_storage_table.map_or(Value::Null, Value::Str),
69                row.new_doc_id.map_or(Value::Null, encode_prepared_doc_id),
70                row.new.map_or(Value::Null, Value::Map),
71                context,
72            ]))
73            .map_err(physical_exec_error)?;
74        if self.context_schema.is_none() {
75            self.context_schema = context_schema;
76        }
77        Ok(())
78    }
79
80    pub fn len(&self) -> usize {
81        usize::try_from(self.rows.len()).expect("push checks the addressable row count")
82    }
83
84    pub fn is_empty(&self) -> bool {
85        self.len() == 0
86    }
87
88    pub fn finish(self) -> RuleRows {
89        let len = self.len();
90        RuleRows(Arc::new(RuleRowsInner {
91            rows: Mutex::new(self.rows),
92            context_schema: self.context_schema,
93            cancellation: self.cancellation,
94            len,
95        }))
96    }
97}
98
99struct RuleRowsInner {
100    rows: Mutex<BufferedIndexedSpill>,
101    context_schema: Option<RowSchema>,
102    cancellation: CancellationToken,
103    len: usize,
104}
105
106/// Shared immutable event ownership; callbacks never run while its positional reader is locked.
107#[derive(Clone)]
108pub struct RuleRows(Arc<RuleRowsInner>);
109
110/// Original ordered event access, independent of an upstream producer's storage representation.
111pub trait RuleEventSource {
112    fn event_count(&self) -> usize;
113    fn event_row(&self, index: usize) -> Result<Cow<'_, RuleRowImage>, SQLError>;
114}
115
116impl RuleEventSource for RuleRows {
117    fn event_count(&self) -> usize {
118        self.len()
119    }
120    fn event_row(&self, index: usize) -> Result<Cow<'_, RuleRowImage>, SQLError> {
121        self.get(index).map(Cow::Owned)
122    }
123}
124
125impl RuleEventSource for [RuleRowImage] {
126    fn event_count(&self) -> usize {
127        self.len()
128    }
129    fn event_row(&self, index: usize) -> Result<Cow<'_, RuleRowImage>, SQLError> {
130        self.get(index)
131            .map(Cow::Borrowed)
132            .ok_or_else(|| invalid("source index is outside the event row set"))
133    }
134}
135
136impl RuleEventSource for Vec<RuleRowImage> {
137    fn event_count(&self) -> usize {
138        self.len()
139    }
140    fn event_row(&self, index: usize) -> Result<Cow<'_, RuleRowImage>, SQLError> {
141        self.as_slice().event_row(index)
142    }
143}
144
145impl RuleRows {
146    pub fn from_rows(
147        rows: impl IntoIterator<Item = Result<RuleRowImage, SQLError>>,
148        bytes: usize,
149        cancellation: CancellationToken,
150    ) -> Result<Self, SQLError> {
151        let mut buffer = RuleRowBuffer::new(bytes, cancellation);
152        for row in rows {
153            buffer.push(row?)?;
154        }
155        Ok(buffer.finish())
156    }
157
158    pub fn len(&self) -> usize {
159        self.0.len
160    }
161
162    pub fn is_empty(&self) -> bool {
163        self.len() == 0
164    }
165
166    pub fn get(&self, index: usize) -> Result<RuleRowImage, SQLError> {
167        self.0.cancellation.check()?;
168        if index >= self.len() {
169            return Err(invalid("source index is outside the event row set"));
170        }
171        let row = self
172            .0
173            .rows
174            .lock()
175            .get(index as u64)
176            .map_err(physical_exec_error)?;
177        decode(row, self.0.context_schema.as_ref())
178    }
179
180    pub fn iter(&self) -> impl Iterator<Item = Result<RuleRowImage, SQLError>> + '_ {
181        (0..self.len()).map(|index| self.get(index))
182    }
183
184    pub(crate) fn select_indices(
185        &self,
186        indices: &super::RuleIndices,
187        bytes: usize,
188        cancellation: CancellationToken,
189    ) -> Result<Self, SQLError> {
190        cancellation.check()?;
191        if indices.is_all(self.len()) {
192            return Ok(self.clone());
193        }
194        Self::from_rows(
195            indices.reader()?.map(|index| self.get(index?)),
196            bytes,
197            cancellation,
198        )
199    }
200
201    pub fn select(
202        &self,
203        indices: &[usize],
204        bytes: usize,
205        cancellation: CancellationToken,
206    ) -> Result<Self, SQLError> {
207        cancellation.check()?;
208        if indices.len() == self.len() && indices.iter().copied().eq(0..self.len()) {
209            return Ok(self.clone());
210        }
211        Self::from_rows(
212            indices.iter().map(|index| self.get(*index)),
213            bytes,
214            cancellation,
215        )
216    }
217}
218
219fn decode(row: PhysicalRow, schema: Option<&RowSchema>) -> Result<RuleRowImage, SQLError> {
220    let values: [Value; WIDTH] = row
221        .into_physical_values()
222        .try_into()
223        .map_err(|_| invalid("encoded event has an invalid width"))?;
224    let [version, old_table, old_id, old, new_table, new_id, new, context] = values;
225    if !matches!(version, Value::Int(VERSION)) {
226        return Err(invalid("encoded event has an invalid version"));
227    }
228    let context = match context {
229        Value::Null => None,
230        Value::Bytes(bytes) => {
231            let schema = schema.ok_or_else(|| invalid("source context lost its schema"))?;
232            let row = decode_physical_row_record(&bytes, schema.physical_width())
233                .map_err(physical_exec_error)?;
234            Some(OwnedPhysicalRow::new(schema.clone(), row))
235        }
236        _ => return Err(invalid("source context is not an encoded physical row")),
237    };
238    Ok(RuleRowImage {
239        old_storage_table: optional_table(old_table)?,
240        old_doc_id: optional_id(old_id)?,
241        old: optional_document(old)?,
242        new_storage_table: optional_table(new_table)?,
243        new_doc_id: optional_id(new_id)?,
244        new: optional_document(new)?,
245        context,
246    })
247}
248
249fn optional_table(value: Value) -> Result<Option<String>, SQLError> {
250    match value {
251        Value::Null => Ok(None),
252        Value::Str(table) => Ok(Some(table)),
253        _ => Err(invalid("storage table is not text")),
254    }
255}
256
257fn optional_id(value: Value) -> Result<Option<uqa_core::DocId>, SQLError> {
258    if matches!(value, Value::Null) {
259        Ok(None)
260    } else {
261        decode_prepared_doc_id(value, "rewrite-rule event").map(Some)
262    }
263}
264
265fn optional_document(
266    value: Value,
267) -> Result<Option<uqa_storage::document_store::Document>, SQLError> {
268    match value {
269        Value::Null => Ok(None),
270        Value::Map(document) => Ok(Some(document)),
271        _ => Err(invalid("event image is not a document")),
272    }
273}
274
275fn invalid(message: &str) -> SQLError {
276    SQLError::Internal(format!("rewrite-rule {message}"))
277}
278
279#[cfg(test)]
280mod tests;