Skip to main content

uqa_execution/query/scope/
definitions.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Lexical inputs of deferred definitions, sharing plans and materialized readers.
8
9use super::CteScope;
10use std::collections::{BTreeMap, BTreeSet};
11use std::sync::Arc;
12use uqa_sql::plan::CtePlan;
13
14#[derive(Default)]
15pub(super) struct DefinitionBindings {
16    rows: BTreeMap<String, crate::query::cte::rows::CteRows>,
17    deferred: BTreeMap<String, uqa_sql::plan::RetainedCtePlan>,
18    definitions: BTreeMap<String, Arc<Self>>,
19    non_returning: BTreeSet<String>,
20    folded: BTreeSet<String>,
21    recursive_widths: BTreeMap<String, usize>,
22    names: BTreeSet<String>,
23}
24
25impl DefinitionBindings {
26    pub(super) fn capture<S: Clone>(scope: &CteScope<S>, plan: &CtePlan) -> Self {
27        let names = scope
28            .rows
29            .keys()
30            .chain(scope.deferred_ctes.keys())
31            .cloned()
32            .collect();
33        let mut names = uqa_sql::semantics::cte_external_references(&plan.body, &names);
34        if uqa_sql::semantics::cte_references_own_name(plan) {
35            names.remove(&plan.name);
36        }
37        let mut retained = Self::default();
38        for name in &names {
39            if let Some(rows) = scope.rows.get(name) {
40                retained.rows.insert(name.clone(), rows.clone());
41            }
42            if let Some(plan) = scope.deferred_ctes.get(name) {
43                retained.deferred.insert(name.clone(), plan.clone());
44            }
45            if let Some(definition) = scope.definition_scopes.get(name) {
46                retained
47                    .definitions
48                    .insert(name.clone(), Arc::clone(definition));
49            }
50            if scope.non_returning_ctes.contains(name) {
51                retained.non_returning.insert(name.clone());
52            }
53            if scope.folded_ctes.contains(name) {
54                retained.folded.insert(name.clone());
55            }
56            if let Some(width) = scope.recursive_control_widths.get(name) {
57                retained.recursive_widths.insert(name.clone(), *width);
58            }
59        }
60        retained.names = names;
61        retained
62    }
63}
64
65impl<S: Clone> CteScope<S> {
66    /// Prepare a definition in its original lexical bindings while retaining the invoking statement's catalog, row locks, scalar arena and transaction controls.
67    pub fn definition_scope(&self, reference: &str) -> Option<Self> {
68        let name = uqa_sql::semantics::cte_reference_name(reference)?;
69        self.definition_scope_for_name(&name)
70    }
71
72    /// A declaration already owns its decoded identifier; dots and quotes in that name are not SQL qualification syntax.
73    pub(crate) fn definition_scope_for_name(&self, name: &str) -> Option<Self> {
74        let retained = self.definition_scopes.get(name)?;
75        let mut scope = self.clone();
76        scope.rows.clone_from(&retained.rows);
77        scope.deferred_ctes.clone_from(&retained.deferred);
78        scope.definition_scopes.clone_from(&retained.definitions);
79        scope.non_returning_ctes.clone_from(&retained.non_returning);
80        scope.folded_ctes.clone_from(&retained.folded);
81        scope
82            .recursive_control_widths
83            .clone_from(&retained.recursive_widths);
84        scope.visible_cte_names.clone_from(&retained.names);
85        if let Some(plan) = self.deferred_ctes.get(name) {
86            if uqa_sql::semantics::cte_references_own_name(plan) {
87                scope.deferred_ctes.insert(name.to_owned(), plan.clone());
88                scope.visible_cte_names.insert(name.to_owned());
89            }
90        }
91        Some(scope)
92    }
93
94    pub(crate) fn insert_preparation_cte(
95        &mut self,
96        plan: uqa_sql::plan::RetainedCtePlan,
97        folded: bool,
98    ) {
99        let definition = Arc::new(DefinitionBindings::capture(self, &plan));
100        self.rows.remove(&plan.name);
101        if plan.body.returns_rows() {
102            self.non_returning_ctes.remove(&plan.name);
103        } else {
104            self.non_returning_ctes.insert(plan.name.clone());
105        }
106        if folded {
107            self.folded_ctes.insert(plan.name.clone());
108        } else {
109            self.folded_ctes.remove(&plan.name);
110        }
111        self.definition_scopes.insert(plan.name.clone(), definition);
112        self.deferred_ctes.insert(plan.name.clone(), plan);
113    }
114
115    pub(crate) fn cte_is_folded(&self, name: &str) -> bool {
116        uqa_sql::semantics::cte_reference_name(name)
117            .is_some_and(|name| self.folded_ctes.contains(&name))
118    }
119
120    pub(crate) fn take_deferred_input(&mut self, name: &str) -> Option<(CtePlan, Self)> {
121        let scope = self.definition_scope(name)?;
122        self.deferred_for_scan(name).map(|plan| (plan, scope))
123    }
124}