Skip to main content

uqa_execution/mutation/referential/
context.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Capabilities for referential action preparation and tuple rechecks.
8use crate::{
9    mutation::{
10        assignment::MutationAssignmentContext, constraints::ConstraintContext,
11        identity::MutationIdentifiers, triggers::context::TriggerContext,
12    },
13    query::locking::context::RowLockContext,
14};
15use uqa_core::DocId;
16use uqa_sql::{ast::ForeignKey, SQLError};
17/// Retained latest row images used only for referential checks under a fixed transaction snapshot.
18pub trait ReferentialReadSnapshot {
19    fn doc_ids(&self, table: &str) -> Result<Vec<DocId>, SQLError>;
20    fn doc_id_page(
21        &self,
22        table: &str,
23        after: Option<DocId>,
24        limit: usize,
25        control: &uqa_storage::read_control::StorageReadControl,
26    ) -> Result<uqa_core::memory::BudgetedVec<DocId>, SQLError>;
27    /// Probe the same retained row generation used by this snapshot's document reads.
28    fn value_index_scan_key(
29        &self,
30        table: &str,
31        key: &uqa_storage::ValueIndexKey,
32        predicate: &uqa_core::Predicate,
33    ) -> Result<Option<uqa_core::PostingList>, SQLError>;
34    fn visit_value_index_equal(
35        &self,
36        table: &str,
37        key: &uqa_storage::ValueIndexKey,
38        value: &uqa_core::Value,
39        visit: &mut dyn FnMut(DocId) -> Result<(), SQLError>,
40    ) -> Result<bool, SQLError>;
41    fn document(
42        &self,
43        table: &str,
44        doc_id: DocId,
45    ) -> Result<Option<uqa_storage::document_store::Document>, SQLError>;
46    fn metadata(
47        &self,
48        table: &str,
49        doc_id: DocId,
50    ) -> Result<Option<uqa_storage::DocumentMetadata>, SQLError>;
51}
52pub trait ReferentialSnapshots {
53    fn latest_reference_snapshot(&self) -> Result<Box<dyn ReferentialReadSnapshot + '_>, SQLError>;
54    fn transaction_document_metadata(
55        &self,
56        table: &str,
57        doc_id: DocId,
58    ) -> Result<Option<uqa_storage::DocumentMetadata>, SQLError>;
59}
60/// The deferral of the checks a change to a referenced row fires, under the constraint `derived` names when the foreign key derives one on the firing partition.
61pub trait ReferentialDeferrals {
62    fn defer_foreign_key_check(
63        &self,
64        constraint_table: &str,
65        firing_table: &str,
66        row: (&str, DocId),
67        foreign_key: &ForeignKey,
68        derived: Option<&uqa_sql::ast::ReferencedPartitionConstraint>,
69        values: std::sync::Arc<[uqa_core::Value]>,
70    ) -> Result<(), SQLError>;
71    fn defer_foreign_key_parent_event(
72        &self,
73        constraint_table: &str,
74        firing_table: &str,
75        foreign_key: &ForeignKey,
76        derived: Option<&uqa_sql::ast::ReferencedPartitionConstraint>,
77    ) -> Result<(), SQLError>;
78}
79#[derive(Clone)]
80pub struct ReferentialContext<'a, S: Clone + 'static> {
81    pub constraints: ConstraintContext<'a>,
82    pub locking: RowLockContext<'a, S>,
83    pub assignment: MutationAssignmentContext<'a, S>,
84    pub identifiers: &'a dyn MutationIdentifiers,
85    pub triggers: TriggerContext<'a>,
86    pub deferrals: &'a dyn ReferentialDeferrals,
87    pub snapshots: &'a dyn ReferentialSnapshots,
88}
89impl<S: Clone + 'static> Copy for ReferentialContext<'_, S> {}