1use 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
36pub 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}