Skip to main content

uqa_sql/plan/mutable/
analysis.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Ordered preparation observes original addresses and installs only typed independently owned metadata.
8
9use super::{MutableExecutablePlan, MutableQueryPlan, RewriteMemory};
10use crate::{
11    ast::FunctionBinding,
12    plan::{ProjectionPlan, QueryPlan, SharedAnalyzedSource, SourcePlan},
13    RowSchema, SQLError,
14};
15use uqa_core::memory::{BudgetedVec, MemoryReservation, Produced, ProductionControl};
16
17mod traversal;
18
19type ProjectionAliasUpdates = Produced<Vec<(usize, Produced<String>)>>;
20
21#[derive(Default)]
22pub(crate) struct QueryMetadataUpdate {
23    pub root: Option<MutableQueryPlan>,
24    pub output: Option<RowSchema>,
25    pub source: Option<SharedAnalyzedSource>,
26    pub grouping: Option<Produced<crate::semantics::grouping_sets::AnalyzedGroupingSets>>,
27}
28
29impl QueryMetadataUpdate {
30    pub(super) fn install(
31        self,
32        query: &mut QueryPlan,
33        mut memory: Option<&mut RewriteMemory>,
34        control: &ProductionControl<'_>,
35    ) -> Result<(), SQLError> {
36        if let Some(root) = self.root {
37            root.assert_owner(control);
38            let MutableQueryPlan {
39                query: replacement,
40                memory: mut replacement_memory,
41            } = root;
42            query.root = replacement.root;
43            if let Some(memory) = memory.as_deref_mut() {
44                *memory.field_mut("root") = replacement_memory
45                    .as_mut()
46                    .expect("replacement query owner")
47                    .field_mut("root")
48                    .take();
49            }
50        }
51        if let Some(output) = self.output {
52            query.analyzed_output = Some(output);
53        }
54        if let Some(source) = self.source {
55            query.analyzed_source = Some(source);
56        }
57        if let Some(grouping) = self.grouping {
58            let (grouping, lease) = grouping.into_parts();
59            let (grouping, lease) = control.finish(grouping, lease)?.into_parts();
60            query.analyzed_grouping = Some(grouping);
61            if let Some(memory) = memory {
62                let direct = lease.expect("admitted grouping metadata");
63                *memory.field_mut("analyzed_grouping") = Some(RewriteMemory::Fields {
64                    fields: BudgetedVec::new(direct.budget()),
65                    direct,
66                });
67            }
68        }
69        Ok(())
70    }
71}
72
73pub(crate) type SourceMetadataUpdate = Produced<Vec<(usize, Produced<FunctionBinding>)>>;
74type ProjectionObserver<'a> =
75    dyn FnMut(&[ProjectionPlan]) -> Result<ProjectionAliasUpdates, SQLError> + 'a;
76pub(super) type QueryObserver<'a> =
77    dyn FnMut(&QueryPlan) -> Result<QueryMetadataUpdate, SQLError> + 'a;
78type SourceObserver<'a> = dyn FnMut(&SourcePlan) -> Result<SourceMetadataUpdate, SQLError> + 'a;
79type SourceReplacement<'a> =
80    dyn FnMut(&SourcePlan) -> Result<Option<super::MutableSourcePlan>, SQLError> + 'a;
81
82struct Walker<'a, 'c> {
83    query: Option<&'a mut QueryObserver<'a>>,
84    projections: Option<&'a mut ProjectionObserver<'a>>,
85    source: Option<&'a mut SourceObserver<'a>>,
86    replacement: Option<&'a mut SourceReplacement<'a>>,
87    control: ProductionControl<'c>,
88    mark_relations: bool,
89    cte_command: bool,
90}
91
92impl MutableExecutablePlan {
93    /// Catalog statement inputs retain their bound identities. CTE mutation targets are bound as well; the enclosing action target keeps its independent binding decision.
94    pub fn mark_catalog_relations_bound(
95        mut self,
96        control: &ProductionControl<'_>,
97    ) -> Result<Self, SQLError> {
98        control.check()?;
99        if let Self::Command(command) = &self {
100            if !matches!(
101                &**command,
102                crate::plan::CommandPlan::Insert(_)
103                    | crate::plan::CommandPlan::Update(_)
104                    | crate::plan::CommandPlan::Delete(_)
105                    | crate::plan::CommandPlan::Merge(_)
106                    | crate::plan::CommandPlan::Notify { .. }
107            ) {
108                return Err(SQLError::Internal(
109                    "catalog-owned statement lowered to an unsupported command".into(),
110                ));
111            }
112        }
113        Walker {
114            query: None,
115            projections: None,
116            source: None,
117            replacement: None,
118            control: *control,
119            mark_relations: true,
120            cte_command: false,
121        }
122        .plan(&mut self)?;
123        Ok(self)
124    }
125    /// Select independently owned replacements while borrowing original sources in SQL source order. Replacement payloads and constructor records are installed together before visiting descendants.
126    pub fn replace_sources<'a>(
127        &mut self,
128        control: &ProductionControl<'_>,
129        replace: &'a mut SourceReplacement<'a>,
130    ) -> Result<(), SQLError> {
131        Walker {
132            query: None,
133            projections: None,
134            source: None,
135            replacement: Some(replace),
136            control: *control,
137            mark_relations: false,
138            cte_command: false,
139        }
140        .plan(self)
141    }
142    /// Preparation owns this private destination through the call; failure discards it before publication. Observers only receive original read-only syntax and return typed owning updates.
143    pub(crate) fn apply_query_metadata<'a>(
144        &mut self,
145        control: &ProductionControl<'_>,
146        observe: &'a mut QueryObserver<'a>,
147    ) -> Result<(), SQLError> {
148        Walker {
149            query: Some(observe),
150            projections: None,
151            source: None,
152            replacement: None,
153            mark_relations: false,
154            cte_command: false,
155            control: *control,
156        }
157        .plan(self)
158    }
159
160    /// Preserve observable projection names before scalar replacement, for both queries and mutation RETURNING clauses.
161    pub(crate) fn apply_projection_aliases<'a>(
162        &mut self,
163        control: &ProductionControl<'_>,
164        observe: &'a mut ProjectionObserver<'a>,
165    ) -> Result<(), SQLError> {
166        Walker {
167            query: None,
168            projections: Some(observe),
169            source: None,
170            replacement: None,
171            mark_relations: false,
172            cte_command: false,
173            control: *control,
174        }
175        .plan(self)
176    }
177
178    pub(crate) fn apply_source_metadata<'a>(
179        &mut self,
180        control: &ProductionControl<'_>,
181        observe: &'a mut SourceObserver<'a>,
182    ) -> Result<(), SQLError> {
183        Walker {
184            query: None,
185            projections: None,
186            source: Some(observe),
187            replacement: None,
188            mark_relations: false,
189            cte_command: false,
190            control: *control,
191        }
192        .plan(self)
193    }
194}
195
196impl Walker<'_, '_> {
197    fn install_query(
198        &mut self,
199        query: &mut QueryPlan,
200        memory: Option<&mut RewriteMemory>,
201    ) -> Result<(), SQLError> {
202        self.control.check()?;
203        if self.mark_relations {
204            query.relations_bound = true;
205        }
206        let Some(observe) = &mut self.query else {
207            return Ok(());
208        };
209        let update = observe(query)?;
210        update.install(query, memory, &self.control)
211    }
212
213    fn install_projection_aliases(
214        &mut self,
215        projections: &mut [ProjectionPlan],
216        memory: Option<&mut RewriteMemory>,
217    ) -> Result<(), SQLError> {
218        let Some(observe) = &mut self.projections else {
219            return Ok(());
220        };
221        let aliases = observe(projections)?;
222        install_aliases(projections, memory, aliases, &self.control)
223    }
224
225    fn install_source(
226        &mut self,
227        source: &mut SourcePlan,
228        mut memory: Option<&mut RewriteMemory>,
229    ) -> Result<(), SQLError> {
230        self.control.check()?;
231        if let Some(replace) = &mut self.replacement {
232            if let Some(replacement) = replace(source)? {
233                let (value, owner) = replacement.into_rewrite_parts(&self.control)?;
234                *source = value;
235                if let Some(memory) = memory.as_deref_mut() {
236                    *memory = owner.expect("replacement source owner");
237                }
238            }
239        }
240        let Some(observe) = &mut self.source else {
241            return Ok(());
242        };
243        let updates = observe(source)?;
244        let (values, buffer) = updates.into_parts();
245        struct Updates {
246            values: std::vec::IntoIter<(usize, Produced<FunctionBinding>)>,
247            _buffer: Option<MemoryReservation>,
248        }
249        let mut updates = Updates {
250            values: values.into_iter(),
251            _buffer: buffer,
252        };
253        for (index, selected) in &mut updates.values {
254            let (binding, owner) = match source {
255                SourcePlan::Function { binding, .. } => {
256                    assert_eq!(index, 0, "single function source binding");
257                    (
258                        binding,
259                        memory
260                            .as_deref_mut()
261                            .map(|memory| memory.field_mut("binding")),
262                    )
263                }
264                SourcePlan::FunctionGroup { functions, .. } => {
265                    let owner = memory.as_deref_mut().map(|memory| {
266                        memory
267                            .field_mut("functions")
268                            .as_mut()
269                            .expect("function vector")
270                            .item_mut(index)
271                            .as_mut()
272                            .expect("table function")
273                            .field_mut("binding")
274                    });
275                    (&mut functions[index].binding, owner)
276                }
277                _ => {
278                    return Err(SQLError::Internal(
279                        "selected function binding lost its source".into(),
280                    ));
281                }
282            };
283            let (selected, lease) = selected.into_parts();
284            let selected = self.control.finish(selected, lease)?;
285            let (selected, lease) = selected.into_parts();
286            *binding = Some(selected);
287            if let Some(owner) = owner {
288                let direct = lease.expect("admitted selected function binding");
289                *owner = Some(RewriteMemory::Fields {
290                    fields: BudgetedVec::new(direct.budget()),
291                    direct,
292                });
293            }
294        }
295        Ok(())
296    }
297}
298
299fn install_aliases(
300    projections: &mut [ProjectionPlan],
301    mut memory: Option<&mut RewriteMemory>,
302    aliases: Produced<Vec<(usize, Produced<String>)>>,
303    control: &ProductionControl<'_>,
304) -> Result<(), SQLError> {
305    let (values, buffer) = aliases.into_parts();
306    struct Aliases {
307        values: std::vec::IntoIter<(usize, Produced<String>)>,
308        _buffer: Option<MemoryReservation>,
309    }
310    let mut aliases = Aliases {
311        values: values.into_iter(),
312        _buffer: buffer,
313    };
314    for (index, alias) in &mut aliases.values {
315        control.check()?;
316        let (alias, lease) = alias.into_parts();
317        let (alias, lease) = control.finish(alias, lease)?.into_parts();
318        projections[index].alias = Some(alias);
319        if let Some(memory) = memory.as_deref_mut() {
320            let direct = lease.expect("admitted projection alias");
321            *memory
322                .item_mut(index)
323                .as_mut()
324                .expect("projection")
325                .field_mut("alias") = Some(RewriteMemory::Fields {
326                fields: BudgetedVec::new(direct.budget()),
327                direct,
328            });
329        }
330    }
331    Ok(())
332}