Skip to main content

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

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Type and value contracts for executor-retained rule inputs.
8
9use super::{
10    bind_source_action, rule_row_metadata, runtime_rule_resolver, BindRuleAction,
11    BoundSetOrientedAction, RuleColumnMetadata, RuleRowMetadata, RuleRowSource, RuleRowValues,
12};
13use crate::{
14    ast::{FromClause, InternalRelationId, RetainedRowSource},
15    RowSchema, SQLError,
16};
17use std::collections::BTreeMap;
18use std::sync::Arc;
19use uqa_core::Value;
20
21/// Describe OLD/NEW input once, materialize one admitted event at a time and bind one set-oriented action to the executor's retained rows.
22pub struct RetainedRuleInput<'a> {
23    columns: &'a BTreeMap<String, RuleColumnMetadata>,
24    metadata: RuleRowMetadata,
25    schema: RowSchema,
26}
27
28impl<'a> RetainedRuleInput<'a> {
29    pub fn new(columns: &'a BTreeMap<String, RuleColumnMetadata>) -> Self {
30        let metadata = rule_row_metadata(InternalRelationId::allocate(), columns);
31        let schema = RowSchema::with_internal_relation_metadata(
32            metadata.relation,
33            metadata
34                .types
35                .iter()
36                .cloned()
37                .zip(metadata.collations.iter().copied()),
38        );
39        let mut ordered: Vec<_> = columns.iter().collect();
40        ordered.sort_by_key(|(_, field)| field.position);
41        let types: crate::schema::RecordFields = ordered
42            .iter()
43            .map(|(_, field)| Some(field.ty.clone()))
44            .collect();
45        let record = crate::schema::RecordMetadata {
46            types: Some(types.clone()),
47            descriptor: Some(Arc::new(crate::schema::RecordDescriptor {
48                types,
49                names: Some(ordered.iter().map(|(name, _)| (*name).clone()).collect()),
50                fields: ordered
51                    .iter()
52                    .map(|(_, field)| crate::schema::RecordFieldMetadata {
53                        collation_oid: field.collation_oid.unwrap_or_else(|| {
54                            u32::try_from(crate::catalog::type_metadata::pg_type_collation_oid(
55                                &field.ty,
56                            ))
57                            .expect("type collation identity")
58                        }),
59                        sql_unknown: false,
60                    })
61                    .collect(),
62            })),
63        };
64        let schema = schema.with_physical_record_metadata([
65            (columns.len() * 2, record.clone()),
66            (columns.len() * 2 + 1, record),
67        ]);
68        Self {
69            columns,
70            metadata,
71            schema,
72        }
73    }
74
75    pub fn relation(&self) -> InternalRelationId {
76        self.metadata.relation
77    }
78
79    pub fn schema(&self) -> &RowSchema {
80        &self.schema
81    }
82
83    /// The first slots replace typed constants; whole OLD/NEW records and the ordinal replace untyped constants.
84    pub fn admitted_types(&self) -> Arc<[Option<String>]> {
85        self.metadata
86            .types
87            .iter()
88            .enumerate()
89            .map(|(slot, ty)| {
90                (slot < self.columns.len() * 2)
91                    .then(|| ty.as_ref().expect("declared rule field").catalog_name())
92            })
93            .collect()
94    }
95
96    pub fn row_values(
97        &self,
98        row: &dyn RuleRowValues,
99        row_index: usize,
100    ) -> Result<Vec<Value>, SQLError> {
101        let resolver = runtime_rule_resolver(row, self.columns);
102        let mut values = Vec::with_capacity(self.metadata.types.len());
103        for column in self.columns.keys() {
104            for (record, doc_id) in [
105                (row.old_row(), row.old_doc_id()),
106                (row.new_row(), row.new_doc_id()),
107            ] {
108                crate::expr::check_statement_cancellation()?;
109                let (_, value) = resolver.field(record, doc_id, column)?;
110                values.push(value);
111            }
112        }
113        values.push(resolver.record(row.old_row(), row.old_doc_id())?.value);
114        values.push(resolver.record(row.new_row(), row.new_doc_id())?.value);
115        values.push(Value::Int(i64::try_from(row_index).map_err(|_| {
116            SQLError::Internal("rewrite rule event row index exceeds BIGINT".into())
117        })?));
118        Ok(values)
119    }
120
121    pub fn bind_action(
122        self,
123        source: RetainedRowSource,
124        bind_action: &BindRuleAction<'_>,
125    ) -> Result<BoundSetOrientedAction, SQLError> {
126        if source.relation() != self.metadata.relation || source.schema() != &self.schema {
127            return Err(SQLError::Internal(
128                "rewrite-rule retained input lost its identity or type descriptor".into(),
129            ));
130        }
131        bind_source_action(
132            RuleRowSource {
133                clause: FromClause::RetainedRows(source),
134                metadata: self.metadata,
135            },
136            bind_action,
137        )
138    }
139}