Skip to main content

uqa_engine/capabilities/
mutation_publication.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind physical publication to the active storage and transaction generation.
8use crate::Engine;
9use std::collections::BTreeMap;
10use uqa_core::{DocId, FieldName};
11use uqa_execution::mutation::{
12    identity::MutationIdentifiers,
13    publication::{
14        DocumentVectors, MutationConstraintDeferrals, MutationHistory, MutationStorage,
15        MutationTextIndex, PublicationContext,
16    },
17};
18use uqa_sql::SQLError;
19use uqa_storage::document_store::Document;
20impl Engine {
21    pub(crate) fn mutation_publication_context(&self) -> PublicationContext<'_> {
22        PublicationContext {
23            observations: self,
24            storage: self,
25            text: self,
26            history: self,
27            deferrals: self,
28            identifiers: self,
29            catalog: self,
30        }
31    }
32}
33impl MutationIdentifiers for Engine {
34    fn allocate_next_id(&self, table: &str) -> Result<DocId, SQLError> {
35        Engine::allocate_next_id(self, table)
36    }
37    fn allocate_unmapped_id(&self, table: &str) -> Result<DocId, SQLError> {
38        Engine::allocate_unmapped_id(self, table)
39    }
40    fn maps_integer_keys(&self, table: &str) -> Result<bool, SQLError> {
41        Ok(self
42            .require_table(table)?
43            .maps_integer_keys
44            .load(std::sync::atomic::Ordering::Acquire))
45    }
46    fn advance_next_id(&self, table: &str, doc_id: DocId) -> uqa_storage::StorageBackendResult<()> {
47        Engine::advance_next_id(self, table, doc_id)
48    }
49    fn persist_next_id(&self, table: &str) -> uqa_storage::StorageBackendResult<()> {
50        Engine::persist_next_id(self, table)
51    }
52    fn generates_unused_identities(&self, table: &str) -> Result<bool, SQLError> {
53        // A member of a partition hierarchy draws its identities from the hierarchy's owner, whose watermark is not this table's.
54        if uqa_sql::semantics::partition::partition_hierarchy_root(self, table)?.is_some() {
55            return Ok(false);
56        }
57        let state = self
58            .try_table(table)
59            .map_err(|error| SQLError::Internal(error.to_string()))?
60            .ok_or_else(|| SQLError::UnknownTable(table.into()))?;
61        self.table_identifier_allocator(&state)
62            .map(|allocator| allocator.is_durable())
63            .map_err(|error| {
64                uqa_execution::storage_errors::storage_error("inspect document identities", &error)
65            })
66    }
67}
68impl MutationStorage for Engine {
69    fn can_defer_document_text(&self, table: &str) -> Result<bool, SQLError> {
70        let table = self
71            .try_resolve_table_name(table)
72            .map_err(|error| SQLError::Internal(error.to_string()))?
73            .ok_or_else(|| SQLError::UnknownTable(table.into()))?;
74        Ok(!self
75            .physical_index_definitions()
76            .map_err(|error| SQLError::Internal(error.to_string()))?
77            .row_publication_uses_expressions(&table))
78    }
79
80    fn delete_document(&self, table: &str, doc_id: DocId) -> Result<(), SQLError> {
81        Engine::delete_document(self, table, doc_id)
82    }
83    fn observe_document_identity(
84        &self,
85        table: &str,
86        doc_id: DocId,
87    ) -> Result<uqa_storage::mvcc::ObservedIdentifier, SQLError> {
88        let state = self
89            .try_table(table)
90            .map_err(|error| SQLError::Internal(error.to_string()))?
91            .ok_or_else(|| SQLError::UnknownTable(table.into()))?;
92        self.table_identifier_allocator(&state)
93            .and_then(|allocator| allocator.observe_durably(doc_id))
94            .map_err(|error| {
95                uqa_execution::storage_errors::storage_error("observe document identity", &error)
96            })
97    }
98    fn delete_document_deferred_text(&self, table: &str, doc_id: DocId) -> Result<(), SQLError> {
99        self.delete_prepared_document_deferred_fts(table, doc_id)
100    }
101    fn insert_document(
102        &self,
103        table: &str,
104        doc_id: DocId,
105        document: Document,
106        vectors: DocumentVectors,
107        inserted: uqa_execution::mutation::publication::InsertedIdentity,
108    ) -> Result<(), SQLError> {
109        self.add_prepared_document_with_vector_values(table, doc_id, document, vectors, inserted)
110    }
111    fn insert_document_deferred_text(
112        &self,
113        table: &str,
114        doc_id: DocId,
115        document: Document,
116        vectors: DocumentVectors,
117        inserted: uqa_execution::mutation::publication::InsertedIdentity,
118    ) -> Result<(), SQLError> {
119        self.add_prepared_document_with_vector_values_deferred_fts(
120            table, doc_id, document, vectors, inserted,
121        )
122    }
123    fn rewrite_document(
124        &self,
125        table: &str,
126        doc_id: DocId,
127        document: Document,
128    ) -> Result<(), SQLError> {
129        self.rewrite_prepared_document(table, doc_id, document)
130    }
131    fn rewrite_document_deferred_text(
132        &self,
133        table: &str,
134        doc_id: DocId,
135        document: Document,
136    ) -> Result<(), SQLError> {
137        self.rewrite_prepared_document_deferred_fts(table, doc_id, document)
138    }
139}
140impl MutationTextIndex for Engine {
141    fn text_fields(
142        &self,
143        table: &str,
144        document: &Document,
145    ) -> Result<BTreeMap<FieldName, String>, SQLError> {
146        self.prepared_document_text_fields(table, document)
147    }
148    fn add_documents(
149        &self,
150        table: &str,
151        documents: Vec<(DocId, BTreeMap<FieldName, String>)>,
152    ) -> Result<(), SQLError> {
153        self.add_prepared_fts_documents(table, documents)
154    }
155}
156impl MutationHistory for Engine {
157    fn note_rewrite(
158        &self,
159        old_table: &str,
160        old_doc_id: DocId,
161        new_table: &str,
162        new_doc_id: DocId,
163    ) -> Result<(), SQLError> {
164        self.note_row_rewritten_between_tables(old_table, old_doc_id, new_table, new_doc_id)
165    }
166}
167impl MutationConstraintDeferrals for Engine {
168    fn inserted(&self, table: &str, doc_id: DocId) -> Result<(), SQLError> {
169        self.defer_inserted_foreign_key_checks(table, doc_id)
170    }
171    fn rewritten(
172        &self,
173        table: &str,
174        doc_id: DocId,
175        old: Option<&Document>,
176        new: &Document,
177    ) -> Result<(), SQLError> {
178        self.defer_rewritten_foreign_key_checks(table, doc_id, old, new)
179    }
180}
181
182impl uqa_execution::mutation::staging::MutationCommandRows for Engine {
183    fn stage_shared_command_document(
184        &self,
185        table: &str,
186        doc_id: DocId,
187        document: Option<std::sync::Arc<Document>>,
188    ) -> Result<(), SQLError> {
189        Engine::stage_shared_command_document(self, table, doc_id, document)
190    }
191    fn stage_command_document(
192        &self,
193        table: &str,
194        doc_id: DocId,
195        document: Option<Document>,
196    ) -> Result<(), SQLError> {
197        Engine::stage_command_document(self, table, doc_id, document)
198    }
199}
200impl Engine {
201    pub(crate) fn mutation_staging_context(
202        &self,
203    ) -> uqa_execution::mutation::staging::MutationStagingContext<'_> {
204        uqa_execution::mutation::staging::MutationStagingContext {
205            commands: self,
206            constraints: self.constraint_execution_context(),
207            triggers: self.trigger_execution_context(),
208        }
209    }
210}
211
212use uqa_execution::serializable::SerializableWrites;
213use uqa_sql::ast::RelationPersistence;
214use uqa_storage::mvcc::SerializableSession;
215
216impl SerializableWrites for Engine {
217    fn serializable_session(&self) -> Option<&dyn SerializableSession> {
218        self.storage.backend.as_ref()?.serializable_session()
219    }
220
221    fn serializable_cancellation(&self) -> &uqa_core::CancellationToken {
222        &self.runtime.cancellation
223    }
224
225    fn serializable_write_object(&self, table: &str) -> Result<Option<[u8; 16]>, SQLError> {
226        let table = self.require_table(table)?;
227        Ok((table.persistence != RelationPersistence::Temporary).then_some(table.object_id()))
228    }
229}