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();
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}