Skip to main content

uqa_engine/capabilities/
referential.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind referential execution to transaction queues and mutation snapshots.
8use crate::Engine;
9use uqa_core::DocId;
10use uqa_execution::mutation::referential::{
11    ReferentialContext, ReferentialDeferrals, ReferentialReadSnapshot, ReferentialSnapshots,
12};
13use uqa_sql::{ast::ForeignKey, SQLError};
14impl Engine {
15    pub(crate) fn referential_execution_context(
16        &self,
17    ) -> ReferentialContext<'_, crate::session::StatementReadSnapshot> {
18        ReferentialContext {
19            constraints: self.constraint_execution_context(),
20            locking: self.row_lock_context(),
21            assignment: self.mutation_assignment_context(),
22            identifiers: self,
23            triggers: self.trigger_execution_context(),
24            deferrals: self,
25            snapshots: self,
26        }
27    }
28}
29impl ReferentialDeferrals for Engine {
30    fn defer_foreign_key_check(
31        &self,
32        constraint_table: &str,
33        firing_table: &str,
34        row_table: &str,
35        doc_id: DocId,
36        foreign_key: &ForeignKey,
37        derived: Option<&uqa_sql::ast::ReferencedPartitionConstraint>,
38    ) -> Result<(), SQLError> {
39        Engine::defer_foreign_key_check(
40            self,
41            crate::transactions::DeferredReferencedKey {
42                constraint_table,
43                firing_table,
44                foreign_key,
45                derived,
46            },
47            row_table,
48            doc_id,
49        )
50    }
51    fn defer_foreign_key_parent_event(
52        &self,
53        constraint_table: &str,
54        firing_table: &str,
55        foreign_key: &ForeignKey,
56        derived: Option<&uqa_sql::ast::ReferencedPartitionConstraint>,
57    ) -> Result<(), SQLError> {
58        Engine::defer_foreign_key_parent_event(
59            self,
60            crate::transactions::DeferredReferencedKey {
61                constraint_table,
62                firing_table,
63                foreign_key,
64                derived,
65            },
66        )
67    }
68}
69
70/// Own or borrow the existing snapshot resource; referential scan policy belongs to execution.
71struct ReferenceSnapshotEngine<T: std::ops::Deref<Target = Engine>>(T);
72
73impl<T: std::ops::Deref<Target = Engine>> ReferentialReadSnapshot for ReferenceSnapshotEngine<T> {
74    fn doc_ids(&self, table: &str) -> Result<Vec<DocId>, SQLError> {
75        self.0.live_table_doc_ids(table)
76    }
77    fn value_index_scan_key(
78        &self,
79        table: &str,
80        key: &uqa_storage::ValueIndexKey,
81        predicate: &uqa_core::Predicate,
82    ) -> Result<Option<uqa_core::PostingList>, SQLError> {
83        self.0.value_index_scan_key(table, key, predicate)
84    }
85    fn document(
86        &self,
87        table: &str,
88        doc_id: DocId,
89    ) -> Result<Option<uqa_storage::document_store::Document>, SQLError> {
90        self.0.get_live_document(table, doc_id)
91    }
92    fn metadata(
93        &self,
94        table: &str,
95        doc_id: DocId,
96    ) -> Result<Option<uqa_storage::DocumentMetadata>, SQLError> {
97        self.0
98            .require_table(table)?
99            .document_store
100            .read()
101            .get_metadata(doc_id)
102            .map_err(|error| SQLError::Internal(format!("read reference tuple metadata: {error}")))
103    }
104}
105impl ReferentialSnapshots for Engine {
106    fn latest_reference_snapshot(&self) -> Result<Box<dyn ReferentialReadSnapshot + '_>, SQLError> {
107        let Some(backend) = self.storage.backend.as_ref() else {
108            return Ok(Box::new(ReferenceSnapshotEngine(self)));
109        };
110        if backend.transaction_has_written().map_err(|error| {
111            SQLError::Internal(format!("inspect reference snapshot transaction: {error}"))
112        })? {
113            Ok(Box::new(ReferenceSnapshotEngine(self)))
114        } else {
115            Ok(Box::new(ReferenceSnapshotEngine(
116                self.open_independent_pinned_read_snapshot()?,
117            )))
118        }
119    }
120    fn transaction_document_metadata(
121        &self,
122        table: &str,
123        doc_id: DocId,
124    ) -> Result<Option<uqa_storage::DocumentMetadata>, SQLError> {
125        self.get_query_document_metadata(table, doc_id)
126    }
127}