inillucent_sql/bind/scratch.rs
1//! The binder's working vectors: the set it borrows from the connection, and
2//! the subset it saves while a nested block is bound.
3//!
4//! Invariant: **a vector in here is scratch, never part of an answer.** What
5//! [`Binder::bind_statement`] returns owns its own vectors and leaves with
6//! them; everything this module moves about is state the binder keeps while it
7//! works and has no use for afterwards. That is what makes it safe to hand back
8//! to the connection and fill again.
9//!
10//! ## Why this is its own module
11//!
12//! The same reason [`super::cte`] is: `bind.rs` was at the size `policy.rs`
13//! records for it and task-2026 added to it, and that check asks for an
14//! extraction rather than a raised number. The two halves here are one
15//! question - which of the binder's vectors are saved, and who they are given
16//! back to - asked at two scales.
17//!
18//! [`BinderScratch`] is the outer one: the vectors a *connection* keeps
19//! between statements, so a compile pushes into capacity the last compile
20//! took. [`BlockFrame`] is the inner one: the vectors a *query block* borrows
21//! from the block around it, so an aggregate written inside a subquery is
22//! finalised at its own level rather than the enclosing one. Nothing moved
23//! changed in the move.
24
25use super::{
26 Binder, BoundAggregate, BoundExpr, BoundSource, BoundWindow, CteBinding, RecursiveTarget,
27};
28use crate::ast;
29
30/// The vectors a binder works in, kept by the connection rather than made for
31/// every statement.
32///
33/// **The parse arena's counterpart, for the stage after the parse
34/// (task-2026).** `Compiled::scratch_ast` exists because every vector in an
35/// `Ast` is empty at construction and grows on its first push, so a parse that
36/// is thrown away a microsecond later pays the allocator for capacity it
37/// already had last time. The binder has exactly that shape and was not getting
38/// that treatment: binding `SELECT 1` took the scope stack's buffer and the
39/// result-alias buffer - 96 and 320 bytes - out of the allocator on every
40/// compile, and `prepare.trivial` is a workload the gate compiles on every
41/// iteration.
42///
43/// What is here is the binder's own working state. What the binder *returns* is
44/// not: a `BoundStatement`'s vectors leave with it and belong to whoever asked
45/// for the bind, so recycling them would mean handing back memory something
46/// else is still reading.
47///
48/// Like the arena, it is cleared on the way in rather than on the way out, and
49/// it keeps whatever capacity the largest statement so far needed - a
50/// connection that once bound a statement with ten thousand FROM terms holds
51/// that much `sources` until it closes. That is the trade [`crate::ast::Ast`]
52/// already makes, made once more here rather than differently.
53#[derive(Default)]
54pub struct BinderScratch {
55 sources: Vec<BoundSource>,
56 scopes: Vec<Vec<usize>>,
57 aggregates: Vec<BoundAggregate>,
58 result_aliases: Vec<(Vec<u8>, BoundExpr)>,
59 schemas: Vec<(usize, u32)>,
60 ctes: Vec<Vec<CteBinding>>,
61 recursing: Vec<RecursiveTarget>,
62 binding_ctes: Vec<ast::SelectId>,
63 correlations: Vec<usize>,
64 windows: Vec<BoundWindow>,
65 named_windows: Vec<(Vec<u8>, ast::WindowId)>,
66 firing: Vec<Vec<u8>>,
67 firing_foreign_keys: Vec<Vec<u8>>,
68 pending_constraints: Vec<BoundExpr>,
69}
70
71impl BinderScratch {
72 /// Returns a scratch with nothing in it and nothing allocated.
73 pub fn new() -> BinderScratch {
74 BinderScratch::default()
75 }
76
77 /// Empties every vector, keeping the memory each has already taken.
78 ///
79 /// A `clear` rather than a `new` for the reason [`crate::ast::Ast::clear`]
80 /// gives: the capacity is the point, and dropping it would leave a scratch
81 /// that costs an allocation to refill.
82 fn clear(&mut self) {
83 self.sources.clear();
84 self.scopes.clear();
85 self.aggregates.clear();
86 self.result_aliases.clear();
87 self.schemas.clear();
88 self.ctes.clear();
89 self.recursing.clear();
90 self.binding_ctes.clear();
91 self.correlations.clear();
92 self.windows.clear();
93 self.named_windows.clear();
94 self.firing.clear();
95 self.firing_foreign_keys.clear();
96 self.pending_constraints.clear();
97 }
98}
99
100/// The per-block binder state saved while a nested block is bound.
101///
102/// Aggregates, result aliases and the correlation list all belong to one query
103/// block. Without a frame, an aggregate written inside a subquery would be
104/// added to the enclosing block's accumulator list and finalised at the wrong
105/// level - which is a wrong answer rather than an error.
106pub(super) struct BlockFrame {
107 windows: Vec<BoundWindow>,
108 named_windows: Vec<(Vec<u8>, ast::WindowId)>,
109 aggregates: Vec<BoundAggregate>,
110 result_aliases: Vec<(Vec<u8>, BoundExpr)>,
111 allow_aggregates: bool,
112 allow_windows: bool,
113 in_group_by: bool,
114 in_plain_order_by: bool,
115 inside_aggregate: bool,
116 correlations: Vec<usize>,
117 tail_may_name_an_alias: bool,
118 deferred: Option<(Vec<u8>, crate::lexer::Span)>,
119 /// The table function argument constraints the enclosing block has bound
120 /// and not yet put in its `WHERE`.
121 ///
122 /// **Per block, like the correlations.** They name the enclosing block's
123 /// FROM terms, and a derived table bound after a table function took them
124 /// into its own `WHERE`: `SELECT count(*) FROM json_each('[1,2]'),
125 /// (SELECT 1 AS x)` failed with "the tree read for FROM term 0 does not
126 /// carry column 8", because the subquery's pipeline has no term 0.
127 pending_constraints: Vec<BoundExpr>,
128}
129
130impl<'a> Binder<'a> {
131 /// Binds into vectors the caller keeps, rather than into fresh ones.
132 ///
133 /// **For a caller that binds one statement after another**, which is every
134 /// connection: the scratch is cleared on the way in, so the second bind
135 /// pushes into capacity the first one took. See [`BinderScratch`] for what
136 /// is in it and what is deliberately not.
137 ///
138 /// @param scratch - the vectors to fill, cleared first
139 pub fn with_scratch(mut self, mut scratch: BinderScratch) -> Binder<'a> {
140 scratch.clear();
141 self.sources = scratch.sources;
142 self.scopes = scratch.scopes;
143 self.aggregates = scratch.aggregates;
144 self.result_aliases = scratch.result_aliases;
145 self.dependencies.schemas = scratch.schemas;
146 self.ctes = scratch.ctes;
147 self.recursing = scratch.recursing;
148 self.binding_ctes = scratch.binding_ctes;
149 self.correlations = scratch.correlations;
150 self.windows = scratch.windows;
151 self.named_windows = scratch.named_windows;
152 self.firing = scratch.firing;
153 self.firing_foreign_keys = scratch.firing_foreign_keys;
154 self.pending_constraints = scratch.pending_constraints;
155 self
156 }
157
158 /// Returns the vectors this bind filled, for the next bind to reuse.
159 ///
160 /// The binder is consumed, so nothing can still be reading what is handed
161 /// back. The bound statement is not in here - it was returned by
162 /// [`Binder::bind_statement`] and owns its own vectors.
163 pub fn into_scratch(self) -> BinderScratch {
164 BinderScratch {
165 sources: self.sources,
166 scopes: self.scopes,
167 aggregates: self.aggregates,
168 result_aliases: self.result_aliases,
169 schemas: self.dependencies.schemas,
170 ctes: self.ctes,
171 recursing: self.recursing,
172 binding_ctes: self.binding_ctes,
173 correlations: self.correlations,
174 windows: self.windows,
175 named_windows: self.named_windows,
176 firing: self.firing,
177 firing_foreign_keys: self.firing_foreign_keys,
178 pending_constraints: self.pending_constraints,
179 }
180 }
181
182 /// Opens a query block: a fresh scope, and fresh per-block state.
183 pub(super) fn enter_block(&mut self) -> BlockFrame {
184 self.scopes.push(Vec::new());
185 BlockFrame {
186 windows: core::mem::take(&mut self.windows),
187 named_windows: core::mem::take(&mut self.named_windows),
188 aggregates: core::mem::take(&mut self.aggregates),
189 result_aliases: core::mem::take(&mut self.result_aliases),
190 allow_aggregates: core::mem::replace(&mut self.allow_aggregates, false),
191 allow_windows: core::mem::replace(&mut self.allow_windows, false),
192 in_group_by: core::mem::replace(&mut self.in_group_by, false),
193 in_plain_order_by: core::mem::replace(&mut self.in_plain_order_by, false),
194 inside_aggregate: core::mem::replace(&mut self.inside_aggregate, false),
195 correlations: core::mem::take(&mut self.correlations),
196 tail_may_name_an_alias: self.tail_may_name_an_alias,
197 deferred: self.outer.deferred.take(),
198 pending_constraints: core::mem::take(&mut self.pending_constraints),
199 }
200 }
201
202 /// Closes a query block, returning the FROM terms it owned.
203 ///
204 /// A correlation the closing block recorded is passed outward when the
205 /// block that is now innermost does not own the term either, which is what
206 /// makes correlation transitive through two levels of nesting.
207 pub(super) fn leave_block(&mut self, frame: BlockFrame) -> Vec<usize> {
208 let ids = self.scopes.pop().unwrap_or_default();
209 let inner = core::mem::replace(&mut self.correlations, frame.correlations);
210 for id in inner {
211 if ids.contains(&id) {
212 continue;
213 }
214 let owned = self.scopes.last().is_some_and(|scope| scope.contains(&id));
215 if !owned && !self.correlations.contains(&id) {
216 self.correlations.push(id);
217 }
218 }
219 self.windows = frame.windows;
220 self.named_windows = frame.named_windows;
221 self.aggregates = frame.aggregates;
222 self.result_aliases = frame.result_aliases;
223 self.allow_aggregates = frame.allow_aggregates;
224 self.allow_windows = frame.allow_windows;
225 self.pending_constraints = frame.pending_constraints;
226 self.in_group_by = frame.in_group_by;
227 self.in_plain_order_by = frame.in_plain_order_by;
228 self.inside_aggregate = frame.inside_aggregate;
229 self.tail_may_name_an_alias = frame.tail_may_name_an_alias;
230 self.outer.deferred = frame.deferred;
231 ids
232 }
233}
234
235impl Binder<'_> {
236 /// Takes the table function argument constraints that belong in the `WHERE`.
237 ///
238 /// An argument such as `json_each(t.tags)` constrains the function's own
239 /// term, so on the right side of a `LEFT JOIN` it is part of that join's
240 /// `ON`. In the `WHERE` it would reject the null extended row of an outer
241 /// row the function returned nothing for. Those are added to the term's
242 /// `ON`; the rest are returned.
243 pub(super) fn pending_for_the_where(&mut self) -> Vec<BoundExpr> {
244 let pending = core::mem::take(&mut self.pending_constraints);
245 let mut for_where = Vec::with_capacity(pending.len());
246 for constraint in pending {
247 let owner = match &constraint {
248 BoundExpr::Compare { left, .. } => match **left {
249 BoundExpr::Column { source, .. } => Some(source),
250 _ => None,
251 },
252 _ => None,
253 };
254 // **Every outer join, not only `LEFT`.** The planner seeks an outer
255 // join's term on its own `ON` alone, so an argument left in the
256 // `WHERE` never reached the function: `a RIGHT JOIN json_each('[..]')`
257 // returned no rows and `RIGHT JOIN generate_series(1, 2)` failed
258 // with "first argument missing". Every row a table function returns
259 // satisfies its arguments, so in the `ON` they null extend nothing.
260 let left_joined = owner
261 .and_then(|id| self.sources.get_mut(id))
262 .filter(|source| crate::plan::is_outer(source.join));
263 match left_joined {
264 Some(source) => {
265 source.constraint = Some(match source.constraint.take() {
266 Some(existing) => BoundExpr::And(Box::new(existing), Box::new(constraint)),
267 None => constraint,
268 });
269 }
270 None => for_where.push(constraint),
271 }
272 }
273 for_where
274 }
275}