Skip to main content

uqa_execution/mutation/
returning.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Physical OLD/NEW row images and RETURNING projection results.
8use crate::{
9    mutation::{
10        errors::dml_storage_error,
11        row_images::{MutationRowImage, MutationRowImages},
12        rows::context::MutationRowContext,
13    },
14    query::{relational::RelationalContext, CteScope},
15    OwnedPhysicalRow, PhysicalRow, RowSchema,
16};
17use std::collections::BTreeSet;
18use uqa_core::Value;
19use uqa_sql::{
20    ast::ReturningAliases,
21    plan::ProjectionPlan,
22    routines::RoutineResolution,
23    semantics::{
24        doc_id_value,
25        returning::{expanded_returning_projections, returning_target_schema, ReturningCatalog},
26        returning_expression_schema, returning_schema_for_target, DOC_ID_COLUMN, TABLE_OID_COLUMN,
27    },
28    SQLError, SQLParam, SQLResult,
29};
30
31#[derive(Clone)]
32pub struct ReturningExecutionContext<'a, S: Clone + 'static> {
33    pub rows: MutationRowContext<'a>,
34    pub catalog: &'a dyn ReturningCatalog,
35    pub routines: &'a dyn RoutineResolution,
36    pub relational: RelationalContext<'a, S>,
37}
38impl<S: Clone + 'static> Copy for ReturningExecutionContext<'_, S> {}
39
40#[derive(Clone)]
41pub struct ReturningProjectionRow<'a> {
42    pub table: &'a str,
43    pub target_qualifier: &'a str,
44    pub images: MutationRowImages<'a>,
45    pub aliases: &'a ReturningAliases,
46    pub context: Option<&'a OwnedPhysicalRow>,
47}
48
49#[derive(Clone, Copy)]
50pub struct ReturningValueProjectionRow<'a> {
51    pub table: &'a str,
52    pub target_qualifier: &'a str,
53    pub current: &'a [Value],
54    pub old: Option<&'a [Value]>,
55    pub new: Option<&'a [Value]>,
56    pub aliases: &'a ReturningAliases,
57    pub context: Option<&'a OwnedPhysicalRow>,
58}
59
60pub struct DmlReturningShape<'a, S: Clone + 'static> {
61    pub table: &'a str,
62    pub target_qualifier: &'a str,
63    pub aliases: &'a ReturningAliases,
64    pub returning: &'a [ProjectionPlan],
65    pub params: &'a [SQLParam],
66    pub ctes: &'a CteScope<S>,
67    pub supplemental_schema: Option<&'a RowSchema>,
68}
69
70pub fn returning_image_values<S: Clone + 'static>(
71    services: ReturningExecutionContext<'_, S>,
72    image: Option<&MutationRowImage<'_>>,
73    columns: &[String],
74    definitions: &[uqa_sql::ast::ColumnDef],
75) -> Result<Vec<Value>, SQLError> {
76    let Some(image) = image else {
77        return Ok(vec![Value::Null; columns.len()]);
78    };
79    let mut document = image.document.clone();
80    crate::query::generated::materialize_virtual_generated_columns(definitions, &mut document)?;
81    columns
82        .iter()
83        .map(|column| {
84            if super::rows::is_virtual_document_id_column(column, definitions) {
85                doc_id_value(image.doc_id)
86            } else if definitions.iter().any(|definition| {
87                definition.name == *column && definition.primary_key && definition.ty.is_integer()
88            }) {
89                super::rows::integer_key_value(&document, column, Some(image.doc_id))
90            } else if column == TABLE_OID_COLUMN {
91                Ok(Value::Int(
92                    services
93                        .rows
94                        .tuples
95                        .table_relation_oid(&image.storage_table)?,
96                ))
97            } else {
98                Ok(crate::query::document_projection::project_document_column(
99                    &document,
100                    image.metadata,
101                    column,
102                    definitions,
103                ))
104            }
105        })
106        .collect()
107}
108
109pub fn build_returning_row<S: Clone + 'static>(
110    services: ReturningExecutionContext<'_, S>,
111    input: ReturningProjectionRow<'_>,
112    returning: &[ProjectionPlan],
113    params: &[SQLParam],
114    ctes: &CteScope<S>,
115) -> Result<OwnedPhysicalRow, SQLError> {
116    let row = returning_projection_context(services, input.clone())?;
117    let projections = expanded_returning_projections(
118        services.catalog,
119        input.table,
120        input.target_qualifier,
121        input.aliases,
122        returning,
123    )?;
124    let snapshot_scope = ctes.returning_statement_snapshot_scope();
125    crate::query::relational::project_row::build_projection_physical_row_with_ctes(
126        services.relational,
127        &row,
128        &projections,
129        params,
130        &snapshot_scope,
131    )
132}
133
134pub fn build_returning_value_row<S: Clone + 'static>(
135    services: ReturningExecutionContext<'_, S>,
136    input: ReturningValueProjectionRow<'_>,
137    returning: &[ProjectionPlan],
138    params: &[SQLParam],
139    ctes: &CteScope<S>,
140) -> Result<OwnedPhysicalRow, SQLError> {
141    let row = returning_value_context(services, input)?;
142    let projections = expanded_returning_projections(
143        services.catalog,
144        input.table,
145        input.target_qualifier,
146        input.aliases,
147        returning,
148    )?;
149    let snapshot_scope = ctes.returning_statement_snapshot_scope();
150    crate::query::relational::project_row::build_projection_physical_row_with_ctes(
151        services.relational,
152        &row,
153        &projections,
154        params,
155        &snapshot_scope,
156    )
157}
158
159pub fn returning_value_context<S: Clone + 'static>(
160    services: ReturningExecutionContext<'_, S>,
161    input: ReturningValueProjectionRow<'_>,
162) -> Result<OwnedPhysicalRow, SQLError> {
163    let target = returning_target_schema(services.catalog, input.table)?;
164    let width = target.len();
165    if input.current.len() != width
166        || input.old.is_some_and(|row| row.len() != width)
167        || input.new.is_some_and(|row| row.len() != width)
168    {
169        return Err(SQLError::Internal(
170            "rewrite-rule RETURNING row does not match the event relation".into(),
171        ));
172    }
173    let mut columns = target.columns().to_vec();
174    let mut types = target.column_types().to_vec();
175    let append_doc_id = !columns.iter().any(|column| column == DOC_ID_COLUMN);
176    if append_doc_id {
177        columns.push(DOC_ID_COLUMN.into());
178        types.push(Some(uqa_sql::ast::ColumnType::BigInteger));
179    }
180    let image = |row: Option<&[Value]>| {
181        let mut values = row.map_or_else(|| vec![Value::Null; width], <[Value]>::to_vec);
182        if append_doc_id {
183            values.push(Value::Null);
184        }
185        values
186    };
187    let mut current = input.current.to_vec();
188    if append_doc_id {
189        current.push(Value::Null);
190    }
191    let schema = RowSchema::with_qualified_types(input.target_qualifier, columns.clone(), types)
192        .with_column_collations(
193            (0..columns.len()).map(|position| target.column_collation(position)),
194        );
195    let schema = returning_schema_for_target(schema, width, input.aliases);
196    let values = current
197        .into_iter()
198        .chain(image(input.old))
199        .chain(image(input.new))
200        .collect();
201    let target = OwnedPhysicalRow::new(schema, PhysicalRow::from_values(values));
202    Ok(input.context.map_or(target.clone(), |context| {
203        OwnedPhysicalRow::new(
204            RowSchema::join(&target.schema, &context.schema, std::iter::empty()),
205            PhysicalRow::concat(&target.row, &context.row),
206        )
207    }))
208}
209
210pub fn returning_projection_context<S: Clone + 'static>(
211    services: ReturningExecutionContext<'_, S>,
212    input: ReturningProjectionRow<'_>,
213) -> Result<OwnedPhysicalRow, SQLError> {
214    let target = returning_row_context(
215        services,
216        input.table,
217        input.target_qualifier,
218        input.images,
219        input.aliases,
220    )?;
221    let row = input.context.map_or(target.clone(), |context| {
222        OwnedPhysicalRow::new(
223            RowSchema::join(&target.schema, &context.schema, std::iter::empty()),
224            PhysicalRow::concat(&target.row, &context.row),
225        )
226    });
227    Ok(row)
228}
229
230pub fn dml_returning_result<S: Clone + 'static>(
231    services: ReturningExecutionContext<'_, S>,
232    shape: DmlReturningShape<'_, S>,
233    rows: Vec<OwnedPhysicalRow>,
234    affected_rows: u64,
235) -> Result<SQLResult, SQLError> {
236    let projections = expanded_returning_projections(
237        services.catalog,
238        shape.table,
239        shape.target_qualifier,
240        shape.aliases,
241        shape.returning,
242    )?;
243    dml_returning_result_with_projections(services, shape, &projections, rows, affected_rows)
244}
245
246pub fn dml_returning_result_with_projections<S: Clone + 'static>(
247    services: ReturningExecutionContext<'_, S>,
248    shape: DmlReturningShape<'_, S>,
249    projections: &[ProjectionPlan],
250    rows: Vec<OwnedPhysicalRow>,
251    affected_rows: u64,
252) -> Result<SQLResult, SQLError> {
253    let star_schema = returning_target_schema(services.catalog, shape.table)?;
254    let expression_schema = returning_expression_schema(
255        &star_schema,
256        shape.target_qualifier,
257        shape.aliases,
258        shape.supplemental_schema,
259    );
260    let output = crate::query::binding::bind_projection_output_schema(
261        services.routines,
262        projections,
263        &expression_schema,
264        &star_schema,
265        &shape.ctes.scalar_subqueries,
266        shape.params,
267        shape.ctes,
268    )?;
269    let preserve_positions =
270        output.columns().iter().collect::<BTreeSet<_>>().len() != output.columns().len();
271    let mut named_rows = Vec::with_capacity(rows.len());
272    let mut positional_rows = preserve_positions.then(|| Vec::with_capacity(rows.len()));
273    for row in rows {
274        if let Some(positional_rows) = positional_rows.as_mut() {
275            positional_rows.push(row.view().iter().map(|(_, value)| value.clone()).collect());
276        }
277        named_rows.push(row.into_result_row());
278    }
279    let mut result = SQLResult::from_schema_rows_with_positions(
280        output.for_result_columns(output.columns()),
281        named_rows,
282        positional_rows,
283    );
284    result.affected_rows = affected_rows;
285    Ok(result)
286}
287
288pub fn returning_row_context<S: Clone + 'static>(
289    services: ReturningExecutionContext<'_, S>,
290    table: &str,
291    target_qualifier: &str,
292    images: MutationRowImages<'_>,
293    aliases: &ReturningAliases,
294) -> Result<OwnedPhysicalRow, SQLError> {
295    let current = images.new.as_ref().or(images.old.as_ref()).ok_or_else(|| {
296        SQLError::Internal(format!(
297            "RETURNING for table `{table}` has neither an old nor a new row image"
298        ))
299    })?;
300    let definitions = services
301        .rows
302        .relations
303        .column_definitions(table)
304        .map_err(|error| dml_storage_error("RETURNING schema lookup", error))?
305        .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?;
306    let target = returning_target_schema(services.catalog, table)?;
307    let composite_width = target.len();
308    let mut columns = target.columns().to_vec();
309    let mut types = target.column_types().to_vec();
310    if !columns.iter().any(|column| column == DOC_ID_COLUMN) {
311        columns.push(DOC_ID_COLUMN.into());
312        types.push(Some(uqa_sql::ast::ColumnType::BigInteger));
313    }
314    columns.push(TABLE_OID_COLUMN.into());
315    types.push(Some(uqa_sql::ast::ColumnType::Oid));
316    columns.push(uqa_sql::semantics::XMIN_COLUMN.into());
317    types.push(Some(uqa_sql::ast::ColumnType::Xid));
318    let schema = RowSchema::with_qualified_types(target_qualifier, columns.clone(), types)
319        .with_column_collations(
320            (0..columns.len()).map(|position| target.column_collation(position)),
321        );
322    let schema = returning_schema_for_target(schema, composite_width, aliases);
323    let current_values = returning_image_values(services, Some(current), &columns, &definitions)?;
324    let old_values = returning_image_values(services, images.old.as_ref(), &columns, &definitions)?;
325    let new_values = returning_image_values(services, images.new.as_ref(), &columns, &definitions)?;
326    let values = current_values
327        .into_iter()
328        .chain(old_values)
329        .chain(new_values)
330        .collect();
331    Ok(OwnedPhysicalRow::new(
332        schema,
333        PhysicalRow::from_values(values),
334    ))
335}