Skip to main content

uqa_execution/query/
scope.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Statement-scoped CTE buffers, subquery arenas, and tuple recheck state.
8
9use crate::catalog::CatalogReadView;
10use crate::row_locks::recheck::{
11    recheck_storage_names_match, RecheckDoc, RecheckSourceRow, RowLockRecheckPins,
12};
13use std::collections::{BTreeMap, BTreeSet};
14use std::sync::{atomic::AtomicU64, Arc};
15use uqa_sql::catalog::resolution::{RelationLookupMode, RelationNameResolution};
16use uqa_sql::catalog::roles::RoleReference;
17use uqa_sql::plan::QueryPlan;
18use uqa_sql::SQLError;
19
20pub(crate) mod binding;
21mod cte;
22mod definitions;
23mod producers;
24#[cfg(test)]
25mod retained_plans;
26mod row_locks;
27mod statement_commands;
28pub mod subqueries;
29use row_locks::RowLockScopeState;
30pub use row_locks::{LockIdentityOptions, ResolvedRowLock};
31pub use statement_commands::StatementCommands;
32use subqueries::ScalarSubqueryCacheEntry;
33
34#[derive(Clone)]
35pub struct CteScope<S: Clone = ()> {
36    producers: producers::CteProducers,
37    pub rows: BTreeMap<String, crate::query::cte::rows::CteRows>,
38    deferred_ctes: BTreeMap<String, uqa_sql::plan::RetainedCtePlan>,
39    definition_scopes: BTreeMap<String, Arc<definitions::DefinitionBindings>>,
40    folded_ctes: BTreeSet<String>,
41    pub non_returning_ctes: BTreeSet<String>,
42    pub scalar_subqueries: Arc<[QueryPlan]>,
43    pub(crate) source_outer_rewrites:
44        Option<Arc<[uqa_sql::semantics::view_rewrite::DeferredOuterRewrite]>>,
45    pub lock_identities: LockIdentityOptions,
46    row_lock: Option<Box<RowLockScopeState>>,
47    visible_cte_names: BTreeSet<String>,
48    recursive_control_widths: BTreeMap<String, usize>,
49    scalar_subquery_arena: u64,
50    read_command_overlay: bool,
51    stream_command_progress: bool,
52    scan_backwards: bool,
53    next_scalar_subquery_arena: Arc<AtomicU64>,
54    scalar_subquery_cache:
55        Arc<parking_lot::Mutex<BTreeMap<(u64, usize), ScalarSubqueryCacheEntry>>>,
56    catalog: Option<CatalogReadView>,
57    catalog_revision: Option<(u64, u64)>,
58    catalog_resolution: Option<RelationNameResolution>,
59    privilege_subject: Option<RoleReference>,
60    command_cte_snapshot: Option<Arc<S>>,
61    /// The commands of the statement this scope belongs to, shared by every scope of the statement.
62    statement_commands: Option<Arc<StatementCommands>>,
63}
64
65impl<S: Clone> Default for CteScope<S> {
66    fn default() -> Self {
67        Self {
68            producers: producers::CteProducers::default(),
69            rows: BTreeMap::new(),
70            deferred_ctes: BTreeMap::new(),
71            definition_scopes: BTreeMap::new(),
72            folded_ctes: BTreeSet::new(),
73            non_returning_ctes: BTreeSet::new(),
74            scalar_subqueries: Arc::default(),
75            source_outer_rewrites: None,
76            lock_identities: LockIdentityOptions::default(),
77            row_lock: None,
78            visible_cte_names: BTreeSet::new(),
79            recursive_control_widths: BTreeMap::new(),
80            scalar_subquery_arena: 0,
81            read_command_overlay: true,
82            stream_command_progress: false,
83            scan_backwards: false,
84            next_scalar_subquery_arena: Arc::new(AtomicU64::new(1)),
85            scalar_subquery_cache: Arc::new(parking_lot::Mutex::new(BTreeMap::new())),
86            catalog: None,
87            catalog_revision: None,
88            catalog_resolution: None,
89            privilege_subject: None,
90            command_cte_snapshot: None,
91            statement_commands: None,
92        }
93    }
94}
95
96impl<S: Clone> CteScope<S> {
97    /// Bind immutable statement metadata while keeping the snapshot payload owned by the caller.
98    pub fn with_catalog(
99        catalog: CatalogReadView,
100        resolution: RelationNameResolution,
101        privilege_subject: Option<RoleReference>,
102    ) -> Self {
103        Self {
104            catalog: Some(catalog),
105            catalog_resolution: Some(resolution),
106            privilege_subject,
107            ..Self::default()
108        }
109    }
110
111    pub fn set_reads_command_overlay(&mut self, enabled: bool) {
112        self.read_command_overlay = enabled;
113    }
114
115    pub fn set_relation_lookup_mode(&mut self, mode: RelationLookupMode) -> Result<(), SQLError> {
116        self.catalog_resolution
117            .as_mut()
118            .ok_or_else(|| {
119                SQLError::Internal(
120                    "query execution scope has no statement name-resolution snapshot".into(),
121                )
122            })?
123            .set_lookup_mode(mode);
124        Ok(())
125    }
126
127    pub fn cached_subquery(&self, slot: usize) -> Option<ScalarSubqueryCacheEntry> {
128        self.scalar_subquery_cache
129            .lock()
130            .get(&(self.scalar_subquery_arena, slot))
131            .cloned()
132    }
133
134    pub fn cache_subquery(&self, slot: usize, entry: ScalarSubqueryCacheEntry) {
135        self.scalar_subquery_cache
136            .lock()
137            .insert((self.scalar_subquery_arena, slot), entry);
138    }
139
140    pub fn new() -> Self {
141        Self::default()
142    }
143
144    pub fn catalog_read_view(&self) -> Result<CatalogReadView, SQLError> {
145        self.catalog.clone().ok_or_else(|| {
146            SQLError::Internal("query execution scope has no statement catalog snapshot".into())
147        })
148    }
149
150    /// Record the caller's source identity and invalidation revision when it captures the catalog, independently of the immutable binding view.
151    pub fn set_catalog_revision(&mut self, source: u64, revision: u64) {
152        self.catalog_revision = Some((source, revision));
153    }
154
155    pub fn catalog_revision(&self) -> Option<(u64, u64)> {
156        self.catalog_revision
157    }
158
159    pub fn relation_name_resolution(&self) -> Result<RelationNameResolution, SQLError> {
160        self.catalog_resolution.clone().ok_or_else(|| {
161            SQLError::Internal(
162                "query execution scope has no statement name-resolution snapshot".into(),
163            )
164        })
165    }
166
167    pub(crate) fn relation_lookup_mode(
168        &self,
169    ) -> Option<uqa_sql::catalog::resolution::RelationLookupMode> {
170        self.catalog_resolution
171            .as_ref()
172            .map(|resolution| resolution.lookup_mode)
173    }
174
175    pub fn privilege_subject(&self) -> Result<&RoleReference, SQLError> {
176        if let Some(subject) = self.privilege_subject.as_ref() {
177            return Ok(subject);
178        }
179        self.catalog_resolution
180            .as_ref()
181            .map(RelationNameResolution::current_user)
182            .ok_or_else(|| {
183                SQLError::Internal(
184                    "query execution scope has no statement authorization subject".into(),
185                )
186            })
187    }
188}
189
190pub use uqa_sql::semantics::expr_contains_subquery;
191
192#[cfg(test)]
193mod tests {
194    use super::{expr_contains_subquery, CteScope};
195    use crate::ScalarExpr;
196    use crate::ScalarFrameBound;
197    use uqa_sql::ast::{FrameExclusion, FrameMode};
198
199    #[test]
200    fn query_scope_restores_relation_authority_and_namespace_after_unwind() {
201        use uqa_sql::catalog::resolution::{RelationLookupMode, RelationNameResolution};
202        let uqa_sql::plan::UnifiedPlan::Query(mut query) =
203            uqa_sql::plan::UnifiedPlan::lower(uqa_sql::compile("SELECT 1").unwrap().remove(0))
204        else {
205            panic!("query")
206        };
207        query.relation_privilege_subject = Some("caller".into());
208        let mut scope = CteScope::<()>::new();
209        scope.privilege_subject = Some("action_owner".into());
210        scope.catalog_resolution = Some(RelationNameResolution {
211            search_path: vec!["public".into()],
212            temporary_schema: "pg_temp_1".into(),
213            temporary_namespace_allocated: false,
214            current_user: "caller".into(),
215            lookup_mode: RelationLookupMode::Bound,
216        });
217        let unwind = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
218            let current = scope.enter_query_plan_scope(&query).unwrap();
219            assert_eq!(current.privilege_subject().unwrap(), &"caller".into());
220            let resolution = current.relation_name_resolution().unwrap();
221            assert_eq!(resolution.lookup_mode, RelationLookupMode::Dynamic);
222            assert_eq!(resolution.current_user, "caller".into());
223            panic!("query failed while retaining caller authority");
224        }));
225        assert!(unwind.is_err());
226        assert_eq!(scope.privilege_subject().unwrap(), &"action_owner".into());
227        assert_eq!(
228            scope.relation_name_resolution().unwrap().lookup_mode,
229            RelationLookupMode::Bound
230        );
231    }
232
233    #[test]
234    fn empty_row_lock_scopes_leave_non_locking_state_unallocated() {
235        let mut ctes = CteScope::<()>::new();
236        {
237            let _scope = ctes.enter_source_row_locks(Vec::new());
238        }
239        assert!(ctes.row_lock.is_none());
240        {
241            let _scope = ctes.enter_recheck_storage_pins("plain_source");
242        }
243        assert!(ctes.row_lock.is_none());
244    }
245
246    #[test]
247    fn scalar_ir_detects_subqueries_in_window_frame_bounds() {
248        let expression = ScalarExpr::WindowCall {
249            name: "sum".into(),
250            args: vec![ScalarExpr::Column("amount".into())],
251            spec: crate::ScalarWindowSpec {
252                definition: None,
253                partition_by: Vec::new(),
254                order_by: Vec::new(),
255                frame: Some(crate::ScalarWindowFrame {
256                    mode: FrameMode::Rows,
257                    start: ScalarFrameBound::Preceding(Box::new(ScalarExpr::ScalarSubquery(0))),
258                    end: ScalarFrameBound::CurrentRow,
259                    between: true,
260                    exclusion: FrameExclusion::NoOthers,
261                }),
262            },
263            filter: None,
264            modifiers: uqa_sql::ast::WindowCallModifiers::default(),
265        };
266        assert!(expr_contains_subquery(&expression));
267    }
268    #[test]
269    fn scalar_subquery_scope_restores_the_parent_arena_after_unwind() {
270        use uqa_sql::plan::UnifiedPlan;
271
272        let statement = uqa_sql::compile("SELECT 1")
273            .unwrap()
274            .into_iter()
275            .next()
276            .unwrap();
277        let UnifiedPlan::Query(query) = UnifiedPlan::lower(statement) else {
278            panic!("SELECT must lower to a query plan");
279        };
280        let query = *query;
281        let mut scope = CteScope::<()>::new();
282        scope.scalar_subqueries = vec![query.clone()].into();
283
284        let unwind = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
285            let _guard = scope.enter_scalar_subqueries(&[query.clone(), query]);
286            panic!("exercise scalar-subquery scope cleanup");
287        }));
288
289        assert!(unwind.is_err());
290        assert_eq!(scope.scalar_subqueries.len(), 1);
291    }
292}
293
294pub mod bindings;