Skip to main content

uqa_sql/plan/
scoped_visit.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Mutable plan traversal borrows lexical CTE names without copying definitions or names.
8
9use super::{
10    CommandPlan, CtePlan, CtePlanBody, QueryPlan, RelationalPlan, SourcePlan, UnifiedPlan,
11};
12use crate::SQLError;
13
14/// Hooks receive the enclosing CTE namespace, using decoded, unqualified names. A command's own definitions are not enclosing names. Returning false leaves its children unvisited.
15pub trait ScopedPlanVisitor {
16    fn command(
17        &mut self,
18        _command: &mut CommandPlan,
19        _outer: &dyn Fn(&str) -> bool,
20    ) -> Result<bool, SQLError> {
21        Ok(true)
22    }
23
24    fn source(
25        &mut self,
26        _source: &mut SourcePlan,
27        _visible: &dyn Fn(&str) -> bool,
28    ) -> Result<bool, SQLError> {
29        Ok(true)
30    }
31}
32
33impl UnifiedPlan {
34    pub fn visit_scoped_mut(
35        &mut self,
36        visitor: &mut dyn ScopedPlanVisitor,
37    ) -> Result<(), SQLError> {
38        visit_plan(self, &|_| false, visitor)
39    }
40}
41
42fn visit_plan(
43    plan: &mut UnifiedPlan,
44    outer: &dyn Fn(&str) -> bool,
45    visitor: &mut dyn ScopedPlanVisitor,
46) -> Result<(), SQLError> {
47    match plan {
48        UnifiedPlan::Query(query) => visit_query(query, outer, visitor),
49        UnifiedPlan::Command(command) => visit_command(command, outer, visitor),
50    }
51}
52
53fn visit_ctes(
54    ctes: &mut [CtePlan],
55    outer: &dyn Fn(&str) -> bool,
56    visitor: &mut dyn ScopedPlanVisitor,
57) -> Result<(), SQLError> {
58    let recursive = ctes.iter().any(|cte| cte.recursive);
59    for index in 0..ctes.len() {
60        let (before, rest) = ctes.split_at_mut(index);
61        let (cte, after) = rest.split_first_mut().expect("current CTE");
62        let visible = |name: &str| {
63            before.iter().any(|cte| cte.name == name)
64                || (recursive && (cte.name == name || after.iter().any(|cte| cte.name == name)))
65                || outer(name)
66        };
67        match &mut cte.body {
68            CtePlanBody::Query(query) => visit_query(query, &visible, visitor)?,
69            CtePlanBody::Command(command) => visit_command(command, &visible, visitor)?,
70        }
71    }
72    Ok(())
73}
74
75fn visit_query(
76    query: &mut QueryPlan,
77    outer: &dyn Fn(&str) -> bool,
78    visitor: &mut dyn ScopedPlanVisitor,
79) -> Result<(), SQLError> {
80    visit_ctes(&mut query.ctes, outer, visitor)?;
81    let visible = |name: &str| query.ctes.iter().any(|cte| cte.name == name) || outer(name);
82    let subqueries = match &mut query.root {
83        RelationalPlan::QueryBlock(block) => {
84            if let Some(source) = &mut block.from {
85                visit_source(source, &visible, visitor)?;
86            }
87            &mut block.subqueries
88        }
89        RelationalPlan::SetOp {
90            left,
91            right,
92            subqueries,
93            ..
94        } => {
95            visit_query(left, &visible, visitor)?;
96            visit_query(right, &visible, visitor)?;
97            subqueries
98        }
99        RelationalPlan::Values { subqueries, .. } => subqueries,
100    };
101    for query in subqueries {
102        visit_query(query, &visible, visitor)?;
103    }
104    Ok(())
105}
106
107fn visit_source(
108    source: &mut SourcePlan,
109    visible: &dyn Fn(&str) -> bool,
110    visitor: &mut dyn ScopedPlanVisitor,
111) -> Result<(), SQLError> {
112    if !visitor.source(source, visible)? {
113        return Ok(());
114    }
115    match source {
116        SourcePlan::Subquery { body, .. } => visit_query(body, visible, visitor)?,
117        SourcePlan::Table {
118            name,
119            executable_query: Some(body),
120            ..
121        } => {
122            if crate::semantics::cte_reference_name(name).is_some_and(|name| visible(&name)) {
123                visit_query(body, visible, visitor)?;
124            } else {
125                // Stored view definitions have their own namespace, independently of the invoking query's WITH names.
126                visit_query(body, &|_| false, visitor)?;
127            }
128        }
129        SourcePlan::Join { left, right, .. } => {
130            visit_source(left, visible, visitor)?;
131            visit_source(right, visible, visitor)?;
132        }
133        _ => {}
134    }
135    Ok(())
136}
137
138fn visit_command(
139    command: &mut CommandPlan,
140    outer: &dyn Fn(&str) -> bool,
141    visitor: &mut dyn ScopedPlanVisitor,
142) -> Result<(), SQLError> {
143    if !visitor.command(command, outer)? {
144        return Ok(());
145    }
146    let (ctes, source, query, subqueries) = match command {
147        CommandPlan::CreateView { query, .. }
148        | CommandPlan::CreateTableAs { query, .. }
149        | CommandPlan::CreateMaterializedView { query, .. }
150        | CommandPlan::DeclareCursor { query, .. } => return visit_query(query, outer, visitor),
151        CommandPlan::Explain { body, .. } | CommandPlan::Prepare { body, .. } => {
152            return visit_plan(body, outer, visitor)
153        }
154        CommandPlan::Execute { params, .. } | CommandPlan::Call { args: params, .. } => {
155            for expression in params {
156                for query in &mut expression.subqueries {
157                    visit_query(query, outer, visitor)?;
158                }
159            }
160            return Ok(());
161        }
162        CommandPlan::Insert(plan) => (
163            &mut plan.ctes,
164            None,
165            plan.source.as_deref_mut(),
166            &mut plan.subqueries,
167        ),
168        CommandPlan::Update(plan) => (
169            &mut plan.ctes,
170            plan.source.as_deref_mut(),
171            None,
172            &mut plan.subqueries,
173        ),
174        CommandPlan::Delete(plan) => (
175            &mut plan.ctes,
176            plan.source.as_deref_mut(),
177            None,
178            &mut plan.subqueries,
179        ),
180        CommandPlan::Merge(plan) => (
181            &mut plan.ctes,
182            Some(plan.source.as_mut()),
183            None,
184            &mut plan.subqueries,
185        ),
186        _ => return Ok(()),
187    };
188    visit_ctes(ctes, outer, visitor)?;
189    let visible = |name: &str| ctes.iter().any(|cte| cte.name == name) || outer(name);
190    if let Some(source) = source {
191        visit_source(source, &visible, visitor)?;
192    }
193    if let Some(query) = query {
194        visit_query(query, &visible, visitor)?;
195    }
196    for query in subqueries {
197        visit_query(query, &visible, visitor)?;
198    }
199    Ok(())
200}
201
202#[cfg(test)]
203mod tests;