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(qualifier)
77            | ScalarExpr::QualifiedColumn { qualifier, .. }
78                if !shadowed.contains(&qualifier.to_ascii_lowercase()) =>
79            {
80                if qualifier.eq_ignore_ascii_case(&aliases.old) {
81                    self.images.insert(RuleReturningImages::OLD);
82                } else if qualifier.eq_ignore_ascii_case(&aliases.new) {
83                    self.images.insert(RuleReturningImages::NEW);
84                } else {
85                    self.images.insert(RuleReturningImages::CURRENT);
86                }
87            }
88            ScalarExpr::ScalarSubquery(id)
89            | ScalarExpr::Exists { subquery: id, .. }
90            | ScalarExpr::InSubquery { subquery: id, .. } => subqueries.push(*id),
91            _ => {}
92        });
93        subqueries
94    }
95
96    fn inspect_cte_body(
97        &mut self,
98        body: &crate::plan::CtePlanBody,
99        aliases: &ReturningAliases,
100        inherited: &BTreeSet<String>,
101    ) {
102        match body {
103            crate::plan::CtePlanBody::Query(query) => self.inspect_query(query, aliases, inherited),
104            crate::plan::CtePlanBody::Command(command) => {
105                let mut scope = inherited.clone();
106                if let Some(qualifier) = command.target_qualifier() {
107                    scope.insert(qualifier.to_ascii_lowercase());
108                }
109                if let Some(source) = command.source_input() {
110                    collect_source_qualifiers(source, &mut scope);
111                    self.inspect_source(source, aliases, inherited);
112                }
113                if let Some(aliases) = command.returning_aliases() {
114                    scope.insert(aliases.old.to_ascii_lowercase());
115                    scope.insert(aliases.new.to_ascii_lowercase());
116                }
117                for cte in command.ctes() {
118                    self.inspect_cte_body(&cte.body, aliases, &scope);
119                }
120                for query in command.query_inputs() {
121                    self.inspect_query(query, aliases, &scope);
122                }
123                for expression in command.expressions() {
124                    let _ = self.inspect_expression(expression, aliases, &scope);
125                }
126            }
127        }
128    }
129
130    fn inspect_query(
131        &mut self,
132        query: &QueryPlan,
133        aliases: &ReturningAliases,
134        inherited: &BTreeSet<String>,
135    ) {
136        for cte in &query.ctes {
137            self.inspect_cte_body(&cte.body, aliases, inherited);
138        }
139        match &query.root {
140            RelationalPlan::QueryBlock(block) => {
141                let mut scope = inherited.clone();
142                if let Some(source) = &block.from {
143                    collect_source_qualifiers(source, &mut scope);
144                    self.inspect_source(source, aliases, inherited);
145                }
146                for expression in block
147                    .projections
148                    .iter()
149                    .map(|projection| &projection.expr)
150                    .chain(block.r#where.iter())
151                    .chain(block.group_by.iter())
152                    .chain(block.grouping_sets.iter().flatten())
153                    .chain(block.having.iter())
154                    .chain(block.order_by.iter().map(|order| &order.expr))
155                    .chain(block.limit.iter())
156                    .chain(block.offset.iter())
157                    .chain(block.distinct_on.iter())
158                {
159                    let _ = self.inspect_expression(expression, aliases, &scope);
160                }
161                for subquery in &block.subqueries {
162                    self.inspect_query(subquery, aliases, &scope);
163                }
164            }
165            RelationalPlan::SetOp {
166                left,
167                right,
168                order_by,
169                limit,
170                offset,
171                subqueries,
172                ..
173            } => {
174                self.inspect_query(left, aliases, inherited);
175                self.inspect_query(right, aliases, inherited);
176                for expression in order_by
177                    .iter()
178                    .map(|order| &order.expr)
179                    .chain(limit.iter().map(Box::as_ref))
180                    .chain(offset.iter().map(Box::as_ref))
181                {
182                    let _ = self.inspect_expression(expression, aliases, inherited);
183                }
184                for subquery in subqueries {
185                    self.inspect_query(subquery, aliases, inherited);
186                }
187            }
188            RelationalPlan::Values { rows, subqueries } => {
189                for expression in rows.iter().flatten() {
190                    let _ = self.inspect_expression(expression, aliases, inherited);
191                }
192                for subquery in subqueries {
193                    self.inspect_query(subquery, aliases, inherited);
194                }
195            }
196        }
197    }
198
199    fn inspect_source(
200        &mut self,
201        source: &SourcePlan,
202        aliases: &ReturningAliases,
203        inherited: &BTreeSet<String>,
204    ) {
205        match source {
206            crate::plan::SourcePlan::RetainedRows(_) => {}
207            SourcePlan::Table { .. } => {}
208            SourcePlan::Join {
209                left,
210                right,
211                on,
212                lateral,
213                ..
214            } => {
215                self.inspect_source(left, aliases, inherited);
216                let mut right_scope = inherited.clone();
217                if *lateral {
218                    collect_source_qualifiers(left, &mut right_scope);
219                }
220                self.inspect_source(right, aliases, &right_scope);
221                if let Some(on) = on {
222                    let mut scope = inherited.clone();
223                    collect_source_qualifiers(left, &mut scope);
224                    collect_source_qualifiers(right, &mut scope);
225                    let _ = self.inspect_expression(on, aliases, &scope);
226                }
227            }
228            SourcePlan::Values { rows, .. } => {
229                for expression in rows.iter().flatten() {
230                    let _ = self.inspect_expression(expression, aliases, inherited);
231                }
232            }
233            SourcePlan::Function { args, .. } => {
234                for expression in args {
235                    let _ = self.inspect_expression(expression, aliases, inherited);
236                }
237            }
238            SourcePlan::FunctionGroup { functions, .. } => {
239                for expression in functions.iter().flat_map(|function| &function.args) {
240                    let _ = self.inspect_expression(expression, aliases, inherited);
241                }
242            }
243            SourcePlan::Subquery { body, .. } => self.inspect_query(body, aliases, inherited),
244        }
245    }
246
247    pub const fn captures(self) -> bool {
248        self.capture
249    }
250}
251
252fn collect_source_qualifiers(source: &SourcePlan, output: &mut BTreeSet<String>) {
253    match source {
254        SourcePlan::Join {
255            left, right, alias, ..
256        } => {
257            if let Some(alias) = alias {
258                output.insert(alias.to_ascii_lowercase());
259            } else {
260                collect_source_qualifiers(left, output);
261                collect_source_qualifiers(right, output);
262            }
263        }
264        _ => {
265            if let Some(qualifier) = source.visible_qualifier() {
266                output.insert(qualifier.to_ascii_lowercase());
267            }
268        }
269    }
270}
271
272pub fn validate_rule_returning_provider_width(
273    provider_width: usize,
274    event_width: usize,
275) -> Result<(), SQLError> {
276    if provider_width < event_width {
277        return Err(SQLError::Internal(format!(
278            "could not find replacement targetlist entry for attno {}",
279            provider_width + 1
280        )));
281    }
282    if provider_width > event_width {
283        return Err(SQLError::Internal(format!(
284            "rewrite-rule RETURNING provider produced {provider_width} columns, expected {event_width}"
285        )));
286    }
287    Ok(())
288}
289
290pub fn augment_rule_returning_action(
291    statement: &mut Statement,
292    source_index: Option<Expr>,
293    event_width: usize,
294    request: RuleReturningRequest,
295    target_columns: &BTreeSet<String>,
296) -> Result<(), SQLError> {
297    let (target_qualifier, aliases, returning) = match statement {
298        Statement::Insert(action) => (
299            action.target_qualifier.clone(),
300            action.returning_aliases.clone(),
301            action.returning.clone(),
302        ),
303        Statement::Update(action) => (
304            action.target_qualifier.clone(),
305            action.returning_aliases.clone(),
306            action.returning.clone(),
307        ),
308        Statement::Delete(action) => (
309            action.target_qualifier.clone(),
310            action.returning_aliases.clone(),
311            action.returning.clone(),
312        ),
313        _ => return Ok(()),
314    };
315    if returning.is_empty() {
316        return Ok(());
317    }
318    let mut target_columns = target_columns.clone();
319    target_columns.insert(crate::semantics::DOC_ID_COLUMN.into());
320    let provider_event = match statement {
321        Statement::Insert(_) => RuleEvent::Insert,
322        Statement::Update(_) => RuleEvent::Update,
323        Statement::Delete(_) => RuleEvent::Delete,
324        _ => unreachable!("validated rule provider changed statement kind"),
325    };
326    let current = if request.images.contains(RuleReturningImages::CURRENT) {
327        returning.clone()
328    } else {
329        null_rule_returning_image(event_width)
330    };
331    let old = if request.images.contains(RuleReturningImages::OLD)
332        && provider_event != RuleEvent::Insert
333    {
334        rewrite_rule_returning_image(
335            &returning,
336            &target_qualifier,
337            &target_columns,
338            &aliases.old,
339            &aliases.new,
340            &aliases.old,
341        )?
342    } else {
343        null_rule_returning_image(event_width)
344    };
345    let new = if request.images.contains(RuleReturningImages::NEW)
346        && provider_event != RuleEvent::Delete
347    {
348        rewrite_rule_returning_image(
349            &returning,
350            &target_qualifier,
351            &target_columns,
352            &aliases.old,
353            &aliases.new,
354            &aliases.new,
355        )?
356    } else {
357        null_rule_returning_image(event_width)
358    };
359    let output = match statement {
360        Statement::Insert(action) => &mut action.returning,
361        Statement::Update(action) => &mut action.returning,
362        Statement::Delete(action) => &mut action.returning,
363        _ => unreachable!("validated rule provider changed statement kind"),
364    };
365    *output = current;
366    output.extend(old);
367    output.extend(new);
368    if let Some(expr) = source_index {
369        output.push(Projection { expr, alias: None });
370    }
371    Ok(())
372}
373
374fn null_rule_returning_image(width: usize) -> Vec<Projection> {
375    (0..width)
376        .map(|_| Projection {
377            expr: Expr::Literal(Value::Null),
378            alias: None,
379        })
380        .collect()
381}
382
383fn rewrite_rule_returning_image(
384    returning: &[Projection],
385    target_qualifier: &str,
386    target_columns: &BTreeSet<String>,
387    old_qualifier: &str,
388    new_qualifier: &str,
389    image_qualifier: &str,
390) -> Result<Vec<Projection>, SQLError> {
391    let mut resolver = ReturningImageResolver {
392        target_qualifier,
393        target_columns,
394        old_qualifier,
395        new_qualifier,
396        image_qualifier,
397    };
398    returning
399        .iter()
400        .map(|projection| {
401            let expr = match &projection.expr {
402                Expr::Star => Expr::QualifiedStar(image_qualifier.to_string()),
403                Expr::QualifiedStar(qualifier) if resolver.retargets_qualifier(qualifier) => {
404                    Expr::QualifiedStar(image_qualifier.to_string())
405                }
406                expr => super::action_binding::bind_rule_expr_scoped(
407                    expr,
408                    &mut resolver,
409                    &BTreeSet::new(),
410                )?,
411            };
412            Ok(Projection {
413                expr,
414                alias: projection.alias.clone(),
415            })
416        })
417        .collect()
418}
419
420struct ReturningImageResolver<'a> {
421    target_qualifier: &'a str,
422    target_columns: &'a BTreeSet<String>,
423    old_qualifier: &'a str,
424    new_qualifier: &'a str,
425    image_qualifier: &'a str,
426}
427
428impl ReturningImageResolver<'_> {
429    fn retargets_qualifier(&self, qualifier: &str) -> bool {
430        qualifier.eq_ignore_ascii_case(self.target_qualifier)
431            || qualifier.eq_ignore_ascii_case(self.old_qualifier)
432            || qualifier.eq_ignore_ascii_case(self.new_qualifier)
433    }
434}
435
436impl VariableResolver for ReturningImageResolver<'_> {
437    fn resolve_name(&mut self, _name: &str) -> Result<Option<ResolvedVariable>, SQLError> {
438        Ok(None)
439    }
440
441    fn resolve_qualified(
442        &mut self,
443        _qualifier: &str,
444        _column: &str,
445    ) -> Result<Option<ResolvedVariable>, SQLError> {
446        Ok(None)
447    }
448
449    fn resolve_param(&mut self, _index: usize) -> Result<Option<ResolvedVariable>, SQLError> {
450        Ok(None)
451    }
452
453    fn rewrite_name(&mut self, name: &str) -> Result<Option<Expr>, SQLError> {
454        Ok(self
455            .target_columns
456            .contains(name)
457            .then(|| Expr::qualified_column(self.image_qualifier, name)))
458    }
459
460    fn rewrite_qualified(
461        &mut self,
462        qualifier: &str,
463        column: &str,
464    ) -> Result<Option<Expr>, SQLError> {
465        Ok(self
466            .retargets_qualifier(qualifier)
467            .then(|| Expr::qualified_column(self.image_qualifier, column)))
468    }
469}