Skip to main content

uqa_execution/mutation/rules/
views.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Automatic-view rewrite-rule projection, batching, and `RETURNING` capture.
8
9use crate::{
10    mutation::{
11        returning::{DmlReturningShape, ReturningExecutionContext},
12        rules::{RuleContext, RuleInputProjection},
13        views::ViewRowContext,
14    },
15    query::CteScope,
16};
17use std::collections::BTreeSet;
18use uqa_core::{DocId, Value};
19use uqa_sql::{
20    plan::{ViewRuleInsertPlan, ViewRuleReturningPlan, ViewRuleUpdatePlan},
21    RowSchema, SQLError, SQLParam, SQLResult,
22};
23use uqa_storage::document_store::Document;
24#[derive(Clone)]
25pub struct ViewRuleContext<'a, S: Clone + 'static> {
26    pub rules: RuleContext<'a>,
27    pub views: ViewRowContext<'a, S>,
28}
29impl<S: Clone + 'static> Copy for ViewRuleContext<'_, S> {}
30struct PreparedViewRuleLayer {
31    relation: String,
32    batch: crate::mutation::rules::PreparedRuleBatch,
33}
34
35pub struct PreparedViewRuleBatches {
36    event: uqa_sql::ast::RuleEvent,
37    layers: Vec<PreparedViewRuleLayer>,
38    suppress_original: Vec<bool>,
39}
40
41pub struct ViewRuleReturningCapture {
42    plan: ViewRuleReturningPlan,
43    result: crate::mutation::rules::RuleReturningResult,
44}
45
46pub struct ViewRuleExecutionOutcome {
47    pub returning: Option<ViewRuleReturningCapture>,
48    pub affected_rows: u64,
49    pub sets_command_tag: bool,
50}
51
52impl ViewRuleReturningCapture {
53    pub fn project<S: Clone + 'static>(
54        self,
55        context: ReturningExecutionContext<'_, S>,
56        params: &[SQLParam],
57        ctes: &CteScope<S>,
58        supplemental_schema: Option<&RowSchema>,
59    ) -> Result<SQLResult, SQLError> {
60        let mut returning_scope = ctes.clone();
61        returning_scope
62            .scalar_subqueries
63            .clone_from(&self.plan.subqueries);
64        self.result.project(
65            context,
66            DmlReturningShape {
67                table: &self.plan.relation,
68                target_qualifier: &self.plan.target_qualifier,
69                aliases: &self.plan.aliases,
70                returning: &self.plan.returning,
71                params,
72                ctes: &returning_scope,
73                supplemental_schema,
74            },
75        )
76    }
77}
78
79impl PreparedViewRuleBatches {
80    fn empty(row_count: usize, event: uqa_sql::ast::RuleEvent) -> Self {
81        Self {
82            event,
83            layers: Vec::new(),
84            suppress_original: vec![false; row_count],
85        }
86    }
87
88    pub fn suppresses(&self, index: usize) -> bool {
89        self.suppress_original.get(index).copied().unwrap_or(false)
90    }
91
92    pub fn configure_action_qualification(&mut self, row_independent_count: Option<usize>) {
93        debug_assert!(matches!(
94            self.event,
95            uqa_sql::ast::RuleEvent::Update | uqa_sql::ast::RuleEvent::Delete
96        ));
97        for layer in &mut self.layers {
98            let count = row_independent_count.unwrap_or_else(|| layer.batch.event_row_count());
99            layer.batch.set_action_qualification_count(count);
100        }
101    }
102
103    pub fn execute_actions_with_affected(
104        &self,
105        context: RuleContext<'_>,
106        returning: Option<&ViewRuleReturningPlan>,
107    ) -> Result<ViewRuleExecutionOutcome, SQLError> {
108        let mut captured = None;
109        let mut affected_rows = 0_u64;
110        let mut sets_command_tag = false;
111        let layers = if self.event == uqa_sql::ast::RuleEvent::Insert {
112            self.layers.iter().rev().collect::<Vec<_>>()
113        } else {
114            self.layers.iter().collect::<Vec<_>>()
115        };
116        for layer in layers {
117            let request = returning
118                .filter(|plan| plan.relation == layer.relation)
119                .map_or_else(
120                    crate::mutation::rules::RuleReturningRequest::default,
121                    |plan| {
122                        crate::mutation::rules::RuleReturningRequest::from_plan(
123                            &plan.returning,
124                            &plan.aliases,
125                            &plan.subqueries,
126                        )
127                    },
128                );
129            let outcome = layer
130                .batch
131                .execute_actions_with_affected(context, request)?;
132            if outcome.sets_command_tag {
133                affected_rows = outcome.affected_rows;
134                sets_command_tag = true;
135            }
136            let Some(result) = outcome.returning else {
137                continue;
138            };
139            if captured.is_some() {
140                return Err(SQLError::Routine {
141                    sqlstate: "0A000".into(),
142                    message: "cannot have RETURNING lists in multiple rules".into(),
143                });
144            }
145            let plan = returning
146                .filter(|plan| plan.relation == layer.relation)
147                .cloned()
148                .ok_or_else(|| {
149                    SQLError::Internal(
150                        "automatic-view rule captured RETURNING without an outer projection".into(),
151                    )
152                })?;
153            captured = Some(ViewRuleReturningCapture { plan, result });
154        }
155        Ok(ViewRuleExecutionOutcome {
156            returning: captured,
157            affected_rows,
158            sets_command_tag,
159        })
160    }
161}
162
163#[derive(Clone)]
164struct ViewRuleDocumentProjection<'a, S: Clone + 'static> {
165    context: ViewRuleContext<'a, S>,
166    relation: &'a str,
167    document_relation: Option<&'a str>,
168    required_columns: &'a BTreeSet<String>,
169    insert_plan: Option<&'a ViewRuleInsertPlan>,
170    update_plan: Option<&'a ViewRuleUpdatePlan>,
171    params: &'a [SQLParam],
172    scope: &'a CteScope<S>,
173}
174
175pub struct ViewRuleBatchRequest<'a, S: Clone + 'static> {
176    pub context: ViewRuleContext<'a, S>,
177    pub relations: &'a [String],
178    pub event: uqa_sql::ast::RuleEvent,
179    pub rows: &'a [crate::mutation::rules::RuleRowImage],
180    pub params: &'a [SQLParam],
181    pub scope: &'a CteScope<S>,
182    pub insert_plans: &'a [ViewRuleInsertPlan],
183    pub update_plans: &'a [ViewRuleUpdatePlan],
184    pub document_relation: Option<&'a str>,
185}
186
187fn project_view_rule_expressions<S: Clone + 'static>(
188    projection: &ViewRuleDocumentProjection<'_, S>,
189    side: crate::mutation::rules::RuleRowSide,
190    storage_table: Option<&str>,
191    doc_id: Option<DocId>,
192    document: Option<&Document>,
193    input_document: Option<&Document>,
194) -> Result<Option<RuleInputProjection>, SQLError> {
195    document
196        .map(|document| {
197            let input_document = input_document.unwrap_or(document);
198            let mut values = Vec::new();
199            let mut required = projection.required_columns.clone();
200            let assignments = if let Some(insert) = projection.insert_plan {
201                Some((&insert.supplied_columns, &insert.input_columns, true))
202            } else if matches!(side, crate::mutation::rules::RuleRowSide::New) {
203                projection
204                    .update_plan
205                    .map(|update| (&update.assigned_columns, &update.input_columns, false))
206            } else {
207                None
208            };
209            if let Some((assigned, inputs, insert)) = assignments {
210                let schema = projection
211                    .context
212                    .views
213                    .rows
214                    .relations
215                    .view_schema(projection.relation)?;
216                for column in projection.required_columns {
217                    let value = assigned
218                        .iter()
219                        .position(|name| name == column)
220                        .and_then(|index| inputs.get(index))
221                        .and_then(|input| input_document.get(input));
222                    if !insert && value.is_none() {
223                        continue;
224                    }
225                    let value = value.cloned().unwrap_or(Value::Null);
226                    let position = schema.unqualified_position(column);
227                    let ty = position.and_then(|position| schema.column_type(position));
228                    let collation = position.and_then(|position| schema.column_collation(position));
229                    values.push((column.clone(), value, ty.cloned(), collation));
230                    required.remove(column);
231                }
232            }
233            let mut projected = RuleInputProjection::values(values);
234            if projection.insert_plan.is_none() {
235                let other = crate::mutation::views::automatic_view_rule_expressions(
236                    crate::mutation::views::AutomaticViewRuleDocument {
237                        context: projection.context.views,
238                        view: projection.relation,
239                        document_relation: projection.document_relation,
240                        storage_table,
241                        doc_id,
242                        document,
243                        required_columns: &required,
244                        params: projection.params,
245                        scope: projection.scope,
246                    },
247                )?;
248                super::inputs::append_source(&mut projected.source, &other.source);
249                projected.expressions.extend(other.expressions);
250            }
251            Ok(projected)
252        })
253        .transpose()
254}
255
256fn project_view_rule_document<S: Clone + 'static>(
257    projection: &ViewRuleDocumentProjection<'_, S>,
258    side: crate::mutation::rules::RuleRowSide,
259    storage_table: Option<&str>,
260    doc_id: Option<DocId>,
261    document: Option<&Document>,
262    input_document: Option<&Document>,
263) -> Result<Option<Document>, SQLError> {
264    project_view_rule_expressions(
265        projection,
266        side,
267        storage_table,
268        doc_id,
269        document,
270        input_document,
271    )?
272    .map(|projected| {
273        projected
274            .expressions
275            .into_iter()
276            .map(|(name, expression)| {
277                crate::query::catalog_expression::eval_stored_expression_plan_with_row(
278                    projection.context.views.expressions.expressions,
279                    projection.scope.clone(),
280                    &expression,
281                    &projected.source.schema,
282                    &projected.source.row,
283                    projection.params,
284                )
285                .map(|value| (name, value))
286            })
287            .collect()
288    })
289    .transpose()
290}
291
292fn project_view_rule_row<S: Clone + 'static>(
293    projection: &ViewRuleDocumentProjection<'_, S>,
294    row: &crate::mutation::rules::RuleRowImage,
295) -> Result<crate::mutation::rules::RuleRowImage, SQLError> {
296    Ok(crate::mutation::rules::RuleRowImage {
297        old_storage_table: row.old_storage_table.clone(),
298        old_doc_id: row.old_doc_id,
299        old: project_view_rule_document(
300            projection,
301            crate::mutation::rules::RuleRowSide::Old,
302            row.old_storage_table.as_deref(),
303            row.old_doc_id,
304            row.old.as_ref(),
305            row.old.as_ref(),
306        )?,
307        new_storage_table: row.new_storage_table.clone(),
308        new_doc_id: row.new_doc_id,
309        new: project_view_rule_document(
310            projection,
311            crate::mutation::rules::RuleRowSide::New,
312            if projection.update_plan.is_some() {
313                row.old_storage_table.as_deref()
314            } else {
315                row.new_storage_table.as_deref()
316            },
317            if projection.update_plan.is_some() {
318                row.old_doc_id
319            } else {
320                row.new_doc_id
321            },
322            if projection.update_plan.is_some() {
323                row.old.as_ref()
324            } else {
325                row.new.as_ref()
326            },
327            row.new.as_ref(),
328        )?,
329        context: row.context.clone(),
330    })
331}
332
333fn project_view_rule_row_sides<S: Clone + 'static>(
334    projection: &ViewRuleDocumentProjection<'_, S>,
335    row: &crate::mutation::rules::RuleRowImage,
336    old_columns: &BTreeSet<String>,
337    new_columns: &BTreeSet<String>,
338) -> Result<crate::mutation::rules::RuleRowImage, SQLError> {
339    let old_projection = ViewRuleDocumentProjection {
340        required_columns: old_columns,
341        ..*projection
342    };
343    let new_projection = ViewRuleDocumentProjection {
344        required_columns: new_columns,
345        ..*projection
346    };
347    Ok(crate::mutation::rules::RuleRowImage {
348        old_storage_table: row.old_storage_table.clone(),
349        old_doc_id: row.old_doc_id,
350        old: project_view_rule_document(
351            &old_projection,
352            crate::mutation::rules::RuleRowSide::Old,
353            row.old_storage_table.as_deref(),
354            row.old_doc_id,
355            row.old.as_ref(),
356            row.old.as_ref(),
357        )?,
358        new_storage_table: row.new_storage_table.clone(),
359        new_doc_id: row.new_doc_id,
360        new: project_view_rule_document(
361            &new_projection,
362            crate::mutation::rules::RuleRowSide::New,
363            if new_projection.update_plan.is_some() {
364                row.old_storage_table.as_deref()
365            } else {
366                row.new_storage_table.as_deref()
367            },
368            if new_projection.update_plan.is_some() {
369                row.old_doc_id
370            } else {
371                row.new_doc_id
372            },
373            if new_projection.update_plan.is_some() {
374                row.old.as_ref()
375            } else {
376                row.new.as_ref()
377            },
378            row.new.as_ref(),
379        )?,
380        context: row.context.clone(),
381    })
382}
383
384#[expect(
385    clippy::too_many_lines,
386    reason = "preserves view qualifier and row identity"
387)]
388pub fn prepare_view_rule_batches<S: Clone + 'static>(
389    request: ViewRuleBatchRequest<'_, S>,
390) -> Result<PreparedViewRuleBatches, SQLError> {
391    let ViewRuleBatchRequest {
392        context,
393        relations,
394        event,
395        rows,
396        params,
397        scope,
398        insert_plans,
399        update_plans,
400        document_relation,
401    } = request;
402    if relations.is_empty() {
403        return Ok(PreparedViewRuleBatches::empty(rows.len(), event));
404    }
405    let mut prepared = PreparedViewRuleBatches::empty(rows.len(), event);
406    for relation in relations {
407        let required_columns = BTreeSet::new();
408        let insert_plan = insert_plans.iter().find(|plan| plan.relation == *relation);
409        let update_plan = update_plans.iter().find(|plan| plan.relation == *relation);
410        let projection = ViewRuleDocumentProjection {
411            context,
412            relation,
413            document_relation,
414            required_columns: &required_columns,
415            insert_plan,
416            update_plan,
417            params,
418            scope,
419        };
420        let row_indices = (0..rows.len())
421            .filter(|index| !prepared.suppress_original[*index])
422            .collect::<Vec<_>>();
423        let view_rows = row_indices
424            .iter()
425            .map(|index| {
426                let row = rows.get(*index).ok_or_else(|| {
427                    SQLError::Internal("automatic-view rule lost its event row".into())
428                })?;
429                project_view_rule_row(&projection, row)
430            })
431            .collect::<Result<Vec<_>, SQLError>>()?;
432        let mut batch = crate::mutation::rules::prepare_rule_batch_with_projection(
433            context.rules,
434            relation,
435            event,
436            view_rows,
437            |local_index, side, required| {
438                let row_index = row_indices.get(local_index).copied().ok_or_else(|| {
439                    SQLError::Internal("automatic-view rule lost its event row".into())
440                })?;
441                let row = rows.get(row_index).ok_or_else(|| {
442                    SQLError::Internal("automatic-view rule lost its event row".into())
443                })?;
444                let (storage_table, doc_id, document, input_document) = match side {
445                    crate::mutation::rules::RuleRowSide::Old => (
446                        row.old_storage_table.as_deref(),
447                        row.old_doc_id,
448                        row.old.as_ref(),
449                        row.old.as_ref(),
450                    ),
451                    crate::mutation::rules::RuleRowSide::New
452                        if projection.update_plan.is_some() =>
453                    {
454                        (
455                            row.old_storage_table.as_deref(),
456                            row.old_doc_id,
457                            row.old.as_ref(),
458                            row.new.as_ref(),
459                        )
460                    }
461                    crate::mutation::rules::RuleRowSide::New => (
462                        row.new_storage_table.as_deref(),
463                        row.new_doc_id,
464                        row.new.as_ref(),
465                        row.new.as_ref(),
466                    ),
467                };
468                let Some(document) = document else {
469                    return Ok(RuleInputProjection::default());
470                };
471                let projection = ViewRuleDocumentProjection {
472                    required_columns: required,
473                    ..projection
474                };
475                let projected = project_view_rule_expressions(
476                    &projection,
477                    side,
478                    storage_table,
479                    doc_id,
480                    Some(document),
481                    input_document,
482                )?
483                .ok_or_else(|| {
484                    SQLError::Internal("automatic-view rule projection lost its row".into())
485                })?;
486                Ok(projected)
487            },
488        )?;
489        let action_columns = batch.missing_action_row_columns();
490        if action_columns
491            .iter()
492            .any(|(old, new)| !old.is_empty() || !new.is_empty())
493        {
494            let supplemental_rows = row_indices
495                .iter()
496                .zip(action_columns)
497                .map(|(index, (old_columns, new_columns))| {
498                    let row = rows.get(*index).ok_or_else(|| {
499                        SQLError::Internal("automatic-view rule lost its event row".into())
500                    })?;
501                    project_view_rule_row_sides(&projection, row, &old_columns, &new_columns)
502                })
503                .collect::<Result<Vec<_>, SQLError>>()?;
504            batch.supplement_rows(supplemental_rows)?;
505        }
506        for (local_index, row_index) in row_indices.iter().copied().enumerate() {
507            if batch.suppresses(local_index) {
508                prepared.suppress_original[row_index] = true;
509            }
510        }
511        prepared.layers.push(PreparedViewRuleLayer {
512            relation: relation.clone(),
513            batch,
514        });
515        if uqa_sql::semantics::rules::analysis::relation_suppresses_original_query(
516            context.rules.analysis,
517            relation,
518            event,
519        )? {
520            break;
521        }
522    }
523    Ok(prepared)
524}
525
526impl<S: Clone + 'static> Copy for ViewRuleDocumentProjection<'_, S> {}