Skip to main content

uqa_sql/semantics/view_rewrite/
deferred.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Resolve outer-column substitutions only after the local namespace is known.
8
9use crate::plan::{ExpressionPlan, QueryBlockPlan, QueryPlan, RelationalPlan};
10use crate::{ColumnIdentity, RowSchema, SQLError, ScalarExpr};
11use std::borrow::Cow;
12use std::collections::BTreeMap;
13use std::sync::Arc;
14
15mod capture;
16mod owned;
17type OuterColumns = uqa_core::memory::OwnedMap<ColumnIdentity, crate::ast::InternalColumnRef>;
18mod scope;
19pub use owned::{
20    bind_outer_rewrite_scope_with_control, resolve_outer_expression_rewrites_owned,
21    resolve_outer_rewrites_owned, resolve_outer_sources_owned,
22};
23mod sources;
24pub use sources::{resolve_outer_source_rewrites, resolve_outer_sources};
25#[cfg(test)]
26mod tests;
27pub use scope::bind_outer_rewrite_scope;
28
29/// Resolve an expression against its actual local descriptor. The caller retains the accompanying scalar-query arena for evaluation.
30pub fn resolve_outer_expression_rewrites(
31    expression: &mut ScalarExpr,
32    rewrites: &[DeferredOuterRewrite],
33    local: &RowSchema,
34    subqueries: &mut Vec<QueryPlan>,
35) {
36    for rewrite in rewrites {
37        rewrite
38            .in_namespace(local)
39            .expression(expression, subqueries);
40    }
41}
42
43/// An outer-column rewrite retained across an open native row descriptor. Names in an intervening query scope shadow these substitutions, even when their values are NULL.
44#[derive(Debug, Clone)]
45pub struct DeferredOuterRewrite {
46    outer_columns: Arc<uqa_core::memory::Produced<OuterColumns>>,
47    replacements: replacements::Replacements,
48    pub(super) shadowed_qualifiers: uqa_core::memory::OwnedSet<String>,
49    pub(super) shadowed_columns: uqa_core::memory::OwnedSet<String>,
50}
51
52#[derive(Debug)]
53struct OuterReplacement {
54    expression: ExpressionPlan,
55    qualifier: String,
56    memory: Option<uqa_core::memory::MemoryReservation>,
57}
58
59fn ordinary_outer_columns(
60    columns: BTreeMap<ColumnIdentity, crate::ast::InternalColumnRef>,
61) -> Arc<uqa_core::memory::Produced<OuterColumns>> {
62    Arc::new(
63        uqa_core::memory::ProductionControl::uncontrolled()
64            .finish(columns.into_iter().collect::<OuterColumns>(), None)
65            .expect("ordinary outer columns"),
66    )
67}
68
69mod replacements;
70mod transformation;
71
72impl Clone for OuterReplacement {
73    fn clone(&self) -> Self {
74        Self {
75            expression: self.expression.clone(),
76            qualifier: self.qualifier.clone(),
77            memory: None,
78        }
79    }
80}
81
82/// Bind a pending rewrite to the complete local source descriptor without changing its retained syntax. An open descriptor cannot decide that an absent name belongs to the outer scope.
83pub(crate) fn has_resolvable_outer_rewrites(block: &QueryBlockPlan, local: &RowSchema) -> bool {
84    !block.deferred_outer_rewrites.is_empty()
85        && (!local.columns_are_open(None)
86            || block.deferred_outer_rewrites.iter().any(|rewrite| {
87                rewrite
88                    .replacements
89                    .keys()
90                    .any(|identity| identity.qualifier().is_some())
91            }))
92}
93
94pub fn resolve_outer_rewrites<'a>(
95    block: &'a QueryBlockPlan,
96    local: &RowSchema,
97) -> Cow<'a, QueryBlockPlan> {
98    let open = local.columns_are_open(None);
99    if !has_resolvable_outer_rewrites(block, local) {
100        return Cow::Borrowed(block);
101    }
102    let mut block = block.clone();
103    for mut rewrite in std::mem::take(&mut block.deferred_outer_rewrites) {
104        rewrite.add_namespace(local);
105        if open {
106            let mut pending = rewrite.clone();
107            pending
108                .replacements
109                .ordinary_mut()
110                .retain(|identity, _| identity.qualifier().is_none());
111            if !pending.replacements.is_empty() {
112                block.deferred_outer_rewrites.push(pending);
113            }
114            rewrite
115                .replacements
116                .ordinary_mut()
117                .retain(|identity, _| identity.qualifier().is_some());
118        }
119        rewrite.block(&mut block);
120    }
121    Cow::Owned(block)
122}
123
124impl DeferredOuterRewrite {
125    pub(crate) fn copy_with(
126        &self,
127        copying: &mut crate::plan::copy::Copying<'_>,
128    ) -> Result<Self, SQLError> {
129        Ok(Self {
130            outer_columns: Arc::clone(&self.outer_columns),
131            replacements: self.replacements.clone(),
132            shadowed_qualifiers: copying.set(&self.shadowed_qualifiers, |copying, name| {
133                copying.text(name)
134            })?,
135            shadowed_columns: copying
136                .set(&self.shadowed_columns, |copying, name| copying.text(name))?,
137        })
138    }
139
140    /// Bind expressions whose original input attributes already have internal identities. Nested query namespaces resolve their own names before consulting these outer replacements.
141    pub(crate) fn from_inputs(inputs: BTreeMap<ColumnIdentity, ExpressionPlan>) -> Self {
142        Self {
143            outer_columns: ordinary_outer_columns(BTreeMap::new()),
144            replacements: replacements::Replacements::ordinary(
145                inputs
146                    .into_iter()
147                    .map(|(identity, expression)| {
148                        (
149                            identity,
150                            OuterReplacement {
151                                expression,
152                                qualifier: String::new(),
153                                memory: None,
154                            },
155                        )
156                    })
157                    .collect(),
158            ),
159            shadowed_qualifiers: uqa_core::memory::OwnedSet::new(),
160            shadowed_columns: uqa_core::memory::OwnedSet::new(),
161        }
162    }
163
164    pub(crate) fn bind_expression(&self, expression: &mut ExpressionPlan) {
165        self.expression(&mut expression.scalar, &mut expression.subqueries);
166    }
167
168    pub(crate) fn expressions(&self) -> impl Iterator<Item = &ExpressionPlan> {
169        self.replacements
170            .values()
171            .map(|replacement| &replacement.expression)
172    }
173
174    pub(crate) fn try_visit_scalar_expressions<'a, E>(
175        &'a self,
176        visit: &mut dyn FnMut(&'a ScalarExpr) -> Result<(), E>,
177    ) -> Result<(), E> {
178        for expression in self.expressions() {
179            visit(&expression.scalar)?;
180            for query in &expression.subqueries {
181                query.try_visit_scalar_expressions(visit)?;
182            }
183        }
184        Ok(())
185    }
186
187    pub(crate) fn rewrite_scalar_expressions(&mut self, rewrite: &mut dyn FnMut(&mut ScalarExpr)) {
188        for replacement in self.replacements.ordinary_mut().values_mut() {
189            let expression = &mut replacement.expression;
190            crate::plan::rewrite_scalar_expression(&mut expression.scalar, rewrite);
191            for query in &mut expression.subqueries {
192                query.rewrite_scalar_expressions(rewrite);
193            }
194        }
195    }
196
197    fn add_namespace(&mut self, local: &RowSchema) {
198        self.shadowed_columns
199            .extend(super::schema_public_columns(local));
200        for identity in self.replacements.keys() {
201            match identity.qualifier() {
202                Some(qualifier) if local.has_qualifier(qualifier) => {
203                    self.shadowed_qualifiers.insert(qualifier.to_owned());
204                }
205                None if local.has_unqualified_column(identity.column())
206                    || local.has_qualifier(identity.column()) =>
207                {
208                    self.shadowed_columns.insert(identity.column().to_owned());
209                }
210                _ => {}
211            }
212        }
213    }
214
215    fn in_namespace(&self, local: &RowSchema) -> Self {
216        let mut rewrite = self.clone();
217        rewrite.add_namespace(local);
218        if local.columns_are_open(None) {
219            rewrite
220                .replacements
221                .ordinary_mut()
222                .retain(|identity, _| identity.qualifier().is_some());
223        }
224        rewrite
225    }
226
227    fn expression(&self, expression: &mut ScalarExpr, subqueries: &mut Vec<QueryPlan>) {
228        crate::plan::rewrite_scalar_expression(expression, &mut |node| {
229            if let ScalarExpr::ScalarSubquery(id)
230            | ScalarExpr::Exists { subquery: id, .. }
231            | ScalarExpr::InSubquery { subquery: id, .. } = node
232            {
233                if let Some(query) = subqueries.get_mut(*id) {
234                    self.query(query);
235                }
236                return;
237            }
238            let identity = match node {
239                ScalarExpr::Column(column) if !self.shadowed_columns.contains(column.as_str()) => {
240                    ColumnIdentity::unqualified(column.as_str())
241                }
242                ScalarExpr::QualifiedStar(qualifier)
243                    if !self.shadowed_qualifiers.contains(qualifier.as_str()) =>
244                {
245                    ColumnIdentity::unqualified(qualifier.as_str())
246                }
247                ScalarExpr::QualifiedColumn { qualifier, column }
248                    if !self.shadowed_qualifiers.contains(qualifier) =>
249                {
250                    ColumnIdentity::qualified(qualifier.as_str(), column.as_str())
251                }
252                _ => return,
253            };
254            let Some(replacement) = self.replacements.get(&identity) else {
255                return;
256            };
257            let offset = subqueries.len();
258            let mut replacement = replacement.clone();
259            self.bind_replacement_columns(&mut replacement);
260            let mut replacement = replacement.expression;
261            crate::plan::rewrite_scalar_expression(
262                &mut replacement.scalar,
263                &mut |node| match node {
264                    ScalarExpr::ScalarSubquery(id)
265                    | ScalarExpr::Exists { subquery: id, .. }
266                    | ScalarExpr::InSubquery { subquery: id, .. } => *id += offset,
267                    _ => {}
268                },
269            );
270            subqueries.extend(replacement.subqueries);
271            *node = replacement.scalar;
272        });
273    }
274
275    fn block(&self, block: &mut QueryBlockPlan) {
276        for expression in block
277            .projections
278            .iter_mut()
279            .map(|projection| &mut projection.expr)
280            .chain(block.r#where.iter_mut())
281            .chain(&mut block.group_by)
282            .chain(block.grouping_sets.iter_mut().flatten())
283            .chain(block.having.iter_mut())
284            .chain(block.order_by.iter_mut().map(|order| &mut order.expr))
285            .chain(block.limit.iter_mut())
286            .chain(block.offset.iter_mut())
287            .chain(&mut block.distinct_on)
288            .chain(
289                block
290                    .windows
291                    .iter_mut()
292                    .flat_map(|window| window.spec.expressions_mut()),
293            )
294        {
295            self.expression(expression, &mut block.subqueries);
296        }
297    }
298
299    fn query(&self, query: &mut QueryPlan) {
300        for cte in &mut query.ctes {
301            if let Some(query) = cte.body.query_mut() {
302                self.query(query);
303            }
304        }
305        match &mut query.root {
306            RelationalPlan::QueryBlock(block) => {
307                if let Some(previous) = block
308                    .deferred_outer_rewrites
309                    .iter_mut()
310                    .find(|previous| Arc::ptr_eq(&previous.outer_columns, &self.outer_columns))
311                {
312                    previous.replacements.ordinary_mut().extend(
313                        self.replacements
314                            .iter()
315                            .map(|(identity, expression)| (identity.clone(), expression.clone())),
316                    );
317                    previous
318                        .shadowed_columns
319                        .extend(self.shadowed_columns.iter().cloned());
320                    previous
321                        .shadowed_qualifiers
322                        .extend(self.shadowed_qualifiers.iter().cloned());
323                } else {
324                    block.deferred_outer_rewrites.push(self.clone());
325                }
326            }
327            RelationalPlan::Values { rows, subqueries } => {
328                for expression in rows.iter_mut().flatten() {
329                    self.expression(expression, subqueries);
330                }
331            }
332            RelationalPlan::SetOp {
333                left,
334                right,
335                order_by,
336                limit,
337                offset,
338                subqueries,
339                ..
340            } => {
341                self.query(left);
342                self.query(right);
343                for expression in order_by
344                    .iter_mut()
345                    .map(|order| &mut order.expr)
346                    .chain(limit.iter_mut().map(Box::as_mut))
347                    .chain(offset.iter_mut().map(Box::as_mut))
348                {
349                    self.expression(expression, subqueries);
350                }
351            }
352        }
353    }
354}
355
356impl uqa_core::memory::ObserveAllocations for DeferredOuterRewrite {
357    fn observe_allocations<'a>(
358        &'a self,
359        observer: &mut uqa_core::memory::AllocationObserver<'a, '_>,
360    ) -> Result<(), uqa_core::ValueRetentionError> {
361        let Self {
362            outer_columns: _,
363            replacements: _,
364            shadowed_qualifiers,
365            shadowed_columns,
366        } = self;
367        observer.child(shadowed_qualifiers)?;
368        observer.child(shadowed_columns)?;
369        Ok(())
370    }
371}