Skip to main content

uqa_sql/semantics/rules/
returning.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Rule RETURNING image requirements, positional contracts, and action rewriting.
8use crate::{
9    ast::{Expr, Projection, ReturningAliases, RuleEvent, Statement},
10    plan::{ProjectionPlan, QueryPlan, RelationalPlan, SourcePlan},
11    plpgsql::{ResolvedVariable, VariableResolver},
12    SQLError, ScalarExpr,
13};
14use std::collections::BTreeSet;
15use uqa_core::Value;
16#[derive(Clone, Copy, Default)]
17pub struct RuleReturningRequest {
18    capture: bool,
19    images: RuleReturningImages,
20}
21
22#[derive(Clone, Copy, Default)]
23struct RuleReturningImages(u8);
24
25impl RuleReturningImages {
26    const CURRENT: Self = Self(1 << 0);
27    const OLD: Self = Self(1 << 1);
28    const NEW: Self = Self(1 << 2);
29
30    fn insert(&mut self, image: Self) {
31        self.0 |= image.0;
32    }
33
34    const fn contains(self, image: Self) -> bool {
35        self.0 & image.0 != 0
36    }
37}
38
39impl RuleReturningRequest {
40    pub fn from_plan(
41        returning: &[ProjectionPlan],
42        aliases: &ReturningAliases,
43        subqueries: &[QueryPlan],
44    ) -> Self {
45        if returning.is_empty() {
46            return Self::default();
47        }
48        let mut request = Self {
49            capture: true,
50            ..Self::default()
51        };
52        let shadowed = BTreeSet::new();
53        for projection in returning {
54            let ids = request.inspect_expression(&projection.expr, aliases, &shadowed);
55            for id in ids {
56                if let Some(query) = subqueries.get(id) {
57                    request.inspect_query(query, aliases, &shadowed);
58                }
59            }
60        }
61        request
62    }
63
64    fn inspect_expression(
65        &mut self,
66        expression: &ScalarExpr,
67        aliases: &ReturningAliases,
68        shadowed: &BTreeSet<String>,
69    ) -> Vec<usize> {
70        let mut expression = expression.clone();
71        let mut subqueries = Vec::new();
72        crate::plan::rewrite_scalar_expression(&mut expression, &mut |node| match node {
73            ScalarExpr::Star | ScalarExpr::Column(_) | ScalarExpr::Position(_) => {
74                self.images.insert(RuleReturningImages::CURRENT);
75            }
76            ScalarExpr::QualifiedStar(_) | ScalarExpr::QualifiedColumn { .. } => {
77                let qualifier = node.reference_qualifier().expect("qualified reference");
78                if shadowed.contains(&qualifier.to_ascii_lowercase()) {
79                    return;
80                }
81                if qualifier.eq_ignore_ascii_case(&aliases.old) {
82                    self.images.insert(RuleReturningImages::OLD);
83                } else if qualifier.eq_ignore_ascii_case(&aliases.new) {
84                    self.images.insert(RuleReturningImages::NEW);
85                } else {
86                    self.images.insert(RuleReturningImages::CURRENT);
87                }
88            }
89            ScalarExpr::ScalarSubquery(id)
90            | ScalarExpr::Exists { subquery: id, .. }
91            | ScalarExpr::InSubquery { subquery: id, .. } => subqueries.push(*id),
92            _ => {}
93        });
94        subqueries
95    }
96
97    fn inspect_cte_body(
98        &mut self,
99        body: &crate::plan::CtePlanBody,
100        aliases: &ReturningAliases,
101        inherited: &BTreeSet<String>,
102    ) {
103        match body {
104            crate::plan::CtePlanBody::Query(query) => self.inspect_query(query, aliases, inherited),
105            crate::plan::CtePlanBody::Command(command) => {
106                let mut scope = inherited.clone();
107                if let Some(qualifier) = command.target_qualifier() {
108                    scope.insert(qualifier.to_ascii_lowercase());
109                }
110                if let Some(source) = command.source_input() {
111                    collect_source_qualifiers(source, &mut scope);
112                    self.inspect_source(source, aliases, inherited);
113                }
114                if let Some(aliases) = command.returning_aliases() {
115                    scope.insert(aliases.old.to_ascii_lowercase());
116                    scope.insert(aliases.new.to_ascii_lowercase());
117                }
118                for cte in command.ctes() {
119                    self.inspect_cte_body(&cte.body, aliases, &scope);
120                }
121                for query in command.query_inputs() {
122                    self.inspect_query(query, aliases, &scope);
123                }
124                for expression in command.expressions() {
125                    let _ = self.inspect_expression(expression, aliases, &scope);
126                }
127            }
128        }
129    }
130
131    fn inspect_query(
132        &mut self,
133        query: &QueryPlan,
134        aliases: &ReturningAliases,
135        inherited: &BTreeSet<String>,
136    ) {
137        for cte in &query.ctes {
138            self.inspect_cte_body(&cte.body, aliases, inherited);
139        }
140        match &query.root {
141            RelationalPlan::QueryBlock(block) => {
142                let mut scope = inherited.clone();
143                if let Some(source) = &block.from {
144                    collect_source_qualifiers(source, &mut scope);
145                    self.inspect_source(source, aliases, inherited);
146                }
147                for expression in block
148                    .projections
149                    .iter()
150                    .map(|projection| &projection.expr)
151                    .chain(block.r#where.iter())
152                    .chain(block.group_by.iter())
153                    .chain(block.grouping_sets.iter().flatten())
154                    .chain(block.having.iter())
155                    .chain(block.order_by.iter().map(|order| &order.expr))
156                    .chain(block.limit.iter())
157                    .chain(block.offset.iter())
158                    .chain(block.distinct_on.iter())
159                {
160                    let _ = self.inspect_expression(expression, aliases, &scope);
161                }
162                for subquery in &block.subqueries {
163                    self.inspect_query(subquery, aliases, &scope);
164                }
165            }
166            RelationalPlan::SetOp {
167                left,
168                right,
169                order_by,
170                limit,
171                offset,
172                subqueries,
173                ..
174            } => {
175                self.inspect_query(left, aliases, inherited);
176                self.inspect_query(right, aliases, inherited);
177                for expression in order_by
178                    .iter()
179                    .map(|order| &order.expr)
180                    .chain(limit.iter().map(Box::as_ref))
181                    .chain(offset.iter().map(Box::as_ref))
182                {
183                    let _ = self.inspect_expression(expression, aliases, inherited);
184                }
185                for subquery in subqueries {
186                    self.inspect_query(subquery, aliases, inherited);
187                }
188            }
189            RelationalPlan::Values { rows, subqueries } => {
190                for expression in rows.iter().flatten() {
191                    let _ = self.inspect_expression(expression, aliases, inherited);
192                }
193                for subquery in subqueries {
194                    self.inspect_query(subquery, aliases, inherited);
195                }
196            }
197        }
198    }
199
200    fn inspect_source(
201        &mut self,
202        source: &SourcePlan,
203        aliases: &ReturningAliases,
204        inherited: &BTreeSet<String>,
205    ) {
206        match source {
207            crate::plan::SourcePlan::RetainedRows(_) => {}
208            SourcePlan::Table { .. } => {}
209            SourcePlan::Join {
210                left,
211                right,
212                on,
213                lateral,
214                ..
215            } => {
216                self.inspect_source(left, aliases, inherited);
217                let mut right_scope = inherited.clone();
218                if *lateral {
219                    collect_source_qualifiers(left, &mut right_scope);
220                }
221                self.inspect_source(right, aliases, &right_scope);
222                if let Some(on) = on {
223                    let mut scope = inherited.clone();
224                    collect_source_qualifiers(left, &mut scope);
225                    collect_source_qualifiers(right, &mut scope);
226                    let _ = self.inspect_expression(on, aliases, &scope);
227                }
228            }
229            SourcePlan::Values { rows, .. } => {
230                for expression in rows.iter().flatten() {
231                    let _ = self.inspect_expression(expression, aliases, inherited);
232                }
233            }
234            SourcePlan::Function { args, .. } => {
235                for expression in args {
236                    let _ = self.inspect_expression(expression, aliases, inherited);
237                }
238            }
239            SourcePlan::FunctionGroup { functions, .. } => {
240                for expression in functions.iter().flat_map(|function| &function.args) {
241                    let _ = self.inspect_expression(expression, aliases, inherited);
242                }
243            }
244            SourcePlan::Subquery { body, .. } => self.inspect_query(body, aliases, inherited),
245        }
246    }
247
248    pub const fn captures(self) -> bool {
249        self.capture
250    }
251}
252
253fn collect_source_qualifiers(source: &SourcePlan, output: &mut BTreeSet<String>) {
254    match source {
255        SourcePlan::Join {
256            left, right, alias, ..
257        } => {
258            if let Some(alias) = alias {
259                output.insert(alias.to_ascii_lowercase());
260            } else {
261                collect_source_qualifiers(left, output);
262                collect_source_qualifiers(right, output);
263            }
264        }
265        _ => {
266            if let Some(qualifier) = source.visible_qualifier() {
267                output.insert(qualifier.to_ascii_lowercase());
268            }
269        }
270    }
271}
272
273pub fn validate_rule_returning_provider_width(
274    provider_width: usize,
275    event_width: usize,
276) -> Result<(), SQLError> {
277    if provider_width < event_width {
278        return Err(SQLError::Internal(format!(
279            "could not find replacement targetlist entry for attno {}",
280            provider_width + 1
281        )));
282    }
283    if provider_width > event_width {
284        return Err(SQLError::Internal(format!(
285            "rewrite-rule RETURNING provider produced {provider_width} columns, expected {event_width}"
286        )));
287    }
288    Ok(())
289}
290
291/// Describe the stored action in its event namespace, before unevaluated caller inputs replace OLD and NEW. Stored stars keep their creation-time width.
292pub fn rule_action_returning_schema(
293    sources: &dyn super::action_binding::RuleSourceCatalog,
294    context: crate::semantics::returning::ReturningAnalysisContext<'_>,
295    action: &Statement,
296    event: RuleEvent,
297    columns: &[crate::ast::ColumnDef],
298) -> Result<crate::RowSchema, SQLError> {
299    let action_columns = super::action_binding::rule_action_target_columns(sources, action)?;
300    let mut resolver =
301        crate::catalog::events::validation::RuleRowTypeResolver::for_action(columns, event);
302    let bound =
303        super::action_binding::bind_rule_action(sources, action, &action_columns, &mut resolver)?;
304    crate::semantics::returning::dml_statement_returning_schema(context, bound)?
305        .ok_or_else(|| SQLError::Internal("rule action lost its RETURNING descriptor".into()))
306}
307
308pub fn augment_rule_returning_action(
309    statement: &mut Statement,
310    source_index: Option<Expr>,
311    event_width: usize,
312    request: RuleReturningRequest,
313    target_columns: &BTreeSet<String>,
314) -> Result<(), SQLError> {
315    let (target_qualifier, aliases, returning) = match statement {
316        Statement::Insert(action) => (
317            action.target_qualifier.clone(),
318            action.returning_aliases.clone(),
319            action.returning.clone(),
320        ),
321        Statement::Update(action) => (
322            action.target_qualifier.clone(),
323            action.returning_aliases.clone(),
324            action.returning.clone(),
325        ),
326        Statement::Delete(action) => (
327            action.target_qualifier.clone(),
328            action.returning_aliases.clone(),
329            action.returning.clone(),
330        ),
331        _ => return Ok(()),
332    };
333    if returning.is_empty() {
334        return Ok(());
335    }
336    let mut target_columns = target_columns.clone();
337    target_columns.insert(crate::semantics::DOC_ID_COLUMN.into());
338    let provider_event = match statement {
339        Statement::Insert(_) => RuleEvent::Insert,
340        Statement::Update(_) => RuleEvent::Update,
341        Statement::Delete(_) => RuleEvent::Delete,
342        _ => unreachable!("validated rule provider changed statement kind"),
343    };
344    let current = if request.images.contains(RuleReturningImages::CURRENT) {
345        returning.clone()
346    } else {
347        null_rule_returning_image(event_width)
348    };
349    let old = if request.images.contains(RuleReturningImages::OLD)
350        && provider_event != RuleEvent::Insert
351    {
352        rewrite_rule_returning_image(
353            &returning,
354            &target_qualifier,
355            &target_columns,
356            &aliases.old,
357            &aliases.new,
358            &aliases.old,
359        )?
360    } else {
361        null_rule_returning_image(event_width)
362    };
363    let new = if request.images.contains(RuleReturningImages::NEW)
364        && provider_event != RuleEvent::Delete
365    {
366        rewrite_rule_returning_image(
367            &returning,
368            &target_qualifier,
369            &target_columns,
370            &aliases.old,
371            &aliases.new,
372            &aliases.new,
373        )?
374    } else {
375        null_rule_returning_image(event_width)
376    };
377    let output = match statement {
378        Statement::Insert(action) => &mut action.returning,
379        Statement::Update(action) => &mut action.returning,
380        Statement::Delete(action) => &mut action.returning,
381        _ => unreachable!("validated rule provider changed statement kind"),
382    };
383    *output = current;
384    output.extend(old);
385    output.extend(new);
386    if let Some(expr) = source_index {
387        output.push(Projection { expr, alias: None });
388    }
389    Ok(())
390}
391
392fn null_rule_returning_image(width: usize) -> Vec<Projection> {
393    (0..width)
394        .map(|_| Projection {
395            expr: Expr::Literal(Value::Null),
396            alias: None,
397        })
398        .collect()
399}
400
401fn rewrite_rule_returning_image(
402    returning: &[Projection],
403    target_qualifier: &str,
404    target_columns: &BTreeSet<String>,
405    old_qualifier: &str,
406    new_qualifier: &str,
407    image_qualifier: &str,
408) -> Result<Vec<Projection>, SQLError> {
409    let mut resolver = ReturningImageResolver {
410        target_qualifier,
411        target_columns,
412        old_qualifier,
413        new_qualifier,
414        image_qualifier,
415    };
416    returning
417        .iter()
418        .map(|projection| {
419            let expr = match &projection.expr {
420                Expr::Star => Expr::QualifiedStar(image_qualifier.to_string().into()),
421                Expr::QualifiedStar(qualifier) if resolver.retargets_qualifier(qualifier) => {
422                    Expr::QualifiedStar(
423                        crate::ast::ReferenceName::from(image_qualifier)
424                            .with_position(qualifier.position()),
425                    )
426                }
427                expr => super::action_binding::bind_rule_expr_scoped(
428                    expr,
429                    &mut resolver,
430                    &BTreeSet::new(),
431                )?,
432            };
433            Ok(Projection {
434                expr,
435                alias: projection.alias.clone(),
436            })
437        })
438        .collect()
439}
440
441struct ReturningImageResolver<'a> {
442    target_qualifier: &'a str,
443    target_columns: &'a BTreeSet<String>,
444    old_qualifier: &'a str,
445    new_qualifier: &'a str,
446    image_qualifier: &'a str,
447}
448
449impl ReturningImageResolver<'_> {
450    fn retargets_qualifier(&self, qualifier: &str) -> bool {
451        qualifier.eq_ignore_ascii_case(self.target_qualifier)
452            || qualifier.eq_ignore_ascii_case(self.old_qualifier)
453            || qualifier.eq_ignore_ascii_case(self.new_qualifier)
454    }
455}
456
457impl VariableResolver for ReturningImageResolver<'_> {
458    fn resolve_name(&mut self, _name: &str) -> Result<Option<ResolvedVariable>, SQLError> {
459        Ok(None)
460    }
461
462    fn resolve_qualified(
463        &mut self,
464        _qualifier: &str,
465        _column: &str,
466    ) -> Result<Option<ResolvedVariable>, SQLError> {
467        Ok(None)
468    }
469
470    fn resolve_param(&mut self, _index: usize) -> Result<Option<ResolvedVariable>, SQLError> {
471        Ok(None)
472    }
473
474    fn rewrite_name(&mut self, name: &str) -> Result<Option<Expr>, SQLError> {
475        Ok(self
476            .target_columns
477            .contains(name)
478            .then(|| Expr::qualified_column(self.image_qualifier, name)))
479    }
480
481    fn rewrite_qualified(
482        &mut self,
483        qualifier: &str,
484        column: &str,
485    ) -> Result<Option<Expr>, SQLError> {
486        Ok(self
487            .retargets_qualifier(qualifier)
488            .then(|| Expr::qualified_column(self.image_qualifier, column)))
489    }
490}