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