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_with_control(
139        &services
140            .relational
141            .expressions
142            .production_resources()?
143            .control(),
144    )?;
145    crate::query::relational::project_row::build_projection_physical_row_with_ctes(
146        services.relational,
147        &row,
148        &projections,
149        params,
150        &snapshot_scope,
151    )
152}
153
154pub fn build_returning_value_row<S: Clone + 'static>(
155    services: ReturningExecutionContext<'_, S>,
156    input: ReturningValueProjectionRow<'_>,
157    returning: &[ProjectionPlan],
158    params: &[SQLParam],
159    ctes: &CteScope<S>,
160) -> Result<OwnedPhysicalRow, SQLError> {
161    let row = returning_value_context(services, input)?;
162    let projections = expanded_returning_projections(
163        services.catalog,
164        input.table,
165        input.target_qualifier,
166        input.aliases,
167        returning,
168    )?;
169    let snapshot_scope = ctes.returning_statement_snapshot_scope_with_control(
170        &services
171            .relational
172            .expressions
173            .production_resources()?
174            .control(),
175    )?;
176    crate::query::relational::project_row::build_projection_physical_row_with_ctes(
177        services.relational,
178        &row,
179        &projections,
180        params,
181        &snapshot_scope,
182    )
183}
184
185pub fn returning_value_context<S: Clone + 'static>(
186    services: ReturningExecutionContext<'_, S>,
187    input: ReturningValueProjectionRow<'_>,
188) -> Result<OwnedPhysicalRow, SQLError> {
189    let target = returning_target_schema(services.catalog, input.table)?;
190    let width = target.len();
191    if input.current.len() != width
192        || input.old.is_some_and(|row| row.len() != width)
193        || input.new.is_some_and(|row| row.len() != width)
194    {
195        return Err(SQLError::Internal(
196            "rewrite-rule RETURNING row does not match the event relation".into(),
197        ));
198    }
199    let mut columns = target.columns().to_vec();
200    let mut types = target.column_types().to_vec();
201    let append_doc_id = !columns.iter().any(|column| column == DOC_ID_COLUMN);
202    if append_doc_id {
203        columns.push(DOC_ID_COLUMN.into());
204        types.push(Some(uqa_sql::ast::ColumnType::BigInteger));
205    }
206    let image = |row: Option<&[Value]>| {
207        let mut values = row.map_or_else(|| vec![Value::Null; width], <[Value]>::to_vec);
208        if append_doc_id {
209            values.push(Value::Null);
210        }
211        values
212    };
213    let mut current = input.current.to_vec();
214    if append_doc_id {
215        current.push(Value::Null);
216    }
217    let schema = RowSchema::with_qualified_types(input.target_qualifier, columns.clone(), types)
218        .with_column_collations(
219            (0..columns.len()).map(|position| target.column_collation(position)),
220        );
221    let schema = returning_schema_for_target(schema, width, input.aliases);
222    let values = current
223        .into_iter()
224        .chain(image(input.old))
225        .chain(image(input.new))
226        .collect();
227    let target = OwnedPhysicalRow::new(schema, PhysicalRow::from_values(values));
228    Ok(input.context.map_or(target.clone(), |context| {
229        OwnedPhysicalRow::new(
230            RowSchema::join(&target.schema, &context.schema, std::iter::empty()),
231            PhysicalRow::concat(&target.row, &context.row),
232        )
233    }))
234}
235
236pub fn returning_projection_context<S: Clone + 'static>(
237    services: ReturningExecutionContext<'_, S>,
238    input: ReturningProjectionRow<'_>,
239) -> Result<OwnedPhysicalRow, SQLError> {
240    let target = returning_row_context(
241        services,
242        input.table,
243        input.target_qualifier,
244        input.images,
245        input.aliases,
246    )?;
247    let row = input.context.map_or(target.clone(), |context| {
248        OwnedPhysicalRow::new(
249            RowSchema::join(&target.schema, &context.schema, std::iter::empty()),
250            PhysicalRow::concat(&target.row, &context.row),
251        )
252    });
253    Ok(row)
254}
255
256pub fn dml_returning_result<S: Clone + 'static>(
257    services: ReturningExecutionContext<'_, S>,
258    shape: DmlReturningShape<'_, S>,
259    rows: ReturningRows,
260    affected_rows: u64,
261) -> Result<crate::mutation::output::MutationOutput, SQLError> {
262    let projections = expanded_returning_projections(
263        services.catalog,
264        shape.table,
265        shape.target_qualifier,
266        shape.aliases,
267        shape.returning,
268    )?;
269    dml_returning_result_with_projections(services, shape, &projections, rows, affected_rows)
270}
271
272pub fn dml_returning_result_with_projections<S: Clone + 'static>(
273    services: ReturningExecutionContext<'_, S>,
274    shape: DmlReturningShape<'_, S>,
275    projections: &[ProjectionPlan],
276    rows: ReturningRows,
277    affected_rows: u64,
278) -> Result<crate::mutation::output::MutationOutput, SQLError> {
279    let star_schema = returning_target_schema(services.catalog, shape.table)?;
280    let expression_schema = returning_expression_schema(
281        &star_schema,
282        shape.target_qualifier,
283        shape.aliases,
284        shape.supplemental_schema,
285    );
286    let output = crate::query::binding::bind_projection_output_schema(
287        services.routines,
288        projections,
289        uqa_sql::binding::ProjectionSchemas {
290            expressions: &expression_schema,
291            star: &star_schema,
292        },
293        &shape.ctes.scalar_subqueries,
294        shape.params,
295        shape.ctes,
296        &services
297            .relational
298            .expressions
299            .production_resources()?
300            .control(),
301    )?;
302    crate::mutation::output::MutationOutput::from_returning(
303        output.for_result_columns(output.columns()),
304        rows,
305        affected_rows,
306    )
307}
308
309pub fn returning_row_context<S: Clone + 'static>(
310    services: ReturningExecutionContext<'_, S>,
311    table: &str,
312    target_qualifier: &str,
313    images: MutationRowImages<'_>,
314    aliases: &ReturningAliases,
315) -> Result<OwnedPhysicalRow, SQLError> {
316    let current = images.new.as_ref().or(images.old.as_ref()).ok_or_else(|| {
317        SQLError::Internal(format!(
318            "RETURNING for table `{table}` has neither an old nor a new row image"
319        ))
320    })?;
321    let definitions = services
322        .rows
323        .relations
324        .column_definitions(table)
325        .map_err(|error| dml_storage_error("RETURNING schema lookup", error))?
326        .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?;
327    let target = returning_target_schema(services.catalog, table)?;
328    let composite_width = target.len();
329    let mut columns = target.columns().to_vec();
330    let mut types = target.column_types().to_vec();
331    if !columns.iter().any(|column| column == DOC_ID_COLUMN) {
332        columns.push(DOC_ID_COLUMN.into());
333        types.push(Some(uqa_sql::ast::ColumnType::BigInteger));
334    }
335    columns.push(TABLE_OID_COLUMN.into());
336    types.push(Some(uqa_sql::ast::ColumnType::Oid));
337    columns.push(uqa_sql::semantics::XMIN_COLUMN.into());
338    types.push(Some(uqa_sql::ast::ColumnType::Xid));
339    let schema = RowSchema::with_qualified_types(target_qualifier, columns.clone(), types)
340        .with_column_collations(
341            (0..columns.len()).map(|position| target.column_collation(position)),
342        );
343    let schema = returning_schema_for_target(schema, composite_width, aliases);
344    let current_values = returning_image_values(services, Some(current), &columns, &definitions)?;
345    let old_values = returning_image_values(services, images.old.as_ref(), &columns, &definitions)?;
346    let new_values = returning_image_values(services, images.new.as_ref(), &columns, &definitions)?;
347    let values = current_values
348        .into_iter()
349        .chain(old_values)
350        .chain(new_values)
351        .collect();
352    Ok(OwnedPhysicalRow::new(
353        schema,
354        PhysicalRow::from_values(values),
355    ))
356}