Skip to main content

uqa_execution/mutation/overlay/
expressions.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Evaluate physical tuple keys before borrowing command frames; retain them with their row version.
8
9use super::{
10    resource_error, Arc, BudgetedVec, CommandMutationOverlay, CommandStoredDocument, DocId,
11    Document, DocumentChanges, DocumentMetadata, KeyKind, RetainedDocumentFields, SQLError,
12    StorageBackendResult, StorageReadControl, Value,
13};
14use crate::catalog::index::physical::PhysicalIndexDefinitions;
15use crate::mutation::constraints::index_keys::IndexExpressionContext;
16
17impl CommandStoredDocument {
18    /// The expressions run before the caller locks its frame stack, so callbacks can read the original command view.
19    pub fn indexed(
20        fields: Arc<Document>,
21        metadata: DocumentMetadata,
22        table: &str,
23        indexes: &PhysicalIndexDefinitions,
24        expressions: IndexExpressionContext<'_>,
25        control: &StorageReadControl,
26    ) -> Result<Self, SQLError> {
27        let values = indexes.command_expression_values(expressions, table, &fields)?;
28        Self::new(fields, metadata, control)
29            .map_err(resource_error)?
30            .with_index_values(values, control)
31            .map_err(resource_error)
32    }
33
34    pub(super) fn with_index_values(
35        mut self,
36        values: Document,
37        control: &StorageReadControl,
38    ) -> StorageBackendResult<Self> {
39        if !values.is_empty() {
40            self.index_values = Some(RetainedDocumentFields::new(Arc::new(values), control)?);
41        }
42        Ok(self)
43    }
44}
45
46/// Exact physical tuple matches and the same command view that masks older stored keys. Transaction-private stored rows are already represented by the mutation index reader.
47pub struct CommandIndexProbe {
48    pub matches: BudgetedVec<DocId>,
49    pub changes: DocumentChanges,
50}
51
52impl CommandMutationOverlay {
53    pub fn visit_column_matches_with_catalog(
54        overlays: &mut [Self],
55        table: &str,
56        fields: &[String],
57        values: &[Value],
58        control: &StorageReadControl,
59        catalog: Option<&dyn uqa_sql::expr::SQLValueCatalog>,
60        visit: &mut dyn FnMut(DocId) -> Result<(), SQLError>,
61    ) -> Result<DocumentChanges, SQLError> {
62        Self::visit_matches_with_catalog(overlays, table, fields, values, control, catalog, visit)?;
63        Self::changes(overlays, table, DocumentChanges::default(), control)
64    }
65
66    pub fn column_matches(
67        overlays: &mut [Self],
68        table: &str,
69        fields: &[String],
70        values: &[Value],
71        control: &StorageReadControl,
72    ) -> Result<CommandIndexProbe, SQLError> {
73        Self::column_matches_with_catalog(overlays, table, fields, values, control, None)
74    }
75
76    pub fn column_matches_with_catalog(
77        overlays: &mut [Self],
78        table: &str,
79        fields: &[String],
80        values: &[Value],
81        control: &StorageReadControl,
82        catalog: Option<&dyn uqa_sql::expr::SQLValueCatalog>,
83    ) -> Result<CommandIndexProbe, SQLError> {
84        let matches =
85            Self::matches_with_catalog(overlays, table, fields, values, control, catalog)?;
86        let changes = Self::changes(overlays, table, DocumentChanges::default(), control)?;
87        Ok(CommandIndexProbe { matches, changes })
88    }
89
90    /// Visit already evaluated tuple keys before retaining the same command mask; the callback captures identities without evaluating row expressions.
91    pub fn visit_expression_matches_with_catalog(
92        overlays: &mut [Self],
93        table: &str,
94        physical_key: &str,
95        values: &[Value],
96        control: &StorageReadControl,
97        catalog: Option<&dyn uqa_sql::expr::SQLValueCatalog>,
98        visit: &mut dyn FnMut(DocId) -> Result<(), SQLError>,
99    ) -> Result<DocumentChanges, SQLError> {
100        super::matching::visit_matches(
101            overlays,
102            table,
103            super::matching::MatchKeys {
104                fields: &[physical_key.to_owned()],
105                values: &[Value::Row(values.to_vec().into())],
106                kind: KeyKind::Expressions,
107            },
108            control,
109            catalog,
110            visit,
111        )?;
112        Self::changes(overlays, table, DocumentChanges::default(), control)
113    }
114
115    pub fn expression_matches(
116        overlays: &mut [Self],
117        table: &str,
118        physical_key: &str,
119        values: &[Value],
120        control: &StorageReadControl,
121    ) -> Result<CommandIndexProbe, SQLError> {
122        Self::expression_matches_with_catalog(overlays, table, physical_key, values, control, None)
123    }
124
125    pub fn expression_matches_with_catalog(
126        overlays: &mut [Self],
127        table: &str,
128        physical_key: &str,
129        values: &[Value],
130        control: &StorageReadControl,
131        catalog: Option<&dyn uqa_sql::expr::SQLValueCatalog>,
132    ) -> Result<CommandIndexProbe, SQLError> {
133        let matches = Self::matches_keys(
134            overlays,
135            table,
136            &[physical_key.to_owned()],
137            &[Value::Row(values.to_vec().into())],
138            KeyKind::Expressions,
139            control,
140            catalog,
141        )?;
142        let changes = Self::changes(overlays, table, DocumentChanges::default(), control)?;
143        Ok(CommandIndexProbe { matches, changes })
144    }
145}