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