Skip to main content

uqa_sql/binding/
commands.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Static RETURNING schemas for command CTEs.
8
9use super::{
10    projection_star_columns, ColumnType, RowSchema, SQLError, SQLParam, ScalarExpr, SchemaScope,
11    SourcePlan,
12};
13use crate::plan::{CommandPlan, CtePlanBody};
14use crate::routines::RoutineResolution;
15
16pub fn analyze_prepared_command_schema(
17    routines: &dyn RoutineResolution,
18    command: &CommandPlan,
19    params: &[SQLParam],
20    ctes: &super::BindingContext,
21) -> Result<Option<RowSchema>, SQLError> {
22    if let CommandPlan::Explain { options, .. } = command {
23        return options.result_schema().map(Some);
24    }
25    if command.mutation_target().is_none() {
26        return Ok(None);
27    }
28    let mut scope = SchemaScope::for_analysis(ctes)?;
29    scope.set_command_lookup_mode(command);
30    let previous = scope.bind_cte_schemas(routines, command.ctes(), params, None)?;
31    let result = (|| {
32        let (target, expression, _) =
33            scope.command_expression_schema(routines, command, params, None)?;
34        let excluded = RowSchema::with_relation_qualifier(&target, "excluded");
35        let conflict_input = RowSchema::join(&expression, &excluded, std::iter::empty::<String>());
36        let conflict_expressions = match command {
37            CommandPlan::Insert(insert) => insert
38                .on_conflict
39                .as_ref()
40                .map(|conflict| match &conflict.action {
41                    crate::plan::ConflictActionPlan::Update {
42                        assignments,
43                        predicate,
44                    } => assignments
45                        .iter()
46                        .flat_map(crate::plan::AssignmentPlan::expressions)
47                        .chain(predicate.as_deref())
48                        .collect::<Vec<_>>(),
49                    crate::plan::ConflictActionPlan::Nothing => Vec::new(),
50                })
51                .unwrap_or_default(),
52            _ => Vec::new(),
53        };
54        if let CommandPlan::Insert(insert) = command {
55            if let Some(source) = &insert.source {
56                scope.bind_query(routines, source, params, None)?;
57            }
58        }
59        for scalar in command.expressions() {
60            if matches!(command, CommandPlan::Merge(_)) {
61                continue;
62            }
63            scope.bind_expression_type(
64                routines,
65                scalar,
66                if conflict_expressions
67                    .iter()
68                    .any(|candidate| std::ptr::eq(*candidate, scalar))
69                {
70                    &conflict_input
71                } else {
72                    &expression
73                },
74                command.scalar_subqueries(),
75                params,
76            )?;
77        }
78        if let CommandPlan::Merge(merge) = command {
79            scope.bind_merge_expressions(routines, merge, params, &target, &expression)?;
80        }
81        let result = scope.bind_command_returning(routines, command, params)?;
82        Ok(command
83            .returning()
84            .filter(|returning| !returning.is_empty())
85            .map(|_| result))
86    })();
87    scope.restore_cte_schemas(previous);
88    result
89}
90
91impl SchemaScope {
92    pub(super) fn set_command_lookup_mode(&mut self, command: &CommandPlan) {
93        let bound = match command {
94            CommandPlan::Insert(plan) => plan.relations_bound,
95            CommandPlan::Update(plan) => plan.relations_bound,
96            CommandPlan::Delete(plan) => plan.relations_bound,
97            _ => false,
98        };
99        self.resolution.set_lookup_mode(if bound {
100            crate::catalog::resolution::RelationLookupMode::Bound
101        } else {
102            crate::catalog::resolution::RelationLookupMode::Dynamic
103        });
104    }
105
106    pub(super) fn bind_cte_body(
107        &mut self,
108        routines: &dyn RoutineResolution,
109        body: &CtePlanBody,
110        params: &[SQLParam],
111        outer: Option<&RowSchema>,
112    ) -> Result<RowSchema, SQLError> {
113        match body {
114            CtePlanBody::Query(query) => self.bind_query(routines, query, params, outer),
115            CtePlanBody::Command(command) => self.bind_command_returning(routines, command, params),
116        }
117    }
118
119    pub(super) fn bind_command_target(
120        &mut self,
121        routines: &dyn RoutineResolution,
122        command: &CommandPlan,
123        params: &[SQLParam],
124    ) -> Result<RowSchema, SQLError> {
125        let table = command
126            .mutation_target()
127            .ok_or_else(|| SQLError::Internal("non-DML command in a WITH definition".into()))?;
128        let source = SourcePlan::Table {
129            executable_query: None,
130            bound_columns: None,
131            name: table.to_string(),
132            qualifier: command.target_qualifier().unwrap_or(table).to_string(),
133            alias: None,
134            column_aliases: Vec::new(),
135            include_descendants: true,
136        };
137        // A mutation target always denotes a catalog relation, even when a CTE shadows its name.
138        let previous = std::mem::take(&mut self.ctes);
139        let deferred = std::mem::take(&mut self.deferred_ctes);
140        let bound = match command {
141            CommandPlan::Insert(plan) => plan.target_relation_bound,
142            CommandPlan::Update(plan) => plan.target_relation_bound,
143            CommandPlan::Delete(plan) => plan.target_relation_bound,
144            _ => false,
145        };
146        let lookup = bound.then(|| {
147            self.resolution
148                .set_lookup_mode(crate::catalog::resolution::RelationLookupMode::Bound)
149        });
150        let result = self.bind_source(routines, &source, &[], params, None);
151        if let Some(lookup) = lookup {
152            self.resolution.set_lookup_mode(lookup);
153        }
154        self.ctes = previous;
155        self.deferred_ctes = deferred;
156        let target = result?;
157        let columns = target
158            .columns()
159            .iter()
160            .enumerate()
161            .map(|(position, column)| target.public_name(position).unwrap_or(column).to_string())
162            .collect();
163        let schema = RowSchema::with_types(columns, target.column_types().to_vec())
164            .with_column_collations(
165                (0..target.len()).map(|position| target.column_collation(position)),
166            );
167        Ok(if target.columns_are_open(None) {
168            RowSchema::with_open_columns(&schema, None)
169        } else {
170            schema
171        })
172    }
173
174    pub(super) fn command_expression_schema(
175        &mut self,
176        routines: &dyn RoutineResolution,
177        command: &CommandPlan,
178        params: &[SQLParam],
179        outer: Option<&RowSchema>,
180    ) -> Result<(RowSchema, RowSchema, RowSchema), SQLError> {
181        let target = self.bind_command_target(routines, command, params)?;
182        let preceding = super::SourceScope::command_target(command, &target);
183        let source = command
184            .source_input()
185            .map(|source| {
186                self.bind_source_in_scope(
187                    routines,
188                    source,
189                    command.scalar_subqueries(),
190                    params,
191                    super::SourceScope {
192                        outer,
193                        preceding: preceding.as_ref(),
194                        inherited_lateral: false,
195                        retain_names: true,
196                    },
197                )
198            })
199            .transpose()?;
200        let expression = Self::command_input_schema(command, &target, source.as_ref())?;
201        let star = crate::semantics::returning::command_returning_star_schema(
202            command,
203            &target,
204            source.as_ref(),
205        )?;
206        Ok((target, expression, star))
207    }
208
209    pub(super) fn command_input_schema(
210        command: &CommandPlan,
211        target: &RowSchema,
212        source: Option<&RowSchema>,
213    ) -> Result<RowSchema, SQLError> {
214        let aliases = command
215            .returning_aliases()
216            .ok_or_else(|| SQLError::Internal("command CTE has no RETURNING namespace".into()))?;
217        let mut expression = crate::semantics::returning_expression_schema(
218            target,
219            command.target_qualifier().unwrap_or_default(),
220            aliases,
221            source,
222        );
223        if target.columns_are_open(None) {
224            expression = RowSchema::with_open_columns(&expression, command.target_qualifier());
225        }
226        Ok(expression)
227    }
228
229    pub(super) fn bind_command_returning(
230        &mut self,
231        routines: &dyn RoutineResolution,
232        command: &CommandPlan,
233        params: &[SQLParam],
234    ) -> Result<RowSchema, SQLError> {
235        let previous = self.bind_cte_schemas(routines, command.ctes(), params, None)?;
236        let result = (|| {
237            let (target, expression, star) =
238                self.command_expression_schema(routines, command, params, None)?;
239            if let CommandPlan::Insert(insert) = command {
240                if let Some(source) = &insert.source {
241                    self.bind_query(routines, source, params, None)?;
242                }
243            }
244            let returning =
245                crate::semantics::returning::command_returning_projections(command, &target)?;
246            let mut columns = Vec::new();
247            let mut types: Vec<Option<ColumnType>> = Vec::new();
248            let mut records = Vec::new();
249            let mut collations = super::projection::OutputCollations::default();
250            for projection in &returning {
251                let expansion = if matches!(projection.expr, ScalarExpr::QualifiedStar(_)) {
252                    &expression
253                } else {
254                    &star
255                };
256                if let Some(star) = projection_star_columns(&projection.expr, expansion)? {
257                    records.extend(
258                        super::record_fields::star_metadata(&projection.expr, expansion)
259                            .unwrap_or_default(),
260                    );
261                    for (column, ty, collation) in star {
262                        collations.push(types.len(), ty.as_ref(), collation);
263                        columns.push(column);
264                        types.push(ty);
265                    }
266                } else {
267                    columns.push(crate::semantics::projection_label_at(projection));
268                    let metadata = self.bind_projection_metadata(
269                        routines,
270                        &projection.expr,
271                        &expression,
272                        command.scalar_subqueries(),
273                        params,
274                    )?;
275                    collations.push(types.len(), metadata.ty.as_ref(), metadata.collation);
276                    types.push(metadata.ty);
277                    records.push(metadata.record);
278                }
279            }
280            crate::semantics::returning::validate_returning_width(
281                command.returning().unwrap_or_default(),
282                columns.len(),
283            )?;
284            if let Some(error) = crate::semantics::virtual_relation_mutation_error(
285                self.catalog.as_ref(),
286                &self.resolution,
287                command,
288            )? {
289                return Err(error);
290            }
291            for projection in &returning {
292                self.collations.validate_expression(&projection.expr)?;
293            }
294            Ok(collations
295                .apply(RowSchema::with_types(columns, types))
296                .with_record_metadata(
297                    records
298                        .into_iter()
299                        .enumerate()
300                        .filter_map(|(index, record)| record.map(|record| (index, record))),
301                ))
302        })();
303        self.restore_cte_schemas(previous);
304        result
305    }
306}