Skip to main content

uqa_sql/semantics/rules/binding/actions/
query.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind rule actions to their query input before that input starts producing rows.
8
9use crate::{
10    ast::{Expr, InternalRelationId, Statement},
11    plan::{
12        AccessPathPlan, AggregateClassifier, CommandPlan, ComputePlan, JoinExecutionStrategy,
13        ProjectionPlan, QueryBlockPlan, QueryPlan, RelationalPlan, SourcePlan, UnifiedPlan,
14    },
15    plpgsql::{ResolvedVariable, VariableResolver},
16    SQLError, ScalarExpr,
17};
18use std::collections::{BTreeMap, BTreeSet};
19
20mod resolver;
21pub use resolver::{OwnedRuleQueryResolver, RuleInputColumns};
22mod schedule;
23#[cfg(test)]
24pub(super) use schedule::reference::InsertRuleQueries;
25pub use schedule::OwnedInsertRuleQueries;
26mod assignments;
27mod conditions;
28mod mutation;
29pub use mutation::{MutationRuleInput, OwnedMutationRuleInput, RuleMutation};
30mod owned;
31#[cfg(test)]
32mod tests;
33mod values;
34pub use owned::OwnedRuleQueryInput;
35
36/// An action can borrow a native query tree without converting its rows into constants.
37#[expect(
38    clippy::large_enum_variant,
39    reason = "native action owners move without an additional unadmitted root box"
40)]
41pub enum RuleAction {
42    Stored(Box<Statement>),
43    Rewritten(UnifiedPlan),
44    Owned(crate::plan::MutableExecutablePlan),
45}
46
47impl From<Statement> for RuleAction {
48    fn from(statement: Statement) -> Self {
49        Self::Stored(Box::new(statement))
50    }
51}
52
53impl RuleAction {
54    /// Bind native inputs with the rule's catalog metadata before capturing execution state.
55    pub fn bind(
56        context: crate::semantics::rules::analysis::RuleAnalysisContext<'_>,
57        aggregates: &dyn AggregateClassifier,
58        statement: Statement,
59        input: Option<RuleQueryInput>,
60    ) -> Result<Self, SQLError> {
61        let mut plan = Self::from(statement).lower(aggregates)?;
62        if let Some(input) = input {
63            input.attach(&mut plan, context)?;
64        }
65        Ok(Self::Rewritten(plan))
66    }
67
68    pub fn lower_with_control(
69        self,
70        aggregates: &dyn AggregateClassifier,
71        control: &uqa_core::memory::ProductionControl<'_>,
72    ) -> Result<crate::plan::MutableExecutablePlan, SQLError> {
73        match self {
74            Self::Stored(statement) => {
75                UnifiedPlan::lower_borrowed_for_rewrite(&statement, aggregates, control)?
76                    .mark_catalog_relations_bound(control)
77            }
78            Self::Rewritten(plan) => plan.copy_for_rewrite(control),
79            Self::Owned(plan) => plan.transfer(control),
80        }
81    }
82
83    pub fn lower(self, aggregates: &dyn AggregateClassifier) -> Result<UnifiedPlan, SQLError> {
84        match self {
85            Self::Stored(statement) => {
86                let mut plan = UnifiedPlan::lower_with(*statement, aggregates);
87                crate::binding::stored_routines::mark_catalog_statement_relations_bound(&mut plan)?;
88                Ok(plan)
89            }
90            Self::Rewritten(plan) => Ok(plan),
91            Self::Owned(plan) => Ok(plan
92                .as_plan_ref()
93                .copy_for_rewrite(&uqa_core::memory::ProductionControl::uncontrolled())?
94                .finish(&uqa_core::memory::ProductionControl::uncontrolled())?
95                .into_parts()
96                .0),
97        }
98    }
99}
100
101#[derive(Clone)]
102pub struct RuleQueryInput {
103    pub query: QueryPlan,
104    pub inline: bool,
105    pub relation: InternalRelationId,
106    pub condition: Option<crate::plan::ExpressionPlan>,
107    pub expressions: BTreeMap<crate::ast::InternalColumnRef, crate::plan::ExpressionPlan>,
108}
109
110impl RuleQueryInput {
111    fn attach(
112        self,
113        plan: &mut UnifiedPlan,
114        context: crate::semantics::rules::analysis::RuleAnalysisContext<'_>,
115    ) -> Result<(), SQLError> {
116        let (source, predicate) = if self.inline {
117            let mut query = self.query;
118            let RelationalPlan::QueryBlock(block) = &mut query.root else {
119                return Err(SQLError::Internal(
120                    "rule target list lost its query block".into(),
121                ));
122            };
123            if !query.ctes.is_empty() {
124                return Err(SQLError::Internal(
125                    "rule target list has an unexpected local CTE scope".into(),
126                ));
127            }
128            values::retain_authority(
129                &mut block.subqueries,
130                query.relation_privilege_subject.as_ref(),
131            );
132            let predicate = block
133                .r#where
134                .take()
135                .map(|scalar| crate::plan::ExpressionPlan {
136                    scalar,
137                    subqueries: std::mem::take(&mut block.subqueries),
138                });
139            (block.from.take(), predicate)
140        } else {
141            (
142                Some(SourcePlan::Subquery {
143                    captured_output: Some(self.relation),
144                    lateral: false,
145                    body: Box::new(self.query),
146                    alias: None,
147                    column_aliases: Vec::new(),
148                }),
149                None,
150            )
151        };
152        match plan {
153            UnifiedPlan::Query(query) => attach_query(query, source, predicate, self.condition),
154            UnifiedPlan::Command(command) => match command.as_mut() {
155                CommandPlan::Insert(insert) => {
156                    if insert.source.is_none() {
157                        let mut values =
158                            values::ValuesInput::describe(insert)?.expect("VALUES action input");
159                        insert.source = Some(values.source(context, insert)?);
160                        values.project_layer(context, insert)?;
161                    }
162                    attach_query(
163                        insert.source.as_mut().expect("insert source"),
164                        source,
165                        predicate,
166                        self.condition,
167                    )
168                }
169                CommandPlan::Update(update) => {
170                    update.source = prepend(update.source.take().map(|s| *s), source).map(Box::new);
171                    add_native_condition(&mut update.predicate, &mut update.subqueries, predicate);
172                    add_native_condition(
173                        &mut update.predicate,
174                        &mut update.subqueries,
175                        self.condition,
176                    );
177                    Ok(())
178                }
179                CommandPlan::Delete(delete) => {
180                    delete.source = prepend(delete.source.take().map(|s| *s), source).map(Box::new);
181                    add_native_condition(&mut delete.predicate, &mut delete.subqueries, predicate);
182                    add_native_condition(
183                        &mut delete.predicate,
184                        &mut delete.subqueries,
185                        self.condition,
186                    );
187                    Ok(())
188                }
189                _ => Err(SQLError::Internal(
190                    "rule query input requires a relational action".into(),
191                )),
192            },
193        }?;
194        crate::plan::input_projection::substitute_plan_inputs(plan, &self.expressions)
195    }
196}
197
198fn attach_query(
199    query: &mut QueryPlan,
200    source: Option<SourcePlan>,
201    predicate: Option<crate::plan::ExpressionPlan>,
202    condition: Option<crate::plan::ExpressionPlan>,
203) -> Result<(), SQLError> {
204    if let RelationalPlan::Values { rows, subqueries } = &mut query.root {
205        if rows.len() == 1 {
206            let mut block = projection_block(
207                rows.pop()
208                    .expect("one VALUES row")
209                    .into_iter()
210                    .map(|expr| ProjectionPlan { expr, alias: None })
211                    .collect(),
212            );
213            block.subqueries = std::mem::take(subqueries);
214            query.root = RelationalPlan::QueryBlock(Box::new(block));
215        }
216    }
217    if let RelationalPlan::Values { rows, subqueries } = &mut query.root {
218        let relation = InternalRelationId::allocate();
219        let width = rows.first().map_or(0, Vec::len);
220        let mut block = projection_block(
221            (0..width)
222                .map(|position| ProjectionPlan {
223                    expr: ScalarExpr::InternalColumn(relation.column(position)),
224                    alias: None,
225                })
226                .collect(),
227        );
228        block.from = Some(SourcePlan::Values {
229            lateral: true,
230            rows: std::mem::take(rows),
231            alias: None,
232            column_aliases: Vec::new(),
233            internal_relation: Some(relation),
234            internal_column_types: vec![None; width],
235            internal_column_collations: vec![None; width],
236        });
237        block.subqueries = std::mem::take(subqueries);
238        query.root = RelationalPlan::QueryBlock(Box::new(block));
239    }
240    match &mut query.root {
241        RelationalPlan::QueryBlock(block) => {
242            block.from = prepend(block.from.take(), source);
243            add_native_condition(&mut block.r#where, &mut block.subqueries, predicate);
244            add_native_condition(&mut block.r#where, &mut block.subqueries, condition);
245            Ok(())
246        }
247        RelationalPlan::SetOp { .. }
248            if source.is_some() || predicate.is_some() || condition.is_some() =>
249        {
250            Err(SQLError::Routine {
251                sqlstate: "0A000".into(),
252                message: "conditional UNION/INTERSECT/EXCEPT statements are not implemented".into(),
253            })
254        }
255        RelationalPlan::SetOp { .. } => Ok(()),
256        RelationalPlan::Values { .. } => unreachable!("VALUES lowered to a relational source"),
257    }
258}
259
260#[cfg(test)]
261fn add_condition(
262    predicate: &mut Option<ScalarExpr>,
263    subqueries: &mut Vec<QueryPlan>,
264    condition: Option<Expr>,
265    subject: Option<&crate::catalog::roles::RoleReference>,
266) {
267    if let Some(condition) = condition {
268        let mut expression = crate::plan::ExpressionPlan::lower(condition);
269        for query in &mut expression.subqueries {
270            crate::binding::stored_routines::mark_query_relations_bound(query);
271            query.relation_privilege_subject = subject.cloned();
272        }
273        let offset = subqueries.len();
274        crate::plan::rewrite_scalar_expression(&mut expression.scalar, &mut |node| match node {
275            ScalarExpr::ScalarSubquery(index)
276            | ScalarExpr::Exists {
277                subquery: index, ..
278            }
279            | ScalarExpr::InSubquery {
280                subquery: index, ..
281            } => *index += offset,
282            _ => {}
283        });
284        subqueries.extend(expression.subqueries);
285        *predicate = Some(match predicate.take() {
286            Some(previous) => ScalarExpr::And(vec![previous, expression.scalar]),
287            None => expression.scalar,
288        });
289    }
290}
291
292fn add_native_condition(
293    predicate: &mut Option<ScalarExpr>,
294    subqueries: &mut Vec<QueryPlan>,
295    input: Option<crate::plan::ExpressionPlan>,
296) {
297    if let Some(input) = input {
298        let input = crate::plan::input_projection::append_expression(subqueries, input);
299        *predicate = Some(match predicate.take() {
300            Some(previous) => ScalarExpr::And(vec![previous, input]),
301            None => input,
302        });
303    }
304}
305
306fn prepend(existing: Option<SourcePlan>, source: Option<SourcePlan>) -> Option<SourcePlan> {
307    let Some(source) = source else {
308        return existing;
309    };
310    Some(match existing {
311        Some(right) => SourcePlan::Join {
312            comma: false,
313            left: Box::new(source),
314            right: Box::new(right),
315            kind: crate::ast::JoinKind::Cross,
316            on: None,
317            using: None,
318            natural: false,
319            alias: None,
320            column_aliases: Vec::new(),
321            lateral: true,
322            strategy: JoinExecutionStrategy::Auto,
323        },
324        None => source,
325    })
326}
327
328fn projection_block(projections: Vec<ProjectionPlan>) -> QueryBlockPlan {
329    QueryBlockPlan {
330        deferred_outer_rewrites: Vec::new(),
331        windows: Vec::new(),
332        projections,
333        privilege_columns: uqa_core::memory::OwnedSet::new(),
334        from: None,
335        r#where: None,
336        compute: ComputePlan::Project,
337        group_by: Vec::new(),
338        grouping_sets: Vec::new(),
339        group_distinct: false,
340        having: None,
341        order_by: Vec::new(),
342        limit: None,
343        with_ties: false,
344        offset: None,
345        distinct: false,
346        distinct_on: Vec::new(),
347        subqueries: Vec::new(),
348        access: AccessPathPlan::Row,
349        locking: Vec::new(),
350    }
351}
352
353/// NEW fields are expressions over the input query, so unused fields never run.
354pub struct RuleQueryResolver {
355    pub table: String,
356    pub columns: Vec<(String, Result<Expr, SQLError>)>,
357    pub old: BTreeMap<String, Expr>,
358    pub expressions: BTreeMap<crate::ast::InternalColumnRef, crate::plan::ExpressionPlan>,
359}
360
361impl VariableResolver for RuleQueryResolver {
362    fn rewrite_with_control(
363        &mut self,
364        reference: crate::plpgsql::RewriteReference<'_>,
365        control: &uqa_core::memory::ProductionControl<'_>,
366    ) -> Result<Option<uqa_core::memory::Produced<Expr>>, SQLError> {
367        use crate::{plan::copy::SyntaxProduction, plpgsql::RewriteReference};
368        control.check()?;
369        let production = SyntaxProduction::new(*control);
370        let expression = match reference {
371            RewriteReference::Name(name) | RewriteReference::WholeRow(name) => {
372                let new = name.eq_ignore_ascii_case("new");
373                if !new && !name.eq_ignore_ascii_case("old") {
374                    return Ok(None);
375                }
376                let mut items = production.vector(self.columns.len())?;
377                for (name, expression) in &self.columns {
378                    let expression = if new {
379                        expression.as_ref().map_err(Clone::clone)?
380                    } else {
381                        &self.old[name]
382                    };
383                    items.push(production.copy(expression)?)?;
384                }
385                Expr::Cast {
386                    implicit: true,
387                    expr: production.boxed(Expr::Row(items.finish()?))?,
388                    ty: production.copy(&self.table)?,
389                }
390            }
391            RewriteReference::Qualified { qualifier, column } => {
392                let expression = if qualifier.eq_ignore_ascii_case("new") {
393                    self.columns
394                        .iter()
395                        .find(|(name, _)| name == column)
396                        .map(|(_, value)| value.as_ref().map_err(Clone::clone))
397                        .transpose()?
398                } else if qualifier.eq_ignore_ascii_case("old") {
399                    self.old.get(column)
400                } else {
401                    return Ok(None);
402                };
403                production
404                    .copy(expression.ok_or_else(|| {
405                        SQLError::UnknownColumn(format!("{qualifier}.{column}"))
406                    })?)?
407            }
408            RewriteReference::Parameter(_) | RewriteReference::Internal(_) => return Ok(None),
409        };
410        Ok(Some(production.finish(expression)?))
411    }
412
413    fn resolve_name(&mut self, _name: &str) -> Result<Option<ResolvedVariable>, SQLError> {
414        Ok(None)
415    }
416    fn resolve_qualified(
417        &mut self,
418        _qualifier: &str,
419        _column: &str,
420    ) -> Result<Option<ResolvedVariable>, SQLError> {
421        Ok(None)
422    }
423    fn resolve_param(&mut self, _index: usize) -> Result<Option<ResolvedVariable>, SQLError> {
424        Ok(None)
425    }
426    fn rewrite_name(&mut self, name: &str) -> Result<Option<Expr>, SQLError> {
427        let items = if name.eq_ignore_ascii_case("new") {
428            self.columns
429                .iter()
430                .map(|(_, expression)| expression.clone())
431                .collect::<Result<Vec<_>, _>>()?
432        } else if name.eq_ignore_ascii_case("old") {
433            self.columns
434                .iter()
435                .map(|(name, _)| self.old[name].clone())
436                .collect()
437        } else {
438            return Ok(None);
439        };
440        Ok(Some(Expr::Cast {
441            implicit: true,
442            expr: Box::new(Expr::Row(items)),
443            ty: self.table.clone(),
444        }))
445    }
446    fn rewrite_qualified(
447        &mut self,
448        qualifier: &str,
449        column: &str,
450    ) -> Result<Option<Expr>, SQLError> {
451        if qualifier.eq_ignore_ascii_case("new") {
452            self.columns
453                .iter()
454                .find(|(name, _)| name == column)
455                .map(|(_, expression)| expression.clone().map(Some))
456                .unwrap_or_else(|| Err(SQLError::UnknownColumn(format!("{qualifier}.{column}"))))
457        } else if qualifier.eq_ignore_ascii_case("old") {
458            self.old
459                .get(column)
460                .cloned()
461                .map(Some)
462                .ok_or_else(|| SQLError::UnknownColumn(format!("{qualifier}.{column}")))
463        } else {
464            Ok(None)
465        }
466    }
467    fn rewrite_qualified_whole_row(&mut self, qualifier: &str) -> Result<Option<Expr>, SQLError> {
468        self.rewrite_name(qualifier)
469    }
470}
471
472impl RuleQueryResolver {
473    /// Describe the source positions referenced by an action and its condition before planner pruning.
474    pub fn input_columns(
475        &self,
476        context: crate::semantics::rules::analysis::RuleAnalysisContext<'_>,
477        insert: &crate::plan::InsertPlan,
478        action: &Statement,
479        condition: Option<&Expr>,
480        target_columns: &BTreeSet<String>,
481    ) -> Result<Option<(BTreeSet<usize>, usize)>, SQLError> {
482        use crate::semantics::rules::action_binding as binding;
483        let mut required =
484            binding::rule_statement_row_columns(context.sources, action, target_columns)?;
485        if let Some(condition) = condition {
486            required.extend(binding::rule_expr_row_columns(condition));
487        }
488        if binding::rule_statement_references_whole_row(context.sources, action, target_columns)?
489            || condition.is_some_and(binding::rule_expr_references_whole_row)
490        {
491            return Ok(None);
492        }
493        let supplied = if insert.columns.is_empty() {
494            let width = insert
495                .source
496                .as_deref()
497                .and_then(|query| query.analyzed_output.as_ref())
498                .map_or_else(
499                    || inline_width(insert).unwrap_or(self.columns.len()),
500                    crate::RowSchema::len,
501                );
502            self.columns
503                .iter()
504                .take(width)
505                .map(|(name, _)| name.as_str())
506                .collect::<Vec<_>>()
507        } else {
508            insert
509                .columns
510                .iter()
511                .map(|column| column.column.as_str())
512                .collect()
513        };
514        let positions = supplied
515            .iter()
516            .enumerate()
517            .filter_map(|(index, name)| required.contains(*name).then_some(index))
518            .collect();
519        Ok(Some((positions, supplied.len())))
520    }
521
522    pub fn from_insert(
523        context: crate::semantics::rules::analysis::RuleAnalysisContext<'_>,
524        insert: &crate::plan::InsertPlan,
525        relation: InternalRelationId,
526    ) -> Result<Self, SQLError> {
527        let definitions =
528            crate::semantics::rules::analysis::rule_returning_columns(context, &insert.table)?;
529        let supplied = if insert.columns.is_empty() {
530            let width = insert
531                .source
532                .as_deref()
533                .and_then(|source| source.analyzed_output.as_ref())
534                .map_or_else(
535                    || inline_width(insert).unwrap_or(definitions.len()),
536                    crate::RowSchema::len,
537                );
538            definitions
539                .iter()
540                .take(width)
541                .map(|column| column.name.as_str())
542                .collect::<Vec<_>>()
543        } else {
544            insert
545                .columns
546                .iter()
547                .map(|column| column.column.as_str())
548                .collect()
549        };
550        let mut columns = Vec::with_capacity(definitions.len());
551        let mut old = BTreeMap::new();
552        let mut expressions = BTreeMap::new();
553        for column in &definitions {
554            let ty = column.ty.catalog_name();
555            let null = Expr::Cast {
556                implicit: true,
557                expr: Box::new(Expr::Literal(uqa_core::Value::Null)),
558                ty: ty.clone(),
559            };
560            old.insert(column.name.clone(), null.clone());
561            let metadata = crate::semantics::rules::binding::RuleColumnMetadata {
562                ty: column.ty.clone(),
563                collation_oid: column.collation_oid,
564            };
565            if insert
566                .columns
567                .iter()
568                .any(|target| target.column == column.name && !target.is_whole_column())
569            {
570                let reference = InternalRelationId::allocate().column(0);
571                let mut expression =
572                    assignments::column_expression(context, insert, column, relation)?;
573                expression.scalar = metadata.bind_input(expression.scalar);
574                expressions.insert(reference, expression);
575                columns.push((column.name.clone(), Ok(Expr::InternalColumn(reference))));
576                continue;
577            }
578            let supplied_position = supplied
579                .iter()
580                .position(|name| *name == column.name)
581                .filter(|_| !values::overrides_identity(column, insert.overriding));
582            let value = if let Some(position) = supplied_position {
583                Expr::InternalColumn(relation.column(position))
584            } else {
585                values::default_expression(context, column)?
586                    .unwrap_or(Expr::Literal(uqa_core::Value::Null))
587            };
588            let mut expression = crate::plan::ExpressionPlan::lower(Expr::Cast {
589                implicit: true,
590                expr: Box::new(value),
591                ty,
592            });
593            expression.scalar = metadata.bind_input(expression.scalar);
594            let reference = InternalRelationId::allocate().column(0);
595            expressions.insert(reference, expression);
596            columns.push((column.name.clone(), Ok(Expr::InternalColumn(reference))));
597        }
598        let inputs = inline_input_expressions(insert, relation)?;
599        for expression in expressions.values_mut() {
600            crate::plan::input_projection::substitute_expression_inputs(expression, &inputs)?;
601        }
602        expressions.extend(inputs);
603        if let Some(subject) = insert
604            .source
605            .as_ref()
606            .and_then(|query| query.relation_privilege_subject.as_ref())
607        {
608            for expression in expressions.values_mut() {
609                for query in &mut expression.subqueries {
610                    query
611                        .relation_privilege_subject
612                        .get_or_insert(subject.clone());
613                }
614            }
615        }
616        Ok(Self {
617            table: insert.table.clone(),
618            columns,
619            old,
620            expressions,
621        })
622    }
623}
624
625fn inline_width(insert: &crate::plan::InsertPlan) -> Option<usize> {
626    if !insert
627        .rule_values_input
628        .as_ref()
629        .is_some_and(crate::plan::RuleValuesInput::is_inline)
630    {
631        return None;
632    }
633    match &insert.source.as_ref()?.root {
634        RelationalPlan::QueryBlock(block) => Some(block.projections.len()),
635        _ => None,
636    }
637}
638
639fn inline_input_expressions(
640    insert: &crate::plan::InsertPlan,
641    relation: InternalRelationId,
642) -> Result<BTreeMap<crate::ast::InternalColumnRef, crate::plan::ExpressionPlan>, SQLError> {
643    let mut inputs = BTreeMap::new();
644    if !insert
645        .rule_values_input
646        .as_ref()
647        .is_some_and(crate::plan::RuleValuesInput::is_inline)
648    {
649        return Ok(inputs);
650    }
651    let source = insert.source.as_ref().expect("inline input query");
652    let RelationalPlan::QueryBlock(block) = &source.root else {
653        return Err(SQLError::Internal(
654            "rule target list lost its query block".into(),
655        ));
656    };
657    for (position, projection) in block.projections.iter().enumerate() {
658        let mut input = crate::plan::ExpressionPlan {
659            scalar: projection.expr.clone(),
660            subqueries: block.subqueries.clone(),
661        };
662        crate::plan::subqueries::prune_expression(&mut input);
663        values::retain_authority(
664            &mut input.subqueries,
665            source.relation_privilege_subject.as_ref(),
666        );
667        inputs.insert(relation.column(position), input);
668    }
669    Ok(inputs)
670}