1use super::returning_expression_schema;
9use crate::{
10 ast::{ColumnDef, ReturningAliases, Statement},
11 binding::snapshot::BindingSnapshot,
12 plan::{AggregateClassifier, ProjectionPlan},
13 routines::RoutineResolution,
14 ResultRow as Document, RowSchema, SQLError, SQLParam,
15};
16use std::{borrow::Cow, collections::BTreeSet};
17use uqa_core::{DocId, Value};
18
19#[cfg(test)]
20mod tests;
21
22pub trait ReturningCatalog {
23 fn try_describe_table_row_type(&self, table: &str) -> Result<Option<Vec<ColumnDef>>, String>;
24 fn with_table_row_type_with_control(
26 &self,
27 table: &str,
28 control: &uqa_core::memory::ProductionControl<'_>,
29 read: &mut dyn FnMut(&[ColumnDef]) -> Result<(), SQLError>,
30 ) -> Result<bool, SQLError> {
31 control.check()?;
32 let Some(columns) = self
33 .try_describe_table_row_type(table)
34 .map_err(SQLError::Internal)?
35 else {
36 return Ok(false);
37 };
38 read(&columns)?;
39 Ok(true)
40 }
41 fn try_table_columns(&self, table: &str) -> Result<Vec<String>, String>;
42 fn visit_column_names_with_control(
44 &self,
45 table: &str,
46 control: &uqa_core::memory::ProductionControl<'_>,
47 read: &mut dyn FnMut(&str) -> Result<(), SQLError>,
48 ) -> Result<(), SQLError> {
49 control.check()?;
50 let names = self.try_table_columns(table).map_err(SQLError::Internal)?;
51 for name in &names {
52 control.check()?;
53 read(name)?;
54 }
55 Ok(())
56 }
57 fn view_schema(&self, table: &str) -> Result<Option<RowSchema>, SQLError>;
58}
59pub trait ReturningScope {
61 fn binding_snapshot(&self) -> Result<BindingSnapshot, SQLError>;
62}
63#[derive(Clone, Copy)]
64pub struct ReturningAnalysisContext<'a> {
65 pub catalog: &'a dyn ReturningCatalog,
66 pub routines: &'a dyn RoutineResolution,
67 pub aggregates: &'a dyn AggregateClassifier,
68 pub scope: &'a dyn ReturningScope,
69}
70fn dml_storage_error(action: &str, error: impl std::fmt::Display) -> SQLError {
71 SQLError::Internal(format!("{action} failed in storage backend: {error}"))
72}
73
74pub fn returning_target_schema(
75 catalog: &dyn ReturningCatalog,
76 table: &str,
77) -> Result<RowSchema, SQLError> {
78 let definitions = catalog
79 .try_describe_table_row_type(table)
80 .map_err(|error| dml_storage_error("RETURNING schema lookup", error))?;
81 let Some(definitions) = definitions else {
82 return catalog
83 .view_schema(table)?
84 .ok_or_else(|| SQLError::UnknownTable(table.to_string()));
85 };
86 if definitions.is_empty() {
87 let columns = catalog
88 .try_table_columns(table)
89 .map_err(|error| dml_storage_error("RETURNING schema lookup", error))?;
90 let width = columns.len();
91 return Ok(RowSchema::with_types(columns, vec![None; width]));
92 }
93 Ok(RowSchema::with_column_metadata(
94 None,
95 definitions
96 .into_iter()
97 .map(|column| (column.name, Some(column.ty), column.collation_oid)),
98 ))
99}
100
101pub fn expanded_returning_projections(
102 catalog: &dyn ReturningCatalog,
103 table: &str,
104 target_qualifier: &str,
105 aliases: &ReturningAliases,
106 returning: &[ProjectionPlan],
107) -> Result<Vec<ProjectionPlan>, SQLError> {
108 let target = returning_target_schema(catalog, table)?;
109 expand_returning_target_stars(target.columns(), target_qualifier, aliases, returning, true)
110 .map(|projections| projections.into_iter().map(Cow::into_owned).collect())
111}
112
113pub(crate) fn command_returning_projections<'a>(
114 command: &'a crate::plan::CommandPlan,
115 target: &RowSchema,
116) -> Result<Vec<Cow<'a, ProjectionPlan>>, SQLError> {
117 let aliases = command
118 .returning_aliases()
119 .ok_or_else(|| SQLError::Internal("command has no RETURNING namespace".into()))?;
120 expand_returning_target_stars(
121 target.columns(),
122 command.target_qualifier().unwrap_or_default(),
123 aliases,
124 command.returning().unwrap_or_default(),
125 !matches!(command, crate::plan::CommandPlan::Merge(_)),
126 )
127}
128
129pub(crate) fn command_returning_star_schema(
130 command: &crate::plan::CommandPlan,
131 target: &RowSchema,
132 source: Option<&RowSchema>,
133) -> Result<RowSchema, SQLError> {
134 if matches!(command, crate::plan::CommandPlan::Merge(_)) {
135 let source = source
136 .ok_or_else(|| SQLError::Internal("MERGE has no declared source scope".into()))?;
137 Ok(RowSchema::join(source, target, std::iter::empty()))
138 } else {
139 Ok(target.clone())
140 }
141}
142
143pub(crate) fn validate_returning_width(
144 returning: &[ProjectionPlan],
145 width: usize,
146) -> Result<(), SQLError> {
147 if !returning.is_empty() && width == 0 {
148 return Err(SQLError::Routine {
149 sqlstate: "42601".into(),
150 message: "RETURNING must have at least one column".into(),
151 });
152 }
153 Ok(())
154}
155
156fn expand_returning_target_stars<'a>(
158 columns: &[String],
159 target_qualifier: &str,
160 aliases: &ReturningAliases,
161 returning: &'a [ProjectionPlan],
162 expand_bare_star: bool,
163) -> Result<Vec<Cow<'a, ProjectionPlan>>, SQLError> {
164 let mut projections = Vec::with_capacity(returning.len().max(columns.len()));
165 for projection in returning {
166 match &projection.expr {
167 crate::ScalarExpr::Star if expand_bare_star => {
168 projections.extend(columns.iter().map(|column| {
169 Cow::Owned(ProjectionPlan {
170 expr: crate::ScalarExpr::qualified_column(target_qualifier, column),
171 alias: Some(column.clone()),
172 })
173 }));
174 }
175 crate::ScalarExpr::QualifiedStar(qualifier)
176 if qualifier == target_qualifier
177 || qualifier == &aliases.old
178 || qualifier == &aliases.new =>
179 {
180 projections.extend(columns.iter().map(|column| {
181 Cow::Owned(ProjectionPlan {
182 expr: crate::ScalarExpr::qualified_column(qualifier, column),
183 alias: Some(column.clone()),
184 })
185 }));
186 }
187 _ => projections.push(Cow::Borrowed(projection)),
188 }
189 }
190 validate_returning_width(returning, projections.len())?;
191 Ok(projections)
192}
193
194pub fn dml_statement_returning_schema(
195 context: ReturningAnalysisContext<'_>,
196 statement: Statement,
197) -> Result<Option<RowSchema>, SQLError> {
198 let plan = crate::plan::UnifiedPlan::lower_with(statement, context.aggregates);
199 let crate::plan::UnifiedPlan::Command(command) = plan else {
200 return Ok(None);
201 };
202 dml_command_returning_schema(context, &command, &[])
203}
204
205pub fn dml_command_returning_schema(
206 context: ReturningAnalysisContext<'_>,
207 command: &crate::plan::CommandPlan,
208 params: &[SQLParam],
209) -> Result<Option<RowSchema>, SQLError> {
210 match command {
211 crate::plan::CommandPlan::Insert(plan) => analyze_dml_returning_plan(
212 context,
213 &plan.table,
214 &plan.target_qualifier,
215 &plan.returning_aliases,
216 &plan.returning,
217 &plan.ctes,
218 None,
219 &plan.subqueries,
220 params,
221 ),
222 crate::plan::CommandPlan::Update(plan) => analyze_dml_returning_plan(
223 context,
224 &plan.table,
225 &plan.target_qualifier,
226 &plan.returning_aliases,
227 &plan.returning,
228 &plan.ctes,
229 plan.source.as_deref(),
230 &plan.subqueries,
231 params,
232 ),
233 crate::plan::CommandPlan::Delete(plan) => analyze_dml_returning_plan(
234 context,
235 &plan.table,
236 &plan.target_qualifier,
237 &plan.returning_aliases,
238 &plan.returning,
239 &plan.ctes,
240 plan.source.as_deref(),
241 &plan.subqueries,
242 params,
243 ),
244 _ => Ok(None),
245 }
246}
247
248pub fn validate_insert_returning(
249 context: ReturningAnalysisContext<'_>,
250 plan: &crate::plan::InsertPlan,
251 params: &[SQLParam],
252 inherited: Option<&dyn ReturningScope>,
253) -> Result<(), SQLError> {
254 if plan.returning.is_empty() {
255 return Ok(());
256 }
257 let target = returning_target_schema(context.catalog, &plan.table)?;
258 if plan.source.is_none() {
259 let width = if plan.columns.is_empty() {
260 target.len()
261 } else {
262 plan.columns.len()
263 };
264 for row in &plan.rows {
265 if row.len() > width || (!plan.columns.is_empty() && row.len() < width) {
266 return Err(SQLError::Routine {
267 sqlstate: "42601".into(),
268 message: if row.len() > width {
269 "INSERT has more expressions than target columns"
270 } else {
271 "INSERT has more target columns than expressions"
272 }
273 .into(),
274 });
275 }
276 }
277 }
278 let mut scope = inherited.unwrap_or(context.scope).binding_snapshot()?;
279 for cte in &plan.ctes {
280 scope.insert_deferred(cte.clone());
281 }
282 scope.scalar_subqueries = plan.subqueries.as_slice().into();
283 let expressions = returning_expression_schema(
284 &target,
285 &plan.target_qualifier,
286 &plan.returning_aliases,
287 None,
288 );
289 let projections = expanded_returning_projections(
290 context.catalog,
291 &plan.table,
292 &plan.target_qualifier,
293 &plan.returning_aliases,
294 &plan.returning,
295 )?;
296 crate::binding::analyze_projection_output_schema(
297 context.routines,
298 &projections,
299 &expressions,
300 &target,
301 &plan.subqueries,
302 params,
303 &scope.context(),
304 )?;
305 Ok(())
306}
307
308#[expect(
309 clippy::too_many_arguments,
310 reason = "keeps RETURNING row types and nested scopes explicit"
311)]
312pub fn analyze_dml_returning_plan(
313 context: ReturningAnalysisContext<'_>,
314 table: &str,
315 target_qualifier: &str,
316 aliases: &ReturningAliases,
317 returning: &[ProjectionPlan],
318 cte_plans: &[crate::plan::CtePlan],
319 source: Option<&crate::plan::SourcePlan>,
320 subqueries: &[crate::plan::QueryPlan],
321 params: &[SQLParam],
322) -> Result<Option<RowSchema>, SQLError> {
323 if returning.is_empty() {
324 return Ok(None);
325 }
326 let mut ctes = context.scope.binding_snapshot()?;
327 for plan in cte_plans {
328 ctes.insert_deferred(plan.clone());
329 }
330 ctes.scalar_subqueries = subqueries.into();
331 let supplemental = source
332 .map(|source| {
333 crate::binding::analyze_source_plan_schema(
334 context.routines,
335 source,
336 params,
337 &ctes.context(),
338 None,
339 )
340 })
341 .transpose()?;
342 let star_schema = returning_target_schema(context.catalog, table)?;
343 let expression_schema = returning_expression_schema(
344 &star_schema,
345 target_qualifier,
346 aliases,
347 supplemental.as_ref(),
348 );
349 let projections = expanded_returning_projections(
350 context.catalog,
351 table,
352 target_qualifier,
353 aliases,
354 returning,
355 )?;
356 crate::binding::analyze_projection_output_schema(
357 context.routines,
358 &projections,
359 &expression_schema,
360 &star_schema,
361 subqueries,
362 params,
363 &ctes.context(),
364 )
365 .map(Some)
366}
367
368pub fn document_supplied_id(document: &Document, id_column: &str) -> Option<DocId> {
370 match document.get(id_column) {
371 Some(Value::Int(value)) => DocId::try_from(*value).ok(),
372 _ => None,
373 }
374}
375
376pub fn validate_returning_alias_relations(
377 target_qualifier: &str,
378 aliases: &ReturningAliases,
379 supplemental: Option<&RowSchema>,
380) -> Result<(), SQLError> {
381 let mut relation_names = BTreeSet::from([target_qualifier]);
382 for (alias, explicit) in [
383 (aliases.old.as_str(), aliases.old_explicit),
384 (aliases.new.as_str(), aliases.new_explicit),
385 ] {
386 if !explicit {
387 continue;
388 }
389 if relation_names.contains(alias)
390 || supplemental.is_some_and(|schema| schema.has_qualifier(alias))
391 {
392 return Err(SQLError::Routine {
393 sqlstate: "42712".into(),
394 message: format!("table name \"{alias}\" specified more than once"),
395 });
396 }
397 relation_names.insert(alias);
398 }
399 Ok(())
400}