Skip to main content

uqa_execution/schema/columns/
generated.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Rewrite a table's rows as `ATRewriteTable` does: recompute generated columns, check the new rows, remap physical primary keys, and validate the foreign keys involved.
8use super::rows::RewriteRows;
9use crate::mutation::{
10    assignment::MutationAssignmentContext, constraints::context::ConstraintContext,
11    publication::MutationStorage,
12};
13use crate::schema::keys::KeyValidationContext;
14use uqa_core::DocId;
15use uqa_sql::SQLError;
16use uqa_storage::StorageBackendResult;
17pub trait GeneratedRewriteState {
18    fn advance_next_id(&self, table: &str, id: DocId) -> StorageBackendResult<()>;
19}
20pub struct GeneratedRewriteContext<'a, S: Clone + 'static> {
21    pub cancellation: &'a uqa_core::CancellationToken,
22    pub keys: KeyValidationContext<'a>,
23    pub assignment: MutationAssignmentContext<'a, S>,
24    pub storage: &'a dyn MutationStorage,
25    pub state: &'a dyn GeneratedRewriteState,
26    pub identifiers: &'a dyn crate::mutation::identity::MutationIdentifiers,
27}
28/// Publish an already assigned backfill field through the prepared storage path. A schema rewrite must preserve all unrelated stored generated values instead of invoking ordinary DML generation.
29pub fn update_rewritten_fields<S: Clone + 'static>(
30    context: &GeneratedRewriteContext<'_, S>,
31    table: &str,
32    id: DocId,
33    values: std::collections::BTreeMap<String, uqa_core::Value>,
34    vectors: crate::mutation::publication::DocumentVectors,
35) -> Result<bool, SQLError> {
36    context.cancellation.check()?;
37    let Some(mut document) = context.keys.constraints.reads.get_document(table, id)? else {
38        return Ok(false);
39    };
40    document.extend(values);
41    let mut replacement_vectors = crate::mutation::vectors::document_vectors(
42        context.keys.constraints.catalog,
43        table,
44        &document,
45    )?;
46    replacement_vectors.extend(vectors);
47    context.storage.insert_document(
48        table,
49        id,
50        document,
51        replacement_vectors,
52        crate::mutation::publication::InsertedIdentity::Unknown,
53    )?;
54    Ok(true)
55}
56
57/// Recompute the requested stored generated columns of every row of `table` and, when `rewrite_physical_rows`, rewrite the table with them, as adding a stored generated column or changing its expression does.
58pub fn validate_and_rewrite_generated_rows<S: Clone + 'static>(
59    context: &GeneratedRewriteContext<'_, S>,
60    table: &str,
61    rewrite_physical_rows: bool,
62    changed: &[String],
63) -> Result<(), SQLError> {
64    let allowance = context.keys.constraints.memory.work_mem_bytes()?;
65    let memory = uqa_core::memory::MemoryBudget::new(allowance / 2);
66    let read_memory = uqa_core::memory::MemoryBudget::new(allowance - allowance / 2);
67    let control =
68        uqa_storage::read_control::StorageReadControl::new(&read_memory, context.cancellation);
69    let mut original =
70        super::rows::capture(context.keys.constraints.reads, table, &memory, &control)?;
71    let columns =
72        crate::mutation::assignment::describe_generated_columns(context.assignment, table)?;
73    let resources = context
74        .assignment
75        .expressions
76        .expressions
77        .production_resources()?;
78    let production = resources.control();
79    let schema = crate::mutation::generated::generated_row_schema(&columns, &production)?;
80    // PostgreSQL plans every rewrite expression even for an empty relation; row evaluation still preserves conditional branches and error order.
81    let mut expressions = uqa_core::memory::ProductionVec::new(production);
82    for (_, generated) in
83        crate::mutation::generated::stored_generation_expressions(&columns, Some(changed))
84    {
85        context.cancellation.check()?;
86        let expression = crate::query::catalog_expression::PreparedCatalogExpression::lower(
87            context.assignment.expressions.expressions,
88            context.assignment.scopes.current_routine_scope()?,
89            &generated.expression,
90            &schema,
91            &[],
92        )?;
93        expressions
94            .push_produced(production.finish(expression, production.empty_reservation())?)?;
95    }
96    let expressions = expressions.finish()?;
97    let mut rows = RewriteRows::new(&memory);
98    for position in 0..original.len() {
99        context.cancellation.check()?;
100        let super::rows::RewriteRow {
101            original_id: doc_id,
102            mut document,
103            ..
104        } = original.get(position)?;
105        let mut expression_index = 0;
106        crate::mutation::generated::refresh_stored_generated_columns(
107            context.assignment.assignment,
108            &columns,
109            Some(changed),
110            &mut document,
111            &production,
112            &mut |_, row, _| {
113                let prepared = &expressions[expression_index];
114                expression_index += 1;
115                prepared.evaluate(row)
116            },
117        )?;
118        rows.push(doc_id, document)?;
119    }
120    drop(expressions);
121    drop(original);
122    rewrite_table_rows(context, table, rows, rewrite_physical_rows, changed)
123}
124
125/// Replace the rows of `table` with the rows a rewrite produced, as `ATRewriteTable` does. Each new row is checked against the table's validated NOT NULL and CHECK constraints, then the key constraints are checked across all of them, as rebuilding their indexes does; when `write`, the rows replace the old ones, a row whose integer primary key changed moving to the identity that key names. The foreign keys that involve a `changed` column are validated against the result.
126pub fn rewrite_table_rows<S: Clone + 'static>(
127    context: &GeneratedRewriteContext<'_, S>,
128    table: &str,
129    mut rows: RewriteRows,
130    write: bool,
131    changed: &[String],
132) -> Result<(), SQLError> {
133    for position in 0..rows.len() {
134        context.cancellation.check()?;
135        let row = rows.get(position)?;
136        crate::mutation::constraints::validate_rewritten_row(
137            context.keys.constraints,
138            table,
139            &row.document,
140        )?;
141    }
142    publish_validated_rows(context, table, rows, write)?;
143    crate::schema::validation::validate_rewritten_foreign_keys(
144        context.keys.constraints,
145        table,
146        changed,
147    )
148}
149
150/// Publish rows whose row-local checks have already run in conversion order, then verify the cross-row keys.
151pub(in crate::schema) fn publish_validated_rows<S: Clone + 'static>(
152    context: &GeneratedRewriteContext<'_, S>,
153    table: &str,
154    mut rows: RewriteRows,
155    write: bool,
156) -> Result<(), SQLError> {
157    super::super::keys::validate_key_constraint_rows(&context.keys, table, &mut rows)?;
158    if write {
159        publish_rewritten_rows(context, table, rows)?;
160        super::super::keys::validate_temporal_key_rows(&context.keys, table)?;
161    }
162    Ok(())
163}
164
165fn publish_rewritten_rows<S: Clone + 'static>(
166    context: &GeneratedRewriteContext<'_, S>,
167    table: &str,
168    mut rows: RewriteRows,
169) -> Result<(), SQLError> {
170    let mut replacements = RewriteRows::new(rows.memory());
171    for position in 0..rows.len() {
172        context.cancellation.check()?;
173        let super::rows::RewriteRow {
174            original_id: old_doc_id,
175            document,
176            ..
177        } = rows.get(position)?;
178        let new_doc_id = crate::mutation::identity::key_relocation(
179            context.keys.constraints.catalog,
180            context.identifiers,
181            table,
182            old_doc_id,
183            &document,
184        )?
185        .unwrap_or(old_doc_id);
186        replacements.push_replacement(old_doc_id, new_doc_id, document)?;
187    }
188    drop(rows);
189    // A rewrite replaces the heap captured at its start. Self-modifying callbacks cannot leave additional old-heap rows beside that replacement.
190    replacements.spill()?;
191    remove_replaced_rows(context, table, replacements.memory())?;
192    for position in 0..replacements.len() {
193        context.cancellation.check()?;
194        let super::rows::RewriteRow {
195            original_id: old_doc_id,
196            target_id: new_doc_id,
197            document,
198        } = replacements.get(position)?;
199        let vectors = crate::mutation::vectors::document_vectors(
200            context.keys.constraints.catalog,
201            table,
202            &document,
203        )?;
204        context.storage.insert_document(
205            table,
206            new_doc_id,
207            document,
208            vectors,
209            crate::mutation::publication::InsertedIdentity::Vacant,
210        )?;
211        if new_doc_id != old_doc_id {
212            context
213                .state
214                .advance_next_id(table, new_doc_id)
215                .map_err(|error| {
216                    crate::mutation::errors::identifier_storage_error(
217                        "rewritten primary key",
218                        &error,
219                    )
220                })?;
221        }
222    }
223    Ok(())
224}
225
226fn remove_replaced_rows<S: Clone + 'static>(
227    context: &GeneratedRewriteContext<'_, S>,
228    table: &str,
229    memory: &uqa_core::memory::MemoryBudget,
230) -> Result<(), SQLError> {
231    let control = uqa_storage::read_control::StorageReadControl::new(memory, context.cancellation);
232    let limit = (memory.available() / (4 * std::mem::size_of::<DocId>()))
233        .clamp(1, crate::DEFAULT_BATCH_SIZE);
234    let mut after = None;
235    loop {
236        context.cancellation.check()?;
237        let ids = context
238            .keys
239            .constraints
240            .reads
241            .live_table_doc_id_page(table, after, limit, &control)?;
242        let Some(last) = ids.last().copied() else {
243            return Ok(());
244        };
245        after = Some(last);
246        for id in ids.iter().copied() {
247            context.cancellation.check()?;
248            context.storage.delete_document(table, id)?;
249        }
250    }
251}
252
253/// The stored generated columns of `table`, whose values a rewrite of the table recomputes.
254pub fn stored_generated_columns(
255    constraints: ConstraintContext<'_>,
256    table: &str,
257) -> Result<Vec<String>, SQLError> {
258    Ok(constraints
259        .catalog
260        .try_describe_table(table)
261        .map_err(|error| crate::mutation::errors::dml_storage_error("table rewrite", error))?
262        .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?
263        .into_iter()
264        .filter(|column| {
265            column.generated.as_ref().is_some_and(|generated| {
266                generated.kind == uqa_sql::ast::GeneratedColumnKind::Stored
267            })
268        })
269        .map(|column| column.name)
270        .collect())
271}