Skip to main content

uqa_sql/semantics/
returning.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! RETURNING target schemas, alias visibility, projection expansion, and static analysis.
8use 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    /// Lend the current row declaration without evaluating defaults or generated expressions.
25    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    /// Visit declared names without resolving DEFAULT or generated expressions. Native catalogs lend an immutable declaration generation without copying its payloads.
43    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}
59/// Capture names and types from an active scope without exposing execution state.
60pub 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
156/// All RETURNING consumers expand target and image wildcards from the declared user columns. System columns remain individually addressable but are never wildcard outputs.
157fn 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
368/// The identity the `id` field of a document without declared columns names, as the document API addresses it: any nonnegative integer.
369pub 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}