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::sync::{atomic::Ordering, Arc};
10use uqa_sql::binding::production::{BindingMap, BindingNameSet};
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.inherit_cte_bindings_with_control(
60            parent,
61            &uqa_core::memory::ProductionControl::uncontrolled(),
62        )
63        .expect("ordinary inherited CTE bindings");
64    }
65
66    /// Admit every private lexical destination before replacing any part of the child scope. Statement and immutable definition owners remain shared with the parent.
67    pub fn inherit_cte_bindings_with_control(
68        &mut self,
69        parent: &Self,
70        control: &uqa_core::memory::ProductionControl<'_>,
71    ) -> Result<(), SQLError> {
72        control.check()?;
73        let rows = parent.rows.copy_with_control(control)?;
74        let deferred = parent
75            .deferred_ctes
76            .copy_with_control(control, |plan| Ok(plan.clone()))?;
77        let definitions = parent
78            .definition_scopes
79            .copy_with_control(control, |definition| Ok(Arc::clone(definition)))?;
80        let folded = parent.folded_ctes.copy_with_control(control)?;
81        let non_returning = parent.non_returning_ctes.copy_with_control(control)?;
82        let visible = parent.visible_cte_names.copy_with_control(control)?;
83        let widths = parent
84            .recursive_control_widths
85            .copy_with_control(control, |width| Ok(*width))?;
86        control.check()?;
87        self.rows = rows;
88        self.deferred_ctes = deferred;
89        self.definition_scopes = definitions;
90        self.folded_ctes = folded;
91        self.non_returning_ctes = non_returning;
92        self.visible_cte_names = visible;
93        self.recursive_control_widths = widths;
94        self.command_cte_snapshot
95            .clone_from(&parent.command_cte_snapshot);
96        self.statement_commands
97            .clone_from(&parent.statement_commands);
98        if self.privilege_subject.is_none() {
99            self.privilege_subject.clone_from(&parent.privilege_subject);
100        }
101        Ok(())
102    }
103
104    /// Override only relation privilege checks while preserving SQL-visible `current_user` and the caller's namespace.
105    pub fn enter_privilege_subject(
106        &mut self,
107        subject: RoleReference,
108    ) -> PrivilegeSubjectScope<'_, S> {
109        let previous = self.privilege_subject.replace(subject.into());
110        PrivilegeSubjectScope {
111            ctes: self,
112            previous,
113        }
114    }
115
116    /// Transfer an admitted authority reference with its original lease before publishing the override. Child scopes share that owner after this guard restores its parent.
117    pub fn enter_privilege_subject_with_control(
118        &mut self,
119        subject: uqa_core::memory::Produced<RoleReference>,
120        control: &uqa_core::memory::ProductionControl<'_>,
121    ) -> Result<PrivilegeSubjectScope<'_, S>, SQLError> {
122        let subject = super::production::subject::ScopeSubject::from_produced(subject, control)?;
123        let previous = self.privilege_subject.replace(subject);
124        Ok(PrivilegeSubjectScope {
125            ctes: self,
126            previous,
127        })
128    }
129
130    /// Select the namespace semantics owned by one query plan and restore the parent plan's mode on every exit path.
131    pub fn enter_relation_lookup_mode(
132        &mut self,
133        relations_bound: bool,
134    ) -> Result<RelationLookupScope<'_, S>, SQLError> {
135        let resolution = self.catalog_resolution.as_mut().ok_or_else(|| {
136            SQLError::Internal(
137                "query execution scope has no statement name-resolution snapshot".into(),
138            )
139        })?;
140        let lookup_mode = if relations_bound {
141            RelationLookupMode::Bound
142        } else {
143            RelationLookupMode::Dynamic
144        };
145        let previous = resolution.set_lookup_mode(lookup_mode);
146        Ok(RelationLookupScope {
147            ctes: self,
148            previous,
149        })
150    }
151
152    /// Enter the namespace and relation authority retained by one query, including rewritten inputs nested under a different statement owner.
153    pub fn enter_query_plan_scope(
154        &mut self,
155        plan: &QueryPlan,
156    ) -> Result<QueryPlanScope<'_, S>, SQLError> {
157        self.enter_query_plan_scope_with_control(
158            plan,
159            &uqa_core::memory::ProductionControl::uncontrolled(),
160        )
161    }
162
163    pub fn enter_query_plan_scope_with_control(
164        &mut self,
165        plan: &QueryPlan,
166        control: &uqa_core::memory::ProductionControl<'_>,
167    ) -> Result<QueryPlanScope<'_, S>, SQLError> {
168        let mut lookup = self.enter_relation_lookup_mode(plan.relations_bound)?;
169        let previous_subject = match &plan.relation_privilege_subject {
170            Some(subject) => {
171                let subject = super::production::subject::ScopeSubject::capture(subject, control)?;
172                QueryPrivilege::Restore(lookup.privilege_subject.replace(subject))
173            }
174            None => QueryPrivilege::Unchanged,
175        };
176        Ok(QueryPlanScope {
177            lookup,
178            previous_subject,
179        })
180    }
181
182    pub fn insert_shared(&mut self, name: String, rows: crate::SharedSpill) {
183        self.insert_rows(name, crate::query::cte::rows::CteRows::Complete(rows));
184    }
185
186    pub fn insert_rows(&mut self, name: String, rows: crate::query::cte::rows::CteRows) {
187        self.deferred_ctes.remove(&name);
188        self.definition_scopes.remove(&name);
189        self.folded_ctes.remove(&name);
190        self.non_returning_ctes.remove(&name);
191        self.rows.insert(name, rows);
192    }
193
194    pub fn insert_deferred(&mut self, plan: uqa_sql::plan::RetainedCtePlan) {
195        self.insert_preparation_cte(plan, true);
196    }
197
198    pub fn remove_deferred(&mut self, name: &str) -> Option<uqa_sql::plan::RetainedCtePlan> {
199        self.non_returning_ctes.remove(name);
200        self.definition_scopes.remove(name);
201        self.folded_ctes.remove(name);
202        self.deferred_ctes.remove(name)
203    }
204
205    /// 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.
206    pub fn deferred_for_scan(&self, name: &str) -> Option<uqa_sql::plan::RetainedCtePlan> {
207        let reference = uqa_core::RelationIdentity::borrowed_reference(name)?;
208        (reference.schema.is_none())
209            .then(|| self.deferred_ctes.get_name(reference.name).cloned())
210            .flatten()
211    }
212
213    pub fn materialized_for_scan(
214        &self,
215        reference: &str,
216    ) -> Option<crate::query::cte::rows::CteRows> {
217        let reference = uqa_core::RelationIdentity::borrowed_reference(reference)?;
218        (reference.schema.is_none())
219            .then(|| self.rows.get_name(reference.name).cloned())
220            .flatten()
221    }
222
223    pub fn deferred_reference(&self, reference: &str) -> Option<&CtePlan> {
224        let reference = uqa_core::RelationIdentity::borrowed_reference(reference)?;
225        (reference.schema.is_none())
226            .then(|| {
227                self.deferred_ctes
228                    .get_name(reference.name)
229                    .map(AsRef::as_ref)
230            })
231            .flatten()
232    }
233
234    pub fn deferred_ctes(&self) -> &BindingMap<uqa_sql::plan::RetainedCtePlan> {
235        &self.deferred_ctes
236    }
237
238    pub fn recursive_control_width(&self, name: &str) -> Option<usize> {
239        self.recursive_control_widths.get(name).copied()
240    }
241
242    pub fn set_recursive_control_width(&mut self, name: String, width: usize) -> Option<usize> {
243        self.recursive_control_widths.insert(name, width)
244    }
245
246    pub fn restore_recursive_control_width(&mut self, name: &str, previous: Option<usize>) {
247        match previous {
248            Some(width) => {
249                self.recursive_control_widths
250                    .insert(name.to_string(), width);
251            }
252            None => {
253                self.recursive_control_widths.remove(name);
254            }
255        }
256    }
257
258    pub fn remove_materialized(&mut self, name: &str) -> Option<crate::query::cte::rows::CteRows> {
259        self.non_returning_ctes.remove(name);
260        self.rows.remove(name)
261    }
262
263    /// Enter a query block's scalar arena and the outer substitutions owned by its FROM expressions.
264    pub fn enter_query_block(
265        &mut self,
266        block: &uqa_sql::plan::QueryBlockPlan,
267    ) -> ScalarSubqueryScope<'_, S> {
268        self.enter_query_block_with_control(
269            block,
270            &uqa_core::memory::ProductionControl::uncontrolled(),
271        )
272        .expect("ordinary query-block scope")
273    }
274
275    /// Construct both private destinations before installing either, so admission failure leaves the complete parent namespace intact.
276    pub fn enter_query_block_with_control(
277        &mut self,
278        block: &uqa_sql::plan::QueryBlockPlan,
279        control: &uqa_core::memory::ProductionControl<'_>,
280    ) -> Result<ScalarSubqueryScope<'_, S>, SQLError> {
281        let arena = uqa_sql::plan::RetainedQueryArena::capture(&block.subqueries, control)?;
282        let rewrites = if block.deferred_outer_rewrites.is_empty() {
283            None
284        } else {
285            let mut rewrites = uqa_core::memory::ProductionVec::new(*control);
286            rewrites.reserve(block.deferred_outer_rewrites.len())?;
287            for rewrite in &block.deferred_outer_rewrites {
288                rewrites.push_produced(rewrite.clone_with_control(control)?)?;
289            }
290            Some(rewrites.finish()?.into_shared(control)?)
291        };
292        control.check()?;
293        let mut scope = self.enter_retained_scalar_subqueries(arena);
294        scope.source_outer_rewrites = rewrites;
295        Ok(scope)
296    }
297
298    /// 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.
299    pub fn enter_scalar_subqueries(
300        &mut self,
301        subqueries: &[QueryPlan],
302    ) -> ScalarSubqueryScope<'_, S> {
303        self.enter_scalar_subqueries_with_control(
304            subqueries,
305            &uqa_core::memory::ProductionControl::uncontrolled(),
306        )
307        .expect("ordinary scalar-query scope")
308    }
309
310    pub fn enter_scalar_subqueries_with_control(
311        &mut self,
312        subqueries: &[QueryPlan],
313        control: &uqa_core::memory::ProductionControl<'_>,
314    ) -> Result<ScalarSubqueryScope<'_, S>, SQLError> {
315        let arena = uqa_sql::plan::RetainedQueryArena::capture(subqueries, control)?;
316        Ok(self.enter_retained_scalar_subqueries(arena))
317    }
318
319    pub(crate) fn enter_retained_scalar_subqueries(
320        &mut self,
321        arena: uqa_sql::plan::RetainedQueryArena,
322    ) -> ScalarSubqueryScope<'_, S> {
323        let previous = std::mem::replace(&mut self.scalar_subqueries, arena);
324        let next_arena = self
325            .next_scalar_subquery_arena
326            .fetch_add(1, Ordering::Relaxed);
327        let previous_arena = std::mem::replace(&mut self.scalar_subquery_arena, next_arena);
328        let previous_lock_identities = self.lock_identities;
329        let previous_outer_row = self.outer_row_binding();
330        let previous_source_rewrites = self.source_outer_rewrites.clone();
331        ScalarSubqueryScope {
332            ctes: self,
333            previous: Some(previous),
334            previous_arena,
335            previous_lock_identities,
336            previous_outer_row,
337            previous_source_rewrites,
338        }
339    }
340
341    pub fn enter_visible_ctes<'a, 'n>(
342        &'a mut self,
343        names: impl IntoIterator<Item = &'n str>,
344    ) -> VisibleCteScope<'a, S> {
345        self.enter_visible_ctes_with_control(
346            names,
347            &uqa_core::memory::ProductionControl::uncontrolled(),
348        )
349        .expect("ordinary visible CTE scope")
350    }
351
352    /// Build the complete name set before publication. The guard restores its exact previous owner without allocation on error or unwind.
353    pub fn enter_visible_ctes_with_control<'a, 'n>(
354        &'a mut self,
355        names: impl IntoIterator<Item = &'n str>,
356        control: &uqa_core::memory::ProductionControl<'_>,
357    ) -> Result<VisibleCteScope<'a, S>, SQLError> {
358        let mut visible = self.visible_cte_names.copy_with_control(control)?;
359        for name in names {
360            visible.insert_with_control(name, control)?;
361        }
362        control.check()?;
363        let previous = std::mem::replace(&mut self.visible_cte_names, visible);
364        Ok(VisibleCteScope {
365            ctes: self,
366            previous: Some(previous),
367        })
368    }
369
370    /// 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.
371    pub fn is_visible_cte(&self, name: &str) -> bool {
372        uqa_core::RelationIdentity::borrowed_reference(name).is_some_and(|reference| {
373            reference.schema.is_none()
374                && (self.visible_cte_names.contains_name(reference.name)
375                    || self.rows.get_name(reference.name).is_some()
376                    || self.deferred_ctes.get_name(reference.name).is_some())
377        })
378    }
379
380    /// Test an already decoded, unqualified identifier without applying SQL name parsing a second time.
381    pub fn contains_cte_name(&self, name: &str) -> bool {
382        self.visible_cte_names.contains(name)
383            || self.rows.contains_key(name)
384            || self.deferred_ctes.contains_key(name)
385    }
386
387    pub fn returning_statement_snapshot_scope(&self) -> Self {
388        self.returning_statement_snapshot_scope_with_control(
389            &uqa_core::memory::ProductionControl::uncontrolled(),
390        )
391        .expect("ordinary returning scope")
392    }
393
394    pub fn returning_statement_snapshot_scope_with_control(
395        &self,
396        control: &uqa_core::memory::ProductionControl<'_>,
397    ) -> Result<Self, SQLError> {
398        let mut scope = self.copy_with_control(control)?;
399        scope.read_command_overlay = false;
400        Ok(scope)
401    }
402
403    pub fn reads_command_overlay(&self) -> bool {
404        self.read_command_overlay
405    }
406
407    pub fn enable_command_progress_streaming(&mut self) {
408        self.stream_command_progress = true;
409    }
410
411    pub fn streams_command_progress(&self) -> bool {
412        self.stream_command_progress
413    }
414
415    pub fn enable_backwards_scanning(&mut self) {
416        self.scan_backwards = true;
417    }
418
419    pub fn scans_backwards(&self) -> bool {
420        self.scan_backwards
421    }
422}
423
424pub struct PrivilegeSubjectScope<'a, S: Clone> {
425    ctes: &'a mut CteScope<S>,
426    previous: Option<super::production::subject::ScopeSubject>,
427}
428
429impl<S: Clone> std::ops::Deref for PrivilegeSubjectScope<'_, S> {
430    type Target = CteScope<S>;
431
432    fn deref(&self) -> &Self::Target {
433        self.ctes
434    }
435}
436
437impl<S: Clone> std::ops::DerefMut for PrivilegeSubjectScope<'_, S> {
438    fn deref_mut(&mut self) -> &mut Self::Target {
439        self.ctes
440    }
441}
442
443impl<S: Clone> Drop for PrivilegeSubjectScope<'_, S> {
444    fn drop(&mut self) {
445        self.ctes.privilege_subject = self.previous.take();
446    }
447}
448
449pub struct RelationLookupScope<'a, S: Clone> {
450    ctes: &'a mut CteScope<S>,
451    previous: RelationLookupMode,
452}
453
454impl<S: Clone> std::ops::Deref for RelationLookupScope<'_, S> {
455    type Target = CteScope<S>;
456
457    fn deref(&self) -> &Self::Target {
458        self.ctes
459    }
460}
461
462impl<S: Clone> std::ops::DerefMut for RelationLookupScope<'_, S> {
463    fn deref_mut(&mut self) -> &mut Self::Target {
464        self.ctes
465    }
466}
467
468impl<S: Clone> Drop for RelationLookupScope<'_, S> {
469    fn drop(&mut self) {
470        let resolution = self
471            .ctes
472            .catalog_resolution
473            .as_mut()
474            .expect("relation lookup scope lost its statement resolution");
475        resolution.set_lookup_mode(self.previous);
476    }
477}
478
479pub struct QueryPlanScope<'a, S: Clone> {
480    lookup: RelationLookupScope<'a, S>,
481    previous_subject: QueryPrivilege,
482}
483
484enum QueryPrivilege {
485    Unchanged,
486    Restore(Option<super::production::subject::ScopeSubject>),
487}
488
489impl<S: Clone> std::ops::Deref for QueryPlanScope<'_, S> {
490    type Target = CteScope<S>;
491    fn deref(&self) -> &Self::Target {
492        &self.lookup
493    }
494}
495
496impl<S: Clone> std::ops::DerefMut for QueryPlanScope<'_, S> {
497    fn deref_mut(&mut self) -> &mut Self::Target {
498        &mut self.lookup
499    }
500}
501
502impl<S: Clone> Drop for QueryPlanScope<'_, S> {
503    fn drop(&mut self) {
504        if let QueryPrivilege::Restore(previous) = &mut self.previous_subject {
505            self.lookup.privilege_subject = previous.take();
506        }
507    }
508}
509
510pub struct ScalarSubqueryScope<'a, S: Clone> {
511    ctes: &'a mut CteScope<S>,
512    previous: Option<uqa_sql::plan::RetainedQueryArena>,
513    previous_arena: u64,
514    previous_lock_identities: LockIdentityOptions,
515    previous_outer_row: Option<Arc<crate::OwnedPhysicalRow>>,
516    previous_source_rewrites: Option<super::SourceOuterRewrites>,
517}
518
519impl<S: Clone> std::ops::Deref for ScalarSubqueryScope<'_, S> {
520    type Target = CteScope<S>;
521
522    fn deref(&self) -> &Self::Target {
523        self.ctes
524    }
525}
526
527impl<S: Clone> std::ops::DerefMut for ScalarSubqueryScope<'_, S> {
528    fn deref_mut(&mut self) -> &mut Self::Target {
529        self.ctes
530    }
531}
532
533impl<S: Clone> Drop for ScalarSubqueryScope<'_, S> {
534    fn drop(&mut self) {
535        if let Some(previous) = self.previous.take() {
536            self.ctes.scalar_subqueries = previous;
537            self.ctes.scalar_subquery_arena = self.previous_arena;
538            self.ctes.lock_identities = self.previous_lock_identities;
539            self.ctes
540                .restore_outer_row_binding(self.previous_outer_row.take());
541            self.ctes.source_outer_rewrites = std::mem::take(&mut self.previous_source_rewrites);
542        }
543    }
544}
545
546pub struct VisibleCteScope<'a, S: Clone> {
547    ctes: &'a mut CteScope<S>,
548    previous: Option<BindingNameSet>,
549}
550
551impl<S: Clone> std::ops::Deref for VisibleCteScope<'_, S> {
552    type Target = CteScope<S>;
553
554    fn deref(&self) -> &Self::Target {
555        self.ctes
556    }
557}
558
559impl<S: Clone> std::ops::DerefMut for VisibleCteScope<'_, S> {
560    fn deref_mut(&mut self) -> &mut Self::Target {
561        self.ctes
562    }
563}
564
565impl<S: Clone> Drop for VisibleCteScope<'_, S> {
566    fn drop(&mut self) {
567        if let Some(previous) = self.previous.take() {
568            self.ctes.visible_cte_names = previous;
569        }
570    }
571}