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