Skip to main content

uqa_execution/query/scope/
cte.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! CTE lifetime, visibility, and scalar-subquery arena scopes.
8
9use std::collections::{BTreeMap, BTreeSet};
10use std::sync::{atomic::Ordering, Arc};
11use uqa_sql::catalog::roles::RoleReference;
12
13use uqa_sql::plan::{CtePlan, QueryPlan};
14use uqa_sql::SQLError;
15
16use super::{CteScope, LockIdentityOptions};
17use uqa_sql::catalog::resolution::RelationLookupMode;
18
19impl<S: Clone> CteScope<S> {
20    pub fn command_cte_snapshot(&self) -> Option<std::sync::Arc<S>> {
21        self.command_cte_snapshot.clone()
22    }
23
24    pub fn set_command_cte_snapshot(&mut self, snapshot: Option<std::sync::Arc<S>>) {
25        self.command_cte_snapshot = snapshot;
26    }
27
28    /// Make this scope part of the statement whose commands `commands` holds.
29    pub fn set_statement_commands(&mut self, commands: std::sync::Arc<super::StatementCommands>) {
30        self.statement_commands = Some(commands);
31    }
32
33    /// The commands of the statement this scope belongs to.
34    pub fn statement_commands(&self) -> Option<&std::sync::Arc<super::StatementCommands>> {
35        self.statement_commands.as_ref()
36    }
37
38    /// Whether a command of the statement this scope belongs to wrote `row`. A later command finds the row's earlier version in its snapshot, which `PostgreSQL` reports as `TM_SelfModified` because the statement's command id already modified it.
39    pub fn statement_wrote(
40        &self,
41        row: &crate::mutation::candidate::PhysicalDocumentIdentity,
42    ) -> bool {
43        self.statement_commands
44            .as_ref()
45            .is_some_and(|commands| commands.wrote(row))
46    }
47
48    /// Whether a statement that the statement this scope belongs to started wrote `row`, which `PostgreSQL` finds modified under a later command id.
49    pub fn statement_triggered_write(
50        &self,
51        row: &crate::mutation::candidate::PhysicalDocumentIdentity,
52    ) -> bool {
53        self.statement_commands
54            .as_ref()
55            .is_some_and(|commands| commands.triggered_write(row))
56    }
57
58    pub fn inherit_cte_bindings(&mut self, parent: &Self) {
59        self.rows.clone_from(&parent.rows);
60        self.deferred_ctes.clone_from(&parent.deferred_ctes);
61        self.definition_scopes.clone_from(&parent.definition_scopes);
62        self.folded_ctes.clone_from(&parent.folded_ctes);
63        self.non_returning_ctes
64            .clone_from(&parent.non_returning_ctes);
65        self.visible_cte_names.clone_from(&parent.visible_cte_names);
66        self.recursive_control_widths
67            .clone_from(&parent.recursive_control_widths);
68        self.command_cte_snapshot
69            .clone_from(&parent.command_cte_snapshot);
70        self.statement_commands
71            .clone_from(&parent.statement_commands);
72        if self.privilege_subject.is_none() {
73            self.privilege_subject.clone_from(&parent.privilege_subject);
74        }
75    }
76
77    /// Override only relation privilege checks while preserving SQL-visible `current_user` and the caller's namespace.
78    pub fn enter_privilege_subject(
79        &mut self,
80        subject: RoleReference,
81    ) -> PrivilegeSubjectScope<'_, S> {
82        let previous = self.privilege_subject.replace(subject);
83        PrivilegeSubjectScope {
84            ctes: self,
85            previous,
86        }
87    }
88
89    /// Select the namespace semantics owned by one query plan and restore the parent plan's mode on every exit path.
90    pub fn enter_relation_lookup_mode(
91        &mut self,
92        relations_bound: bool,
93    ) -> Result<RelationLookupScope<'_, S>, SQLError> {
94        let resolution = self.catalog_resolution.as_mut().ok_or_else(|| {
95            SQLError::Internal(
96                "query execution scope has no statement name-resolution snapshot".into(),
97            )
98        })?;
99        let lookup_mode = if relations_bound {
100            RelationLookupMode::Bound
101        } else {
102            RelationLookupMode::Dynamic
103        };
104        let previous = resolution.set_lookup_mode(lookup_mode);
105        Ok(RelationLookupScope {
106            ctes: self,
107            previous,
108        })
109    }
110
111    /// Enter the namespace and relation authority retained by one query, including rewritten inputs nested under a different statement owner.
112    pub fn enter_query_plan_scope(
113        &mut self,
114        plan: &QueryPlan,
115    ) -> Result<QueryPlanScope<'_, S>, SQLError> {
116        let mut lookup = self.enter_relation_lookup_mode(plan.relations_bound)?;
117        let previous_subject = match &plan.relation_privilege_subject {
118            Some(subject) => {
119                QueryPrivilege::Restore(lookup.privilege_subject.replace(subject.clone()))
120            }
121            None => QueryPrivilege::Unchanged,
122        };
123        Ok(QueryPlanScope {
124            lookup,
125            previous_subject,
126        })
127    }
128
129    pub fn insert_shared(&mut self, name: String, rows: crate::SharedSpill) {
130        self.insert_rows(name, crate::query::cte::rows::CteRows::Complete(rows));
131    }
132
133    pub fn insert_rows(&mut self, name: String, rows: crate::query::cte::rows::CteRows) {
134        self.deferred_ctes.remove(&name);
135        self.definition_scopes.remove(&name);
136        self.folded_ctes.remove(&name);
137        self.non_returning_ctes.remove(&name);
138        self.rows.insert(name, rows);
139    }
140
141    pub fn insert_deferred(&mut self, plan: uqa_sql::plan::RetainedCtePlan) {
142        self.insert_preparation_cte(plan, true);
143    }
144
145    pub fn remove_deferred(&mut self, name: &str) -> Option<uqa_sql::plan::RetainedCtePlan> {
146        self.non_returning_ctes.remove(name);
147        self.definition_scopes.remove(name);
148        self.folded_ctes.remove(name);
149        self.deferred_ctes.remove(name)
150    }
151
152    /// Return a folded definition without consuming its lexical binding. A single syntactic reference can be built again by a recursive working-table iteration or a correlated consumer. Materialized producers replace the definition explicitly when installed.
153    pub fn deferred_for_scan(&self, name: &str) -> Option<CtePlan> {
154        let name = uqa_sql::semantics::cte_reference_name(name)?;
155        self.deferred_ctes.get(&name).map(|plan| (**plan).clone())
156    }
157
158    pub fn materialized_for_scan(
159        &self,
160        reference: &str,
161    ) -> Option<crate::query::cte::rows::CteRows> {
162        self.rows
163            .get(&uqa_sql::semantics::cte_reference_name(reference)?)
164            .cloned()
165    }
166
167    pub fn deferred_reference(&self, reference: &str) -> Option<&CtePlan> {
168        self.deferred_ctes
169            .get(&uqa_sql::semantics::cte_reference_name(reference)?)
170            .map(AsRef::as_ref)
171    }
172
173    pub fn deferred_ctes(&self) -> &BTreeMap<String, uqa_sql::plan::RetainedCtePlan> {
174        &self.deferred_ctes
175    }
176
177    pub fn recursive_control_width(&self, name: &str) -> Option<usize> {
178        self.recursive_control_widths.get(name).copied()
179    }
180
181    pub fn set_recursive_control_width(&mut self, name: String, width: usize) -> Option<usize> {
182        self.recursive_control_widths.insert(name, width)
183    }
184
185    pub fn restore_recursive_control_width(&mut self, name: &str, previous: Option<usize>) {
186        match previous {
187            Some(width) => {
188                self.recursive_control_widths
189                    .insert(name.to_string(), width);
190            }
191            None => {
192                self.recursive_control_widths.remove(name);
193            }
194        }
195    }
196
197    pub fn remove_materialized(&mut self, name: &str) -> Option<crate::query::cte::rows::CteRows> {
198        self.non_returning_ctes.remove(name);
199        self.rows.remove(name)
200    }
201
202    /// Enter a query block's scalar arena and the outer substitutions owned by its FROM expressions.
203    pub fn enter_query_block(
204        &mut self,
205        block: &uqa_sql::plan::QueryBlockPlan,
206    ) -> ScalarSubqueryScope<'_, S> {
207        let mut scope = self.enter_scalar_subqueries(&block.subqueries);
208        scope.source_outer_rewrites = (!block.deferred_outer_rewrites.is_empty())
209            .then(|| block.deferred_outer_rewrites.as_slice().into());
210        scope
211    }
212
213    /// Bind the scalar-subquery arena owned by one query block. The guard restores the parent arena and correlated row binding on success, error, or panic so nested and lateral query execution cannot resolve a child slot in its parent.
214    pub fn enter_scalar_subqueries(
215        &mut self,
216        subqueries: &[QueryPlan],
217    ) -> ScalarSubqueryScope<'_, S> {
218        let previous = std::mem::replace(&mut self.scalar_subqueries, subqueries.into());
219        let next_arena = self
220            .next_scalar_subquery_arena
221            .fetch_add(1, Ordering::Relaxed);
222        let previous_arena = std::mem::replace(&mut self.scalar_subquery_arena, next_arena);
223        let previous_lock_identities = self.lock_identities;
224        let previous_outer_row = self.outer_row_binding();
225        let previous_source_rewrites = self.source_outer_rewrites.clone();
226        ScalarSubqueryScope {
227            ctes: self,
228            previous: Some(previous),
229            previous_arena,
230            previous_lock_identities,
231            previous_outer_row,
232            previous_source_rewrites,
233        }
234    }
235
236    pub fn enter_visible_ctes<'a>(
237        &'a mut self,
238        names: impl IntoIterator<Item = &'a str>,
239    ) -> VisibleCteScope<'a, S> {
240        let previous = std::mem::take(&mut self.visible_cte_names);
241        self.visible_cte_names.clone_from(&previous);
242        self.visible_cte_names
243            .extend(names.into_iter().map(str::to_owned));
244        VisibleCteScope {
245            ctes: self,
246            previous: Some(previous),
247        }
248    }
249
250    /// Whether `name` resolves to a CTE in this scope: a name declared by an enclosing query's WITH list, or one whose rows or deferred plan are bound in the scope, which is how a DML statement's own WITH list reaches the query it drives.
251    pub fn is_visible_cte(&self, name: &str) -> bool {
252        uqa_sql::semantics::cte_reference_name(name)
253            .is_some_and(|name| self.contains_cte_name(&name))
254    }
255
256    /// Test an already decoded, unqualified identifier without applying SQL name parsing a second time.
257    pub fn contains_cte_name(&self, name: &str) -> bool {
258        self.visible_cte_names.contains(name)
259            || self.rows.contains_key(name)
260            || self.deferred_ctes.contains_key(name)
261    }
262
263    pub fn returning_statement_snapshot_scope(&self) -> Self {
264        let mut scope = self.clone();
265        scope.read_command_overlay = false;
266        scope
267    }
268
269    pub fn reads_command_overlay(&self) -> bool {
270        self.read_command_overlay
271    }
272
273    pub fn enable_command_progress_streaming(&mut self) {
274        self.stream_command_progress = true;
275    }
276
277    pub fn streams_command_progress(&self) -> bool {
278        self.stream_command_progress
279    }
280
281    pub fn enable_backwards_scanning(&mut self) {
282        self.scan_backwards = true;
283    }
284
285    pub fn scans_backwards(&self) -> bool {
286        self.scan_backwards
287    }
288}
289
290pub struct PrivilegeSubjectScope<'a, S: Clone> {
291    ctes: &'a mut CteScope<S>,
292    previous: Option<RoleReference>,
293}
294
295impl<S: Clone> std::ops::Deref for PrivilegeSubjectScope<'_, S> {
296    type Target = CteScope<S>;
297
298    fn deref(&self) -> &Self::Target {
299        self.ctes
300    }
301}
302
303impl<S: Clone> std::ops::DerefMut for PrivilegeSubjectScope<'_, S> {
304    fn deref_mut(&mut self) -> &mut Self::Target {
305        self.ctes
306    }
307}
308
309impl<S: Clone> Drop for PrivilegeSubjectScope<'_, S> {
310    fn drop(&mut self) {
311        self.ctes.privilege_subject = self.previous.take();
312    }
313}
314
315pub struct RelationLookupScope<'a, S: Clone> {
316    ctes: &'a mut CteScope<S>,
317    previous: RelationLookupMode,
318}
319
320impl<S: Clone> std::ops::Deref for RelationLookupScope<'_, S> {
321    type Target = CteScope<S>;
322
323    fn deref(&self) -> &Self::Target {
324        self.ctes
325    }
326}
327
328impl<S: Clone> std::ops::DerefMut for RelationLookupScope<'_, S> {
329    fn deref_mut(&mut self) -> &mut Self::Target {
330        self.ctes
331    }
332}
333
334impl<S: Clone> Drop for RelationLookupScope<'_, S> {
335    fn drop(&mut self) {
336        let resolution = self
337            .ctes
338            .catalog_resolution
339            .as_mut()
340            .expect("relation lookup scope lost its statement resolution");
341        resolution.set_lookup_mode(self.previous);
342    }
343}
344
345pub struct QueryPlanScope<'a, S: Clone> {
346    lookup: RelationLookupScope<'a, S>,
347    previous_subject: QueryPrivilege,
348}
349
350enum QueryPrivilege {
351    Unchanged,
352    Restore(Option<RoleReference>),
353}
354
355impl<S: Clone> std::ops::Deref for QueryPlanScope<'_, S> {
356    type Target = CteScope<S>;
357    fn deref(&self) -> &Self::Target {
358        &self.lookup
359    }
360}
361
362impl<S: Clone> std::ops::DerefMut for QueryPlanScope<'_, S> {
363    fn deref_mut(&mut self) -> &mut Self::Target {
364        &mut self.lookup
365    }
366}
367
368impl<S: Clone> Drop for QueryPlanScope<'_, S> {
369    fn drop(&mut self) {
370        if let QueryPrivilege::Restore(previous) = &mut self.previous_subject {
371            self.lookup.privilege_subject = previous.take();
372        }
373    }
374}
375
376pub struct ScalarSubqueryScope<'a, S: Clone> {
377    ctes: &'a mut CteScope<S>,
378    previous: Option<Arc<[QueryPlan]>>,
379    previous_arena: u64,
380    previous_lock_identities: LockIdentityOptions,
381    previous_outer_row: Option<Arc<crate::OwnedPhysicalRow>>,
382    previous_source_rewrites: Option<Arc<[uqa_sql::semantics::view_rewrite::DeferredOuterRewrite]>>,
383}
384
385impl<S: Clone> std::ops::Deref for ScalarSubqueryScope<'_, S> {
386    type Target = CteScope<S>;
387
388    fn deref(&self) -> &Self::Target {
389        self.ctes
390    }
391}
392
393impl<S: Clone> std::ops::DerefMut for ScalarSubqueryScope<'_, S> {
394    fn deref_mut(&mut self) -> &mut Self::Target {
395        self.ctes
396    }
397}
398
399impl<S: Clone> Drop for ScalarSubqueryScope<'_, S> {
400    fn drop(&mut self) {
401        if let Some(previous) = self.previous.take() {
402            self.ctes.scalar_subqueries = previous;
403            self.ctes.scalar_subquery_arena = self.previous_arena;
404            self.ctes.lock_identities = self.previous_lock_identities;
405            self.ctes
406                .restore_outer_row_binding(self.previous_outer_row.take());
407            self.ctes.source_outer_rewrites = std::mem::take(&mut self.previous_source_rewrites);
408        }
409    }
410}
411
412pub struct VisibleCteScope<'a, S: Clone> {
413    ctes: &'a mut CteScope<S>,
414    previous: Option<BTreeSet<String>>,
415}
416
417impl<S: Clone> std::ops::Deref for VisibleCteScope<'_, S> {
418    type Target = CteScope<S>;
419
420    fn deref(&self) -> &Self::Target {
421        self.ctes
422    }
423}
424
425impl<S: Clone> std::ops::DerefMut for VisibleCteScope<'_, S> {
426    fn deref_mut(&mut self) -> &mut Self::Target {
427        self.ctes
428    }
429}
430
431impl<S: Clone> Drop for VisibleCteScope<'_, S> {
432    fn drop(&mut self) {
433        if let Some(previous) = self.previous.take() {
434            self.ctes.visible_cte_names = previous;
435        }
436    }
437}