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: (&str, DocId),
35        foreign_key: &ForeignKey,
36        derived: Option<&uqa_sql::ast::ReferencedPartitionConstraint>,
37        values: std::sync::Arc<[uqa_core::Value]>,
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.0,
48            row.1,
49            values,
50        )
51    }
52    fn defer_foreign_key_parent_event(
53        &self,
54        constraint_table: &str,
55        firing_table: &str,
56        foreign_key: &ForeignKey,
57        derived: Option<&uqa_sql::ast::ReferencedPartitionConstraint>,
58    ) -> Result<(), SQLError> {
59        Engine::defer_foreign_key_parent_event(
60            self,
61            crate::transactions::DeferredReferencedKey {
62                constraint_table,
63                firing_table,
64                foreign_key,
65                derived,
66            },
67        )
68    }
69}
70
71/// Own or borrow the existing snapshot resource; referential scan policy belongs to execution.
72struct ReferenceSnapshotEngine<T: std::ops::Deref<Target = Engine>>(T);
73
74impl<T: std::ops::Deref<Target = Engine>> ReferentialReadSnapshot for ReferenceSnapshotEngine<T> {
75    fn doc_ids(&self, table: &str) -> Result<Vec<DocId>, SQLError> {
76        self.0.live_table_doc_ids(table)
77    }
78    fn doc_id_page(
79        &self,
80        table: &str,
81        after: Option<DocId>,
82        limit: usize,
83        control: &uqa_storage::read_control::StorageReadControl,
84    ) -> Result<uqa_core::memory::BudgetedVec<DocId>, SQLError> {
85        uqa_execution::mutation::constraints::context::MutationRead::live_table_doc_id_page(
86            &*self.0, table, after, limit, control,
87        )
88    }
89    fn value_index_scan_key(
90        &self,
91        table: &str,
92        key: &uqa_storage::ValueIndexKey,
93        predicate: &uqa_core::Predicate,
94    ) -> Result<Option<uqa_core::PostingList>, SQLError> {
95        self.0.value_index_scan_key(table, key, predicate)
96    }
97    fn visit_value_index_equal(
98        &self,
99        table: &str,
100        key: &uqa_storage::ValueIndexKey,
101        value: &uqa_core::Value,
102        visit: &mut dyn FnMut(DocId) -> Result<(), SQLError>,
103    ) -> Result<bool, SQLError> {
104        self.0.visit_value_index_equal(table, key, value, visit)
105    }
106    fn document(
107        &self,
108        table: &str,
109        doc_id: DocId,
110    ) -> Result<Option<uqa_storage::document_store::Document>, SQLError> {
111        self.0.get_live_document(table, doc_id)
112    }
113    fn metadata(
114        &self,
115        table: &str,
116        doc_id: DocId,
117    ) -> Result<Option<uqa_storage::DocumentMetadata>, SQLError> {
118        self.0
119            .require_table(table)?
120            .document_store
121            .read()
122            .get_metadata(doc_id)
123            .map_err(|error| SQLError::Internal(format!("read reference tuple metadata: {error}")))
124    }
125}
126impl ReferentialSnapshots for Engine {
127    fn latest_reference_snapshot(&self) -> Result<Box<dyn ReferentialReadSnapshot + '_>, SQLError> {
128        let Some(backend) = self.storage.backend.as_ref() else {
129            return Ok(Box::new(ReferenceSnapshotEngine(self)));
130        };
131        if backend.transaction_has_written().map_err(|error| {
132            SQLError::Internal(format!("inspect reference snapshot transaction: {error}"))
133        })? {
134            Ok(Box::new(ReferenceSnapshotEngine(self)))
135        } else {
136            Ok(Box::new(ReferenceSnapshotEngine(
137                self.open_independent_pinned_read_snapshot()?,
138            )))
139        }
140    }
141    fn transaction_document_metadata(
142        &self,
143        table: &str,
144        doc_id: DocId,
145    ) -> Result<Option<uqa_storage::DocumentMetadata>, SQLError> {
146        self.get_query_document_metadata(table, doc_id)
147    }
148}