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