quarb_sql/export.rs
1//! The reverse direction: Quarb → SQL.
2//!
3//! Walks the query's *reflection arbor* — the locked vocabulary is
4//! the stable surface for query-rewriting tooling — and emits an
5//! equivalent `SELECT` statement, refusing what the SQL query core
6//! cannot express. Fragments and pure macros expand before
7//! reflection, so they translate for free.
8//!
9//! The translatable subset mirrors the importer: `/table/*`
10//! branches with predicates (→ `WHERE`), witness joins (`<=>` with
11//! `$*1` equality → `JOIN ... ON`, remaining conditions → `WHERE`,
12//! `$*k` select fields qualified), `rec(...)` select lists,
13//! whole-table and grouped aggregates (`GROUP BY`, a filter after
14//! the reduction → `HAVING`), `sort_by`/`reverse`/`top` →
15//! `ORDER BY`/`LIMIT`, `@| [..n]` → `LIMIT`, and single-column
16//! `unique` → `DISTINCT`.
17//!
18//! Deliberately refused: `-->` resolution chains — the foreign-key
19//! targets live in the *schema*, not the query text, so a chain
20//! cannot be compiled to a join without a database at hand; spell
21//! the join explicitly with `<=>` to export it. Also refused:
22//! registers beyond the grouped-aggregate pattern, windows,
23//! captures, and regex matching (`LIKE` dialects disagree).
24//!
25//! Notes carry the standing divergences: truthiness (`[::c]` →
26//! `IS NOT NULL`, but Quarb also treats `0` and `''` as falsy),
27//! `*=` → `LIKE` case-folding dialects, and join cardinality
28//! (Quarb's existential binding never multiplies rows; SQL `JOIN`
29//! does when several left rows match).
30
31use crate::{Refusal, SqlError, Translation};
32use quarb::reflect::QueryArbor;
33use quarb::{AstAdapter, NodeId, Value};
34
35/// Translate a Quarb query to a SQL `SELECT` statement.
36pub fn export(quarb: &str) -> Result<Translation, SqlError> {
37 refuse_marker(quarb)?;
38 let arbor =
39 QueryArbor::parse(quarb).map_err(|e| SqlError::Syntax(format!("parsing Quarb: {e}")))?;
40 refuse_groups(&arbor)?;
41 let mut ex = Exporter {
42 arbor,
43 notes: Vec::new(),
44 strict: false,
45 dialect: None,
46 from_table: String::new(),
47 join_on_cols: Vec::new(),
48 join_table: None,
49 join_every: false,
50 column_types: ColumnTypes::default(),
51 from_sql: String::new(),
52 join_sql: None,
53 in_on: false,
54 order: PlanOrder::default(),
55 aggregate: false,
56 keyed_hops: false,
57 from_marks: Vec::new(),
58 join_marks: Vec::new(),
59 };
60 let query = ex.query()?;
61 Ok(Translation {
62 query,
63 notes: ex.notes,
64 })
65}
66
67/// A part SQL has no form for, under the word its refusal is told
68/// by.
69fn not_pushed(word: Refusal, reason: String) -> SqlError {
70 SqlError::NotPushed {
71 word,
72 mismatch: false,
73 reason,
74 }
75}
76
77/// A part SQL can spell, with other semantics: the reason names the
78/// divergence.
79fn mismatch(word: Refusal, reason: String) -> SqlError {
80 SqlError::NotPushed {
81 word,
82 mismatch: true,
83 reason,
84 }
85}
86
87/// The exporter rewrites `__LEFT__` (the join's left table) and
88/// `__AGG__` (the HAVING aggregate) as internal placeholders.
89/// Query text containing either marker would be rewritten inside
90/// its own string literals — and could spoof the emitted SQL — so
91/// such queries stay on the scan path.
92fn refuse_marker(quarb: &str) -> Result<(), SqlError> {
93 for marker in ["__LEFT__", "__AGG__"] {
94 if quarb.contains(marker) {
95 return Err(not_pushed(
96 Refusal::Name,
97 format!("query text contains the reserved marker \"{marker}\""),
98 ));
99 }
100 }
101 Ok(())
102}
103
104/// A pushdown plan: SQL whose execution is provably identical to
105/// the Quarb query's — plus the table whose primary key must order
106/// the rows (`None` for a single aggregate row, where order is
107/// moot). The driver appends the `ORDER BY`, since the key lives in
108/// its catalog.
109pub struct Pushdown {
110 pub sql: String,
111 pub order_table: Option<String>,
112 /// Present when the plan contains a witness JOIN: the joined
113 /// table and the columns its ON equalities bind on it
114 /// (collected structurally from the arbor, so query text
115 /// cannot spoof them).
116 /// The plan is only sound if those columns form a unique key
117 /// of the joined table — each FROM row must find at most one
118 /// witness, else SQL multiplies rows where Quarb's existential
119 /// binding does not. The *driver* must verify against its
120 /// catalog before executing, and fall back to the scan if it
121 /// cannot.
122 pub join_left: Option<(String, Vec<String>)>,
123 /// Present when the plan is an every-witness JOIN (`<=>*`,
124 /// ruling 2026-11-11): the joined table. Such a JOIN is what the
125 /// query asks, so it carries no uniqueness obligation
126 /// (`join_left` is absent); its obligation is the ORDER: the
127 /// rows of one driver stand in the joined table's own order,
128 /// after the driver's (`order_table`'s key, then this table's).
129 /// A driver that cannot order by both must decline the plan.
130 pub order_then: Option<String>,
131 /// The plan's own sort, in SQL, where it has one: `(n IS NULL),
132 /// n` for `sort_by(::n)`, a null key last as the engine puts it.
133 /// The driver writes it before the keys, which keep the ties in
134 /// the tables' order as the engine's stable sort does.
135 pub order_first: Option<String>,
136 /// The keys descending: the context reversed (`@| reverse`).
137 pub order_desc: bool,
138 /// The plan is a fold: one row a group, in the order each group
139 /// first appears, which the driver writes as the least key of
140 /// each (`ORDER BY MIN(key)`).
141 pub order_groups: bool,
142 /// The first rows alone (`@| [..n]`), after the order.
143 pub limit: Option<u64>,
144 /// The plan's rows are records the query built (`| %(…)`, the
145 /// `%.` of a fold): a row of one column is then a record of one
146 /// field, where a projection's is the bare value.
147 pub record: bool,
148 /// The plan's rows are the records of the rows' own properties
149 /// (`| %`): a NULL cell is no property of its row, and is left
150 /// out of that row's record, as the scan leaves it out.
151 pub properties: bool,
152 /// The column a sort, a fold or a distinct count goes by, with
153 /// the word of that construct. The plan is the scan's only where
154 /// the catalog says the column is numeric (it is among
155 /// `column_types.numeric`), and unlike a comparison the database
156 /// would not refuse it over a text column: it would run, and
157 /// answer its collation's order or its own groups. A caller with
158 /// no catalog to ask scans; one whose catalog says the column is
159 /// not numeric scans and tells of it under the word.
160 pub keyed_by: Option<(Refusal, String)>,
161 /// What the plan takes for granted about column types. Quarb
162 /// compares by value (a numeric-looking text and a number meet
163 /// as numbers, a number and other text never meet); SQL
164 /// compares by the column's type, and the loosely typed engines
165 /// (SQLite, MySQL) coerce by rules of their own. The plan is
166 /// the scan's only where the columns it compares with a number
167 /// are numeric-typed and those it compares with text are not:
168 /// the caller asks its catalog and scans when one is otherwise.
169 /// (A strictly typed engine rejects the mismatch itself, which
170 /// sends the caller to the scan as well.)
171 pub column_types: ColumnTypes,
172 /// The tables the plan reads (the FROM table, then a joined one).
173 pub tables: Vec<String>,
174}
175
176/// The column types a pushed plan assumes (see
177/// [`Pushdown::column_types`]).
178#[derive(Clone, Debug, Default, PartialEq, Eq)]
179pub struct ColumnTypes {
180 /// Columns compared with a numeric literal.
181 pub numeric: Vec<String>,
182 /// Columns compared with a text literal.
183 pub text: Vec<String>,
184 /// Columns the plan extracts a JSON path from on the strength
185 /// of the column's declaration alone (the step carried no
186 /// `<json>`): the pushed `json_extract` is the scan's only where
187 /// the catalog declares the column json, since the scan grafts
188 /// a leaf only as declared (spec: Grafting).
189 pub json: Vec<String>,
190 /// Whether the plan reads a JSON value as a child node of its
191 /// column (`/col/key::`, or the bare `/col/key` of an existence
192 /// test), with `<json>` on the step or without: the scan's only
193 /// where the mount's grafts list scalars as children, which the
194 /// property reading (`?graft=json2`) does not. The property
195 /// form (`/col::key`) answers under both readings and does not
196 /// set it. No assumption about the catalog ([`is_empty`] and
197 /// [`unmet`] leave it out): the front end holds it against its
198 /// mount's reading.
199 ///
200 /// [`is_empty`]: Self::is_empty
201 /// [`unmet`]: Self::unmet
202 pub json_children: bool,
203}
204
205impl ColumnTypes {
206 pub fn is_empty(&self) -> bool {
207 self.numeric.is_empty() && self.text.is_empty() && self.json.is_empty()
208 }
209
210 /// The assumptions a catalog does not bear out: the columns
211 /// compared with a number that are not numeric-typed, and those
212 /// compared with text that are. `catalog` lists every column of
213 /// the tables read, with whether its type is numeric and
214 /// whether it is declared json; names meet without regard to
215 /// case. A column the catalog does not list is unknown, and
216 /// counts as unmet.
217 pub fn unmet(&self, catalog: &[(String, bool, bool)]) -> Vec<String> {
218 let met = |column: &str, pick: fn(&(String, bool, bool)) -> bool, want: bool| {
219 let mut found = catalog
220 .iter()
221 .filter(|(name, ..)| name.eq_ignore_ascii_case(column))
222 .peekable();
223 found.peek().is_some() && found.all(|entry| pick(entry) == want)
224 };
225 let numeric = |e: &(String, bool, bool)| e.1;
226 let json = |e: &(String, bool, bool)| e.2;
227 let mut out: Vec<String> = Vec::new();
228 for (columns, pick, want) in [
229 (
230 &self.numeric,
231 numeric as fn(&(String, bool, bool)) -> bool,
232 true,
233 ),
234 (&self.text, numeric, false),
235 (&self.json, json, true),
236 ] {
237 for c in columns {
238 if !met(c, pick, want) && !out.contains(c) {
239 out.push(c.clone());
240 }
241 }
242 }
243 out
244 }
245}
246
247/// The target SQL dialect, for the one construct whose emitted
248/// SQL is not portable: a filter that navigates *into* a JSON
249/// column, which each engine extracts with its own operator.
250/// The rest of a pushdown is dialect-agnostic. A query with no
251/// JSON-column filter emits identical SQL regardless of dialect.
252#[derive(Clone, Copy, PartialEq, Eq, Debug)]
253pub enum Dialect {
254 Postgres,
255 MySql,
256 Sqlite,
257 Mssql,
258 Oracle,
259}
260
261/// Attempt the pushdown translation: `Some` only when every
262/// construct in the query is in the verified-safe set. Anything
263/// else — including everything `export` would merely annotate with
264/// a divergence note — returns `None`, and the caller scans.
265///
266/// `dialect` enables JSON-column-path pushdown for that engine
267/// (fixed-path string equality only); `None` keeps such filters
268/// on the client-side graft.
269pub fn pushdown(quarb: &str, dialect: Option<Dialect>) -> Option<Pushdown> {
270 pushdown_explained(quarb, dialect).ok()
271}
272
273/// [`pushdown`], keeping the refusal: the error names the first
274/// construct that kept the query on the scan path.
275pub fn pushdown_explained(quarb: &str, dialect: Option<Dialect>) -> Result<Pushdown, SqlError> {
276 refuse_marker(quarb)?;
277 let arbor =
278 QueryArbor::parse(quarb).map_err(|e| SqlError::Syntax(format!("parsing Quarb: {e}")))?;
279 refuse_groups(&arbor)?;
280 let mut ex = Exporter {
281 arbor,
282 notes: Vec::new(),
283 strict: true,
284 dialect,
285 from_table: String::new(),
286 join_on_cols: Vec::new(),
287 join_table: None,
288 join_every: false,
289 column_types: ColumnTypes::default(),
290 from_sql: String::new(),
291 join_sql: None,
292 in_on: false,
293 order: PlanOrder::default(),
294 aggregate: false,
295 keyed_hops: false,
296 from_marks: Vec::new(),
297 join_marks: Vec::new(),
298 };
299 let sql = ex.query()?;
300 let order_table = if ex.aggregate && !ex.order.groups {
301 None
302 } else {
303 // Rows come back in the driver's document order — the FROM
304 // table's (driver-first correlation).
305 Some(ex.from_table.clone())
306 };
307 // an every-witness JOIN multiplies rows by design: no uniqueness
308 // to verify, the joined table's order to keep instead
309 let join_left = if ex.join_every {
310 None
311 } else {
312 ex.join_table.clone().map(|t| (t, ex.join_on_cols.clone()))
313 };
314 let order_then = if ex.join_every && !ex.aggregate {
315 ex.join_table.clone()
316 } else {
317 None
318 };
319 let mut tables = vec![ex.from_table.clone()];
320 tables.extend(ex.join_table.clone());
321 // the plan's own sort: a null key last, the ties left to the
322 // keys; reversed, every term turns
323 let order_first = ex.order.sort.as_ref().map(|(e, desc)| {
324 let nulls = if ex.order.reversed { " DESC" } else { "" };
325 let dir = if *desc != ex.order.reversed {
326 " DESC"
327 } else {
328 ""
329 };
330 format!("({e} IS NULL){nulls}, {e}{dir}")
331 });
332 Ok(Pushdown {
333 sql,
334 order_table,
335 join_left,
336 order_then,
337 order_first,
338 order_desc: ex.order.reversed,
339 order_groups: ex.order.groups,
340 limit: ex.order.limit,
341 record: ex.order.record,
342 properties: ex.order.properties,
343 keyed_by: ex.order.keyed_by.clone(),
344 column_types: ex.column_types.clone(),
345 tables,
346 })
347}
348
349/// The dialect-specific SQL that extracts a JSON scalar at a
350/// fixed object path, unquoted to text. `path` holds plain
351/// object keys (identifier-safe, per `json_path`), so no
352/// per-dialect path-escaping is needed. Each engine's operator
353/// returns the value as text and yields NULL for an absent path
354/// or a non-scalar — matching the graft, which excludes those
355/// rows too.
356fn json_extract(dialect: Dialect, qual: Option<&str>, col: &str, path: &[String]) -> String {
357 let qcol = match qual {
358 Some(q) => format!("{q}.{col}"),
359 None => col.to_string(),
360 };
361 match dialect {
362 // `#>>` takes a text-array path and returns text; the
363 // `::jsonb` cast lets it work on json, jsonb, and
364 // text-holding-JSON columns alike (an invalid-JSON row
365 // errors, and the driver falls back to the scan).
366 Dialect::Postgres => format!("({qcol}::jsonb #>> '{{{}}}')", path.join(",")),
367 // JSON_UNQUOTE(JSON_EXTRACT(...)) is the `->>` shorthand
368 // spelled out — portable across MySQL and MariaDB, where
369 // the `->>` operator itself is not.
370 Dialect::MySql => {
371 format!("JSON_UNQUOTE(JSON_EXTRACT({qcol}, '$.{}'))", path.join("."))
372 }
373 Dialect::Sqlite => format!("json_extract({qcol}, '$.{}')", path.join(".")),
374 // JSON_VALUE returns a scalar as text (lax mode: NULL on a
375 // missing path or a non-scalar, no error).
376 Dialect::Mssql | Dialect::Oracle => format!("JSON_VALUE({qcol}, '$.{}')", path.join(".")),
377 }
378}
379
380/// The columns SQLite's `json_each` answers: inside a subquery over
381/// it an unqualified name of these is its own.
382const JSON_EACH_COLUMNS: &[&str] = &[
383 "key", "value", "type", "atom", "id", "parent", "fullkey", "path", "json", "root",
384];
385
386/// Wrap a JSON-path condition in the dialect's validity guard,
387/// where a cheap one exists. SQLite and MySQL error the whole
388/// statement on one malformed-JSON row — which turned every
389/// pushdown over a dirty table into a silent fallback scan — and
390/// the graft excludes such rows anyway (no parse, no subtree), so
391/// the guard is observationally identical. SQL Server gets ISJSON;
392/// Oracle's JSON_VALUE is lax already; PostgreSQL has no guard
393/// short of the ::jsonb cast itself (an invalid row errors and the
394/// caller falls back to the scan).
395fn json_valid_guard(dialect: Dialect, qual: Option<&str>, col: &str, cond: String) -> String {
396 let qcol = match qual {
397 Some(q) => format!("{q}.{col}"),
398 None => col.to_string(),
399 };
400 match dialect {
401 Dialect::Sqlite => format!("(json_valid({qcol}) AND {cond})"),
402 Dialect::MySql => format!("(JSON_VALID({qcol}) AND {cond})"),
403 Dialect::Mssql => format!("(ISJSON({qcol}) = 1 AND {cond})"),
404 Dialect::Postgres | Dialect::Oracle => format!("({cond})"),
405 }
406}
407
408/// The dialect's JSON type probe at a fixed path — non-NULL iff
409/// the path exists. A JSON `null` value reports its type ('null'),
410/// so existence still sees it, matching the graft, where a
411/// null-valued key is a node. Only the dialects with a native
412/// probe participate.
413fn json_type_probe(
414 dialect: Dialect,
415 qual: Option<&str>,
416 col: &str,
417 path: &[String],
418) -> Option<String> {
419 let qcol = match qual {
420 Some(q) => format!("{q}.{col}"),
421 None => col.to_string(),
422 };
423 match dialect {
424 Dialect::Sqlite => Some(format!("json_type({qcol}, '$.{}')", path.join("."))),
425 Dialect::Postgres => Some(format!(
426 "jsonb_typeof({qcol}::jsonb #> '{{{}}}')",
427 path.join(",")
428 )),
429 Dialect::MySql | Dialect::Mssql | Dialect::Oracle => None,
430 }
431}
432
433/// The literals no match of `pattern` can do without: each is a
434/// substring of every text the regex matches. Read from the regex
435/// crate's own parse (the engine compiles with its defaults): a
436/// literal of a concatenation, of a group, of a repetition that
437/// runs at least once. An alternation, a class (a letter under
438/// `(?i)` is one) and an optional part promise nothing.
439pub(crate) fn required_literals(pattern: &str) -> Vec<String> {
440 use regex_syntax::hir::{Hir, HirKind};
441 fn walk(h: &Hir, out: &mut Vec<String>) {
442 match h.kind() {
443 HirKind::Literal(lit) => {
444 if let Ok(s) = std::str::from_utf8(&lit.0)
445 && !s.is_empty()
446 && !out.iter().any(|o| o == s)
447 {
448 out.push(s.to_string());
449 }
450 }
451 HirKind::Capture(c) => walk(&c.sub, out),
452 HirKind::Concat(parts) => parts.iter().for_each(|p| walk(p, out)),
453 HirKind::Repetition(r) if r.min >= 1 => walk(&r.sub, out),
454 _ => {}
455 }
456 }
457 let Ok(hir) = regex_syntax::parse(pattern) else {
458 return Vec::new();
459 };
460 let mut out = Vec::new();
461 walk(&hir, &mut out);
462 out
463}
464
465/// "`l` holds `lit`", by bytes and case, where the dialect says
466/// exactly that: SQLite's `instr`, and PostgreSQL's `LIKE`, which
467/// is case-sensitive there and reads a `char(n)` value with its
468/// padding, as the engine does. `None` elsewhere, and for a literal
469/// a SQL string would not carry as written on every server (a
470/// quote, a backslash, a control character).
471fn contains_sql(dialect: Dialect, l: &str, lit: &str) -> Option<String> {
472 if lit
473 .chars()
474 .any(|c| c.is_control() || c == '\\' || c == '\'')
475 {
476 return None;
477 }
478 match dialect {
479 Dialect::Sqlite => Some(format!("instr({l}, '{lit}') > 0")),
480 Dialect::Postgres => {
481 let pat = lit.replace('%', "\\%").replace('_', "\\_");
482 Some(format!("{l} LIKE '%{pat}%' ESCAPE '\\'"))
483 }
484 _ => None,
485 }
486}
487
488/// Flip a comparison for a swapped operand order (`lit OP path` →
489/// `path OP' lit`).
490fn flip_op(op: &str) -> String {
491 match op {
492 "<" => ">".into(),
493 "<=" => ">=".into(),
494 ">" => "<".into(),
495 ">=" => "<=".into(),
496 other => other.into(),
497 }
498}
499
500/// SQL keywords that must not appear as a bare identifier or `AS`
501/// alias — quoting them portably differs by dialect, so strict
502/// mode refuses and export mode quotes with double quotes plus a
503/// note.
504const SQL_KEYWORDS: &[&str] = &[
505 "all",
506 "and",
507 "as",
508 "asc",
509 "by",
510 "case",
511 "cross",
512 "desc",
513 "distinct",
514 "else",
515 "end",
516 "except",
517 "exists",
518 "from",
519 "group",
520 "having",
521 "in",
522 "index",
523 "inner",
524 "intersect",
525 "into",
526 "is",
527 "join",
528 "left",
529 "like",
530 "limit",
531 "not",
532 "null",
533 "offset",
534 "on",
535 "or",
536 "order",
537 "outer",
538 "right",
539 "select",
540 "set",
541 "table",
542 "then",
543 "union",
544 "unique",
545 "update",
546 "using",
547 "values",
548 "when",
549 "where",
550];
551
552/// A bare SQL identifier, portable across the target dialects: a
553/// letter or underscore, then letters, digits, and underscores,
554/// and not a reserved word.
555fn is_plain_ident(name: &str) -> bool {
556 !name.is_empty()
557 && name
558 .chars()
559 .next()
560 .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
561 && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
562 && !SQL_KEYWORDS.contains(&name.to_ascii_lowercase().as_str())
563}
564
565/// The SELECT under construction.
566#[derive(Default)]
567struct Select {
568 select: Vec<String>,
569 distinct: bool,
570 from: String,
571 join: Option<(String, String)>, // (table, ON condition)
572 /// The join keeps every FROM row (`<=>?`, the outer
573 /// correlation): a LEFT JOIN.
574 join_outer: bool,
575 wheres: Vec<String>,
576 group_by: Option<String>,
577 having: Option<String>,
578 order_by: Option<(String, bool)>, // (expr, desc)
579 limit: Option<String>,
580}
581
582impl Select {
583 fn render(&self) -> String {
584 let mut out = String::from("SELECT ");
585 if self.distinct {
586 out.push_str("DISTINCT ");
587 }
588 if self.select.is_empty() {
589 out.push('*');
590 } else {
591 out.push_str(&self.select.join(", "));
592 }
593 out.push_str(&format!(" FROM {}", self.from));
594 if let Some((t, on)) = &self.join {
595 let kind = if self.join_outer { "LEFT JOIN" } else { "JOIN" };
596 out.push_str(&format!(" {kind} {t} ON {on}"));
597 }
598 if !self.wheres.is_empty() {
599 out.push_str(&format!(" WHERE {}", self.wheres.join(" AND ")));
600 }
601 if let Some(g) = &self.group_by {
602 out.push_str(&format!(" GROUP BY {g}"));
603 }
604 if let Some(h) = &self.having {
605 out.push_str(&format!(" HAVING {h}"));
606 }
607 if let Some((e, desc)) = &self.order_by {
608 out.push_str(&format!(" ORDER BY {e}"));
609 if *desc {
610 out.push_str(" DESC");
611 }
612 }
613 if let Some(n) = &self.limit {
614 out.push_str(&format!(" LIMIT {n}"));
615 }
616 out
617 }
618}
619
620/// A partial-pushdown plan: the leading row predicates as a WHERE
621/// clause for `table`'s fetch. The caller runs the *original* query
622/// against the filtered adapter — the engine re-applies the pushed
623/// predicates (a no-op on pre-filtered rows), so no rewriting.
624pub struct Partial {
625 pub table: String,
626 pub where_sql: String,
627 /// As [`Pushdown::column_types`]: the prefilter keeps every row
628 /// the scan would only where these assumptions hold.
629 pub column_types: ColumnTypes,
630}
631
632/// Attempt a partial pushdown: `Some` when the query's leading row
633/// predicates translate strictly and the rest of the query provably
634/// cannot observe the filtering. The gates, each with its reason:
635/// a single `/table/*` branch with no correlations (other shapes
636/// address other data); only the *leading* run of expression
637/// predicates pushes (a positional predicate before an expression
638/// one sees unfiltered rows on the scan path); the table's name
639/// appears exactly once among the query's steps (a second reach —
640/// `^`-anchored subcontexts, self-references — would see the
641/// filtered subset); no crosslink or resolution axes anywhere
642/// (backlinks and reverse resolution into the table would too);
643/// and no `:` / `:::` metadata anywhere (a filtered `:::n-rows`
644/// would lie).
645pub fn partial_pushdown(quarb: &str, dialect: Option<Dialect>) -> Option<Partial> {
646 partial_pushdown_explained(quarb, dialect).ok()
647}
648
649/// [`partial_pushdown`], keeping the refusal reason. `dialect`
650/// enables the JSON-column prefilters — the strict fixed-path
651/// string equality, plus the relaxed superset forms (numeric
652/// comparisons, existence) that are safe here and only here,
653/// because the caller re-runs the original query over the
654/// fetched subset.
655pub fn partial_pushdown_explained(
656 quarb: &str,
657 dialect: Option<Dialect>,
658) -> Result<Partial, SqlError> {
659 partial_pushdown_with(quarb, dialect, false)
660}
661
662/// [`partial_pushdown_explained`] for an adapter that reads steps by
663/// key and filters only the table's listing
664/// (`RelationalModel::with_filtered_listing`): crosslinks and
665/// resolutions no longer refuse the prefilter, since a step into the
666/// filtered table reads its row unfiltered. What still refuses: a
667/// second navigation into the table, and a `<--` or `=>` scope that
668/// could list it.
669pub fn partial_pushdown_keyed(quarb: &str, dialect: Option<Dialect>) -> Result<Partial, SqlError> {
670 partial_pushdown_with(quarb, dialect, true)
671}
672
673fn partial_pushdown_with(
674 quarb: &str,
675 dialect: Option<Dialect>,
676 keyed_hops: bool,
677) -> Result<Partial, SqlError> {
678 refuse_marker(quarb)?;
679 let arbor =
680 QueryArbor::parse(quarb).map_err(|e| SqlError::Syntax(format!("parsing Quarb: {e}")))?;
681 refuse_groups(&arbor)?;
682 let mut ex = Exporter {
683 arbor,
684 notes: Vec::new(),
685 strict: true,
686 dialect,
687 from_table: String::new(),
688 join_on_cols: Vec::new(),
689 join_table: None,
690 join_every: false,
691 column_types: ColumnTypes::default(),
692 from_sql: String::new(),
693 join_sql: None,
694 in_on: false,
695 order: PlanOrder::default(),
696 aggregate: false,
697 keyed_hops,
698 from_marks: Vec::new(),
699 join_marks: Vec::new(),
700 };
701 ex.partial()
702}
703
704/// Refuse a query carrying path-pattern groups: neither the SQL
705/// translation nor the pushdown safe set covers them, and the shape
706/// checks below count only `step` children — an unguarded group
707/// would silently vanish from the translation. Refused queries fall
708/// back to the scan path, which evaluates groups correctly.
709fn refuse_groups(arbor: &QueryArbor) -> Result<(), SqlError> {
710 let mut stack = vec![arbor.root()];
711 while let Some(n) = stack.pop() {
712 if arbor.name(n).as_deref() == Some("group") {
713 return Err(not_pushed(
714 Refusal::Walk,
715 "path patterns (groups and quantifiers)".into(),
716 ));
717 }
718 stack.extend(arbor.children(n));
719 }
720 Ok(())
721}
722
723/// The order a strict plan asks its driver for ([`Pushdown`]'s
724/// `order_first`, `order_desc`, `order_groups`, `limit`).
725#[derive(Default)]
726struct PlanOrder {
727 /// `sort_by(::n)`: the key as SQL, and whether `--desc`.
728 sort: Option<(String, bool)>,
729 /// `@| reverse`.
730 reversed: bool,
731 /// `@| [..n]`.
732 limit: Option<u64>,
733 /// A fold by one key.
734 groups: bool,
735 /// The numeric column the plan sorts, folds or counts distinct
736 /// by, and the word of the construct.
737 keyed_by: Option<(Refusal, String)>,
738 /// The rows are records the query built.
739 record: bool,
740 /// The records are the rows' own properties (`| %`): a NULL
741 /// cell is left out of its row's record.
742 properties: bool,
743}
744
745struct Exporter {
746 arbor: QueryArbor,
747 notes: Vec<String>,
748 /// Pushdown mode: refuse every construct whose SQL semantics
749 /// are not provably identical to Quarb's (LIKE case folding,
750 /// truthiness, group/distinct/sort ordering).
751 strict: bool,
752 /// The target dialect for JSON-column-path pushdown; `None`
753 /// leaves such filters on the client-side graft.
754 dialect: Option<Dialect>,
755 from_table: String,
756 join_on_cols: Vec<String>,
757 join_table: Option<String>,
758 /// The correlation is `<=>*`: every witness, the SQL JOIN itself.
759 join_every: bool,
760 /// What the comparisons assume of column types (see
761 /// [`Pushdown::column_types`]).
762 column_types: ColumnTypes,
763 from_sql: String,
764 join_sql: Option<String>,
765 in_on: bool,
766 /// The order of a strict plan, for its driver.
767 order: PlanOrder,
768 aggregate: bool,
769 /// The adapter reads steps by key (the pushed-down WHERE filters
770 /// the table's listing only), so crosslinks and resolutions are
771 /// safe beside the prefilter.
772 keyed_hops: bool,
773 /// The names the driver's rows are marked under (`/tracks/* .t`)
774 /// and the names the joined expression files its witness under
775 /// (`<=> /albums/*[…] .al`): `$$.t::col` is the FROM table's
776 /// column, `$$.al::col` the joined table's.
777 from_marks: Vec<String>,
778 join_marks: Vec<String>,
779}
780
781impl Exporter {
782 fn kids(&self, n: NodeId, kind: &str) -> Vec<NodeId> {
783 self.arbor
784 .children(n)
785 .into_iter()
786 .filter(|&c| self.arbor.name(c).as_deref() == Some(kind))
787 .collect()
788 }
789
790 fn kid(&self, n: NodeId, kind: &str) -> Option<NodeId> {
791 self.kids(n, kind).into_iter().next()
792 }
793
794 fn prop(&self, n: NodeId, key: &str) -> Option<Value> {
795 self.arbor.property(n, key)
796 }
797
798 fn prop_s(&self, n: NodeId, key: &str) -> String {
799 self.prop(n, key).map(|v| v.to_string()).unwrap_or_default()
800 }
801
802 fn kind(&self, n: NodeId) -> String {
803 self.arbor.name(n).unwrap_or_default()
804 }
805
806 /// Whether `n` is a bare `null` literal operand.
807 fn is_null_literal(&self, n: NodeId) -> bool {
808 self.kind(n) == "literal" && self.prop_s(n, "type") == "null"
809 }
810
811 /// The partial-pushdown analysis (see [`partial_pushdown`]).
812 fn partial(&mut self) -> Result<Partial, SqlError> {
813 let root = self.arbor.root();
814 let q = self
815 .kid(root, "query")
816 .ok_or_else(|| not_pushed(Refusal::Name, "empty query".into()))?;
817 // A correlation does not forbid the prefilter: the driver's
818 // own predicates restrict the driver's rows whatever the join
819 // then binds. What must not happen is the join (or anything
820 // else) reaching the filtered table a second time — a
821 // self-join would see only the filtered rows — and the
822 // whole-query gates below refuse exactly that: they walk the
823 // correlation entries too.
824 let branches = self.kids(q, "branch");
825 if branches.len() != 1 {
826 return Err(not_pushed(Refusal::Union, "a branch union".into()));
827 }
828 let (table, preds) = self.table_branch_lead(branches[0], self.keyed_hops)?;
829
830 // Whole-query gates.
831 let all = self.walk_all(root);
832 let mut table_mentions = 0;
833 for n in &all {
834 match self.kind(*n).as_str() {
835 "step" => {
836 let axis = self.prop_s(*n, "axis");
837 // A crosslink, a resolution or a value match may
838 // land in (or search) the filtered table and would
839 // see only its filtered rows: `=>` and the scoped
840 // `<--` carry their scope as text, so the table
841 // count below cannot see them.
842 if matches!(axis.as_str(), "->" | "<-" | "--" | "-->" | "<--" | "=>") {
843 // Where steps are read by key they are exact
844 // beside the prefilter. A scope is a listing,
845 // though: it is safe only when it plainly
846 // lists another table (`/other/…`), and an
847 // unscoped `=>` walks every table.
848 let scope = self.prop_s(*n, "scope");
849 let lists_other_table = scope
850 .strip_prefix('/')
851 .and_then(|rest| rest.split(['/', '[', '<']).next())
852 .is_some_and(|first| {
853 !first.is_empty()
854 && first != table
855 && first.chars().all(|c| c.is_alphanumeric() || c == '_')
856 });
857 let safe = self.keyed_hops
858 && if scope.is_empty() {
859 axis != "=>"
860 } else {
861 lists_other_table
862 };
863 if !safe {
864 return Err(not_pushed(
865 Refusal::Condition,
866 "crosslink/resolution axes could reach \
867 the filtered table"
868 .into(),
869 ));
870 }
871 }
872 if self.prop_s(*n, "matcher") == table {
873 table_mentions += 1;
874 }
875 }
876 "projection" if self.prop_s(*n, "kind") != "property" => {
877 return Err(not_pushed(
878 Refusal::Condition,
879 "metadata would observe the filtering \
880 (:::n-rows, :index)"
881 .into(),
882 ));
883 }
884 _ => {}
885 }
886 }
887 if table_mentions != 1 {
888 return Err(not_pushed(
889 Refusal::Condition,
890 "the table is reached more than once".into(),
891 ));
892 }
893
894 // The leading run of expression predicates. Strict
895 // translation first; a predicate the strict translator
896 // refuses tries the relaxed prefilter ladder — superset
897 // semantics: the fetched set may hold extra rows, because
898 // the caller re-runs the ORIGINAL query, which re-applies
899 // every predicate; it must never lose a matching row. An
900 // untranslatable predicate is skipped, not fatal — a
901 // shorter conjunction is still a superset filter. A
902 // positional predicate (index/range) ends the run:
903 // predicates after it filter a positionally-selected
904 // subsequence.
905 let mut conds = Vec::new();
906 for p in preds {
907 if self.prop_s(p, "kind") != "expr" {
908 break;
909 }
910 match self.predicate_cond(p, None) {
911 Ok(c) => conds.push(c),
912 Err(_) => {
913 if let Some(c) = self.prefilter_cond(p) {
914 conds.push(c);
915 }
916 }
917 }
918 }
919 if conds.is_empty() {
920 return Err(not_pushed(
921 Refusal::Nothing,
922 "no leading expression predicates to push".into(),
923 ));
924 }
925 Ok(Partial {
926 table,
927 where_sql: conds.join(" AND "),
928 column_types: self.column_types.clone(),
929 })
930 }
931
932 /// The relaxed prefilter for one refused expression predicate:
933 /// the AND of whatever conjuncts translate, each a superset of
934 /// the rows its Quarb counterpart keeps. None when nothing
935 /// does — the predicate stays entirely on the engine.
936 fn prefilter_cond(&mut self, p: NodeId) -> Option<String> {
937 let parts: Vec<String> = self
938 .arbor
939 .children(p)
940 .into_iter()
941 .filter_map(|c| {
942 self.pred_expr(c, None)
943 .ok()
944 .or_else(|| self.prefilter_expr(c))
945 })
946 .collect();
947 if parts.is_empty() {
948 None
949 } else {
950 Some(parts.join(" AND "))
951 }
952 }
953
954 /// One conjunct's superset prefilter — fixed-path JSON shapes
955 /// only, per dialect. Every form here is proven to keep every
956 /// row the graft would match (extras are fine; the engine
957 /// re-checks). The proofs lean on three graft facts: absent
958 /// paths match no comparison; `value_eq`/`value_cmp` coerce
959 /// numeric-looking strings numerically; and Str-to-Str
960 /// ordering is bytewise.
961 fn prefilter_expr(&mut self, e: NodeId) -> Option<String> {
962 let dialect = self.dialect?;
963 match self.kind(e).as_str() {
964 // A bare truthy path: existence (with `::`, value
965 // truthiness — existence is its superset). The type
966 // probe sees JSON null too, as the graft does.
967 "path" => {
968 // The property form (`/col/a::b`) is truthy on a
969 // scalar and on a list with an item: the key is
970 // present either way, so existence is its superset
971 // too.
972 let (col, path) = self
973 .json_path_loose(e)
974 .or_else(|| self.json_property_path(e))?;
975 self.note_json_column(e, &col);
976 let probe = json_type_probe(dialect, None, &col, &path)?;
977 Some(json_valid_guard(
978 dialect,
979 None,
980 &col,
981 format!("{probe} IS NOT NULL"),
982 ))
983 }
984 // A conjunction keeps what either side keeps and more
985 // when one side is left out; a disjunction needs both.
986 "and" | "or" => {
987 let kind = self.kind(e);
988 let sides: Vec<Option<String>> = self
989 .arbor
990 .children(e)
991 .into_iter()
992 .map(|c| {
993 self.pred_expr(c, None)
994 .ok()
995 .or_else(|| self.prefilter_expr(c))
996 })
997 .collect();
998 if kind == "or" {
999 let sides: Option<Vec<String>> = sides.into_iter().collect();
1000 return sides
1001 .filter(|s| !s.is_empty())
1002 .map(|s| format!("({})", s.join(" OR ")));
1003 }
1004 let sides: Vec<String> = sides.into_iter().flatten().collect();
1005 (!sides.is_empty()).then(|| format!("({})", sides.join(" AND ")))
1006 }
1007 "compare" => {
1008 let op = self.prop_s(e, "op");
1009 let kids = self.arbor.children(e);
1010 if kids.len() != 2 {
1011 return None;
1012 }
1013 if op == "==" {
1014 return self.regex_prefilter(dialect, &kids);
1015 }
1016 for (pi, li) in [(0usize, 1usize), (1, 0)] {
1017 let Some((col, path)) = self.json_path(kids[pi]) else {
1018 continue;
1019 };
1020 if self.kind(kids[li]) != "literal" {
1021 continue;
1022 }
1023 let ty = self.prop_s(kids[li], "type");
1024 if ty == "null" {
1025 return None;
1026 }
1027 let raw = self
1028 .prop(kids[li], "value")
1029 .map(|v| v.to_string())
1030 .unwrap_or_default();
1031 let op = if pi == 0 { op.clone() } else { flip_op(&op) };
1032 self.note_json_column(kids[pi], &col);
1033 return self.json_prefilter(dialect, &col, &path, &op, &ty, &raw);
1034 }
1035 // The property form, `/col/a::b OP literal`.
1036 for (pi, li) in [(0usize, 1usize), (1, 0)] {
1037 let Some((col, path)) = self.json_property_path(kids[pi]) else {
1038 continue;
1039 };
1040 if self.kind(kids[li]) != "literal" {
1041 continue;
1042 }
1043 let ty = self.prop_s(kids[li], "type");
1044 if ty == "null" {
1045 return None;
1046 }
1047 let raw = self
1048 .prop(kids[li], "value")
1049 .map(|v| v.to_string())
1050 .unwrap_or_default();
1051 let op = if pi == 0 { op.clone() } else { flip_op(&op) };
1052 self.note_json_column(kids[pi], &col);
1053 return self.json_property_prefilter(dialect, &col, &path, &op, &ty, &raw);
1054 }
1055 None
1056 }
1057 _ => None,
1058 }
1059 }
1060
1061 /// The superset prefilter for `::col == (/regex/)`: every literal
1062 /// the regex cannot match without is a substring of the text it
1063 /// matches, so the rows that hold them all are a superset of the
1064 /// rows the engine keeps; the engine runs the regex itself over
1065 /// what is fetched. A NULL holds no substring and matches no
1066 /// regex. The column is recorded as a text one, for the caller's
1067 /// catalog check: a number would be searched in the database's
1068 /// rendering of it, not the engine's.
1069 fn regex_prefilter(&mut self, dialect: Dialect, kids: &[NodeId]) -> Option<String> {
1070 if !self.is_text_literal(kids[1]) {
1071 return None;
1072 }
1073 let column = self.column_operand(kids[0])?;
1074 let pattern = self.prop(kids[1], "value")?.to_string();
1075 let literals = required_literals(&pattern);
1076 let l = self.operand(kids[0], None).ok()?;
1077 let conds: Vec<String> = literals
1078 .iter()
1079 .filter_map(|lit| contains_sql(dialect, &l, lit))
1080 .collect();
1081 if conds.is_empty() {
1082 return None;
1083 }
1084 if !self.column_types.text.contains(&column) {
1085 self.column_types.text.push(column);
1086 }
1087 Some(conds.join(" AND "))
1088 }
1089
1090 /// The superset prefilter for `/col/a::b OP literal`, the
1091 /// property form of a JSON path. It is [`json_prefilter`] with
1092 /// the two places where a property differs from a child's value:
1093 ///
1094 /// - an ARRAY of scalars is a list, and a list in a comparison
1095 /// matches when any item does (`[::tags = 'a']` keeps
1096 /// `{"tags": ["a", "b"]}`); the child form's `/tags::` has no
1097 /// value there. So every form lets the arrays through for the
1098 /// engine to decide;
1099 /// - `!=` keeps a row whose key is ABSENT (null is not the
1100 /// literal), where the child form has no node and no thread.
1101 /// Its floor is the existence of the node the property is
1102 /// read on; on the column itself there is none (a cell that
1103 /// is no JSON still answers a null property).
1104 ///
1105 /// [`json_prefilter`]: Self::json_prefilter
1106 fn json_property_prefilter(
1107 &self,
1108 d: Dialect,
1109 col: &str,
1110 path: &[String],
1111 op: &str,
1112 lit_ty: &str,
1113 raw: &str,
1114 ) -> Option<String> {
1115 if !matches!(op, "=" | "!=" | "<" | "<=" | ">" | ">=") {
1116 return None;
1117 }
1118 if op == "!=" {
1119 let owner = &path[..path.len() - 1];
1120 if owner.is_empty() {
1121 return None;
1122 }
1123 let probe = json_type_probe(d, None, col, owner)?;
1124 return Some(json_valid_guard(
1125 d,
1126 None,
1127 col,
1128 format!("{probe} IS NOT NULL"),
1129 ));
1130 }
1131 let ty = json_type_probe(d, None, col, path)?;
1132 let numeric_lit = raw.trim().parse::<f64>().is_ok_and(|f| f.is_finite())
1133 && (lit_ty != "text" || !raw.trim().is_empty());
1134 if numeric_lit {
1135 let num: f64 = raw.trim().parse().ok()?;
1136 if num.abs() >= 9_007_199_254_740_992.0 {
1137 return None;
1138 }
1139 let lit = raw.trim();
1140 match d {
1141 Dialect::Sqlite => {
1142 let ex = json_extract(d, None, col, path);
1143 Some(json_valid_guard(
1144 d,
1145 None,
1146 col,
1147 format!("({ex} {op} {lit} OR {ty} IN ('text', 'array'))"),
1148 ))
1149 }
1150 Dialect::Postgres => {
1151 let text = json_extract(d, None, col, path);
1152 Some(format!(
1153 "(CASE WHEN {ty} = 'number' THEN ({text})::float8 {op} {lit} \
1154 WHEN {ty} IN ('string', 'array') THEN true ELSE false END)"
1155 ))
1156 }
1157 Dialect::MySql | Dialect::Mssql | Dialect::Oracle => None,
1158 }
1159 } else if lit_ty == "text" {
1160 if raw.contains('\'') || raw.contains('\\') {
1161 return None;
1162 }
1163 match d {
1164 Dialect::Sqlite => {
1165 let ex = json_extract(d, None, col, path);
1166 Some(json_valid_guard(
1167 d,
1168 None,
1169 col,
1170 format!("({ex} {op} '{raw}' OR {ty} = 'array')"),
1171 ))
1172 }
1173 // Equality alone: a string equals the literal or it
1174 // does not (a looser collation keeps more, never
1175 // fewer); ordering runs into collation, as in the
1176 // child form.
1177 Dialect::Postgres if op == "=" => {
1178 let text = json_extract(d, None, col, path);
1179 Some(format!(
1180 "(CASE WHEN {ty} = 'string' THEN {text} = '{raw}' \
1181 WHEN {ty} = 'array' THEN true ELSE false END)"
1182 ))
1183 }
1184 _ => None,
1185 }
1186 } else {
1187 None
1188 }
1189 }
1190
1191 /// Build the dialect's superset prefilter for
1192 /// `json_path OP literal`.
1193 fn json_prefilter(
1194 &self,
1195 d: Dialect,
1196 col: &str,
1197 path: &[String],
1198 op: &str,
1199 lit_ty: &str,
1200 raw: &str,
1201 ) -> Option<String> {
1202 if !matches!(op, "=" | "!=" | "<" | "<=" | ">" | ">=") {
1203 return None;
1204 }
1205 // `!=` matches every present path whose value isn't the
1206 // literal — including JSON null and cross-typed values —
1207 // so its floor is existence.
1208 if op == "!=" {
1209 let probe = json_type_probe(d, None, col, path)?;
1210 return Some(json_valid_guard(
1211 d,
1212 None,
1213 col,
1214 format!("{probe} IS NOT NULL"),
1215 ));
1216 }
1217 let numeric_lit = raw.trim().parse::<f64>().is_ok_and(|f| f.is_finite())
1218 && (lit_ty != "text" || !raw.trim().is_empty());
1219 if numeric_lit {
1220 let num: f64 = raw.trim().parse().ok()?;
1221 // Past 2^53 the engines' exact integers and the
1222 // graft's f64 part ways at the boundary.
1223 if num.abs() >= 9_007_199_254_740_992.0 {
1224 return None;
1225 }
1226 let lit = raw.trim();
1227 match d {
1228 // Typed extract: JSON numbers compare numerically
1229 // (both sides parse the same source text to f64);
1230 // string values escape through the type probe —
1231 // the graft may coerce them, the server must not
1232 // drop them.
1233 Dialect::Sqlite => {
1234 let ex = json_extract(d, None, col, path);
1235 let ty = json_type_probe(d, None, col, path)?;
1236 Some(json_valid_guard(
1237 d,
1238 None,
1239 col,
1240 format!("({ex} {op} {lit} OR {ty} = 'text')"),
1241 ))
1242 }
1243 // float8 is the graft's f64; jsonb numbers print
1244 // exactly, so the cast parses the same decimal.
1245 // Strings escape; everything else can't match.
1246 Dialect::Postgres => {
1247 let text = json_extract(d, None, col, path);
1248 let ty = json_type_probe(d, None, col, path)?;
1249 Some(format!(
1250 "(CASE WHEN {ty} = 'number' THEN ({text})::float8 {op} {lit} \
1251 WHEN {ty} = 'string' THEN true ELSE false END)"
1252 ))
1253 }
1254 Dialect::MySql | Dialect::Mssql | Dialect::Oracle => None,
1255 }
1256 } else if lit_ty == "text" {
1257 if raw.contains('\'') || raw.contains('\\') {
1258 return None;
1259 }
1260 match d {
1261 // Typed extract again: string values order bytewise
1262 // on both sides; numbers and booleans sit below
1263 // text in SQLite's cross-type order, so `<` keeps
1264 // them (extras, re-checked) and `>` drops them
1265 // (the graft refuses to order Str against them).
1266 Dialect::Sqlite => {
1267 let ex = json_extract(d, None, col, path);
1268 Some(json_valid_guard(d, None, col, format!("{ex} {op} '{raw}'")))
1269 }
1270 // Text ordering elsewhere runs into collation; the
1271 // engine keeps those.
1272 _ => None,
1273 }
1274 } else {
1275 None
1276 }
1277 }
1278
1279 /// [`json_path`], loosened for existence: the projection may
1280 /// be absent (a bare structural path) as well as the bare
1281 /// `::`.
1282 /// Whether a JSON path under a column reads the column as JSON
1283 /// on the strength of its declaration alone: the column step
1284 /// (the first step) carries no `<json>` trait. Such a column is
1285 /// an assumption of the plan ([`ColumnTypes::json`]); with the
1286 /// trait the graft is declared on the step and holds on both
1287 /// roads.
1288 fn note_json_column(&mut self, o: NodeId, col: &str) {
1289 let declared_on_hop = self.kids(o, "step").first().is_some_and(|s| {
1290 self.kids(*s, "trait").iter().any(|t| {
1291 matches!(self.prop(*t, "alts"), Some(Value::List(alts))
1292 if alts.iter().any(|a| matches!(a, Value::Str(x) if x == "json")))
1293 })
1294 });
1295 if !declared_on_hop && !self.column_types.json.iter().any(|c| c == col) {
1296 self.column_types.json.push(col.to_string());
1297 }
1298 // The child form (the bare `::`, or no projection): what the
1299 // property reading leaves empty.
1300 let keyed = self
1301 .kid(o, "projection")
1302 .is_some_and(|p| self.prop(p, "key").is_some());
1303 if !keyed {
1304 self.column_types.json_children = true;
1305 }
1306 }
1307
1308 fn json_path_loose(&self, o: NodeId) -> Option<(String, Vec<String>)> {
1309 if self.json_path(o).is_some() {
1310 return self.json_path(o);
1311 }
1312 if self.kind(o) != "path" || self.kid(o, "projection").is_some() {
1313 return None;
1314 }
1315 let steps = self.kids(o, "step");
1316 if steps.len() < 2 {
1317 return None;
1318 }
1319 let mut names = Vec::with_capacity(steps.len());
1320 for s in &steps {
1321 if self.prop_s(*s, "axis") != "/"
1322 || self.prop_s(*s, "matcher-kind") != "name"
1323 || self.kid(*s, "predicate").is_some()
1324 {
1325 return None;
1326 }
1327 let name = self.prop_s(*s, "matcher");
1328 let plain = !name.is_empty()
1329 && name
1330 .chars()
1331 .next()
1332 .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
1333 && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
1334 if !plain {
1335 return None;
1336 }
1337 names.push(name);
1338 }
1339 let col = names.remove(0);
1340 Some((col, names))
1341 }
1342
1343 fn walk_all(&self, n: NodeId) -> Vec<NodeId> {
1344 let mut out = vec![n];
1345 let mut i = 0;
1346 while i < out.len() {
1347 out.extend(self.arbor.children(out[i]));
1348 i += 1;
1349 }
1350 out
1351 }
1352
1353 fn query(&mut self) -> Result<String, SqlError> {
1354 let root = self.arbor.root();
1355 let q = self
1356 .kid(root, "query")
1357 .ok_or_else(|| not_pushed(Refusal::Name, "empty query".into()))?;
1358 let mut sel = Select::default();
1359
1360 // Correlations: exactly one becomes the JOIN's left table.
1361 let corrs = self.kids(q, "query");
1362 let branches = self.kids(q, "branch");
1363 if branches.len() != 1 {
1364 return Err(not_pushed(
1365 Refusal::Union,
1366 "a branch union (SQL has UNION, but result shapes differ; export one branch)"
1367 .into(),
1368 ));
1369 }
1370
1371 if corrs.len() > 1 {
1372 return Err(not_pushed(
1373 Refusal::Join,
1374 "more than one correlation context".into(),
1375 ));
1376 }
1377 if let Some(corr) = corrs.first() {
1378 // Driver-first: the query's own branch is the FROM
1379 // table (the driver); the correlation entry is the
1380 // joined table, whose `$$` equalities form the ON.
1381 let (ltable, lpreds) = self.table_branch(branches[0])?;
1382 let (rtable, rpreds) = self.table_branch(self.kids(*corr, "branch")[0])?;
1383 self.from_marks = self.row_marks(branches[0])?;
1384 self.join_marks = self.row_marks(self.kids(*corr, "branch")[0])?;
1385 // a joined expression with a pipeline of its own binds
1386 // what that pipeline leaves: not a row of its table
1387 if self.kid(*corr, "pipeline").is_some() {
1388 return Err(not_pushed(
1389 Refusal::Join,
1390 "a joined expression with a pipeline of its own".into(),
1391 ));
1392 }
1393 // The SQL renderings of the two table names (validated
1394 // or quoted); the raw names stay in the plan metadata,
1395 // which the driver matches against its catalog.
1396 let lsql = self.sql_ident(<able, "table name")?;
1397 let rsql = self.sql_ident(&rtable, "table name")?;
1398 self.from_sql = lsql.clone();
1399 self.join_sql = Some(rsql.clone());
1400 // The driver's own predicates are plain WHERE.
1401 let driver_conds: Vec<NodeId> = lpreds;
1402 // Split the joined expression's predicates: `$$`
1403 // equalities form the ON, the rest the WHERE.
1404 let mut on = Vec::new();
1405 let mut wheres = Vec::new();
1406 for p in rpreds {
1407 self.split_join_pred(p, &rsql, &mut on, &mut wheres)?;
1408 }
1409 // `<=>?` — the outer correlation keeps a driver row no
1410 // joined row admits, its witness null: a LEFT JOIN. The
1411 // joined expression's own predicates then select the
1412 // witness, so they belong to the ON; in a WHERE they
1413 // would discard the unmatched rows again.
1414 let outer = matches!(self.prop(*corr, "outer"), Some(Value::Bool(true)));
1415 if outer {
1416 on.append(&mut wheres);
1417 }
1418 sel.join_outer = outer;
1419 if on.is_empty() {
1420 return Err(not_pushed(
1421 Refusal::Join,
1422 "a correlation without a '$$' equality (no JOIN condition)".into(),
1423 ));
1424 }
1425 for p in driver_conds {
1426 let cond = self.predicate_cond(p, Some(&lsql.clone()))?;
1427 wheres.push(cond);
1428 }
1429 // `<=>*` — every witness: the JOIN as SQL means it, one
1430 // row per matching pair; the plain `<=>` binds one.
1431 self.join_every = matches!(self.prop(*corr, "every"), Some(Value::Bool(true)));
1432 if !self.join_every {
1433 self.notes.push(
1434 "JOIN: Quarb's binding is existential (one row per FROM row, \
1435 bound to its first witness); SQL multiplies rows when \
1436 several joined rows match"
1437 .to_string(),
1438 );
1439 }
1440 sel.from = lsql.clone();
1441 self.from_table = ltable;
1442 self.join_table = Some(rtable);
1443 sel.join = Some((rsql.clone(), on.join(" AND ")));
1444 sel.wheres = wheres;
1445 // A terminal projection on the driving branch is a
1446 // one-column select of the FROM table.
1447 let mut projected = None;
1448 if let Some(proj) = self.kid(branches[0], "projection") {
1449 let name = self.projection_col(proj)?;
1450 let col = self.sql_ident(&name, "column name")?;
1451 let col = format!("{lsql}.{col}");
1452 sel.select.push(col.clone());
1453 projected = Some((col, name));
1454 }
1455 if self
1456 .kid(self.kids(*corr, "branch")[0], "projection")
1457 .is_some()
1458 {
1459 return Err(not_pushed(
1460 Refusal::Join,
1461 "a projection on the joined expression (project the witness \
1462 in the pipeline: '$$1::col')"
1463 .into(),
1464 ));
1465 }
1466 self.pipeline(q, &mut sel, Some((&lsql, &rsql)), projected)?;
1467 } else {
1468 let (table, preds) = self.table_branch(branches[0])?;
1469 self.from_marks = self.row_marks(branches[0])?;
1470 sel.from = self.sql_ident(&table, "table name")?;
1471 self.from_table = table;
1472 for p in preds {
1473 let cond = self.predicate_cond(p, None)?;
1474 sel.wheres.push(cond);
1475 }
1476 // A terminal projection is a one-column select.
1477 let mut projected = None;
1478 if let Some(proj) = self.kid(branches[0], "projection") {
1479 let name = self.projection_col(proj)?;
1480 let col = self.sql_ident(&name, "column name")?;
1481 sel.select.push(col.clone());
1482 projected = Some((col, name));
1483 }
1484 self.pipeline(q, &mut sel, None, projected)?;
1485 }
1486 // A whole plan answers values: a column, a record, a
1487 // reduction. A query that ends on row nodes is answered by
1488 // their locators, which are the scan's to write (ruling
1489 // 2026-11-18); it was pushed as SELECT * and printed each
1490 // row as a record, where the scan printed `/books/1`. Its
1491 // conditions still go ahead of the scan through the partial
1492 // plan, and nothing the reader wrote is refused, so the
1493 // refusal carries no code.
1494 if self.strict && sel.select.is_empty() {
1495 return Err(not_pushed(
1496 Refusal::Nodes,
1497 "a selection of row nodes is answered by their locators".into(),
1498 ));
1499 }
1500 Ok(sel.render())
1501 }
1502
1503 /// A `/table/*[preds]` branch: the table name and the row-step
1504 /// predicate nodes.
1505 fn table_branch(&mut self, b: NodeId) -> Result<(String, Vec<NodeId>), SqlError> {
1506 self.table_branch_lead(b, false)
1507 }
1508
1509 /// [`table_branch`]; with `more`, the branch may go on after
1510 /// `/table/*[…]` (a step, a cell): the prefilter concerns its
1511 /// first two steps only, and the steps after them are held to
1512 /// the whole-query gates.
1513 fn table_branch_lead(
1514 &mut self,
1515 b: NodeId,
1516 more: bool,
1517 ) -> Result<(String, Vec<NodeId>), SqlError> {
1518 let steps = self.kids(b, "step");
1519 if steps.len() < 2 || (steps.len() > 2 && !more) {
1520 return Err(not_pushed(
1521 Refusal::Walk,
1522 "navigation beyond /table/* (SQL sees tables and rows)".into(),
1523 ));
1524 }
1525 let (t, rows) = (steps[0], steps[1]);
1526 if self.prop_s(t, "axis") != "/"
1527 || self.prop_s(t, "matcher-kind") != "name"
1528 || self.prop_s(rows, "axis") != "/"
1529 || self.prop_s(rows, "matcher-kind") != "any"
1530 {
1531 return Err(not_pushed(
1532 Refusal::Walk,
1533 "navigation beyond /table/* (SQL sees tables and rows)".into(),
1534 ));
1535 }
1536 if self.kid(t, "predicate").is_some() {
1537 return Err(not_pushed(
1538 Refusal::Walk,
1539 "a predicate on the table step".into(),
1540 ));
1541 }
1542 Ok((self.prop_s(t, "matcher"), self.kids(rows, "predicate")))
1543 }
1544
1545 /// The names a `/table/*` branch marks its rows under: the marks
1546 /// standing after the row step. A mark anywhere else names a
1547 /// node SQL has no row for (the table) and is not translated.
1548 fn row_marks(&self, b: NodeId) -> Result<Vec<String>, SqlError> {
1549 let kids = self.arbor.children(b);
1550 let rows = self.kids(b, "step").get(1).copied();
1551 let after = rows
1552 .and_then(|r| kids.iter().position(|k| *k == r))
1553 .unwrap_or(kids.len());
1554 let mut names = Vec::new();
1555 for (i, k) in kids.iter().enumerate() {
1556 if self.kind(*k) != "mark" {
1557 continue;
1558 }
1559 if i < after {
1560 return Err(not_pushed(
1561 Refusal::Walk,
1562 "a mark before the rows (SQL sees tables and rows)".into(),
1563 ));
1564 }
1565 // (a mark with no name is read by position alone, and
1566 // a read by position is not translated)
1567 if let Some(Value::Str(n)) = self.prop(*k, "name") {
1568 names.push(n);
1569 }
1570 }
1571 Ok(names)
1572 }
1573
1574 /// A path operand read through the capsa's node side (`$$.al`,
1575 /// `$$.2`, `((@))`): the mark's name where the anchor is one
1576 /// mark by name, and whether it is any mark anchor at all.
1577 fn mark_anchor(&self, o: NodeId) -> (Option<String>, bool) {
1578 let named = match self.prop(o, "mark") {
1579 Some(Value::Str(n)) => Some(n),
1580 _ => None,
1581 };
1582 let any = named.is_some()
1583 || [
1584 "mark-index",
1585 "mark-top",
1586 "mark-back",
1587 "marks-all",
1588 "marks-name",
1589 "edge-end",
1590 "node-id",
1591 ]
1592 .iter()
1593 .any(|k| self.prop(o, k).is_some());
1594 (named, any)
1595 }
1596
1597 /// One row predicate as a WHERE condition (qualify columns with
1598 /// `qualifier` when joining).
1599 fn predicate_cond(&mut self, p: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
1600 if self.prop_s(p, "kind") != "expr" {
1601 return Err(not_pushed(
1602 Refusal::Take,
1603 "a positional predicate on rows (SQL rows are unordered; ORDER BY + LIMIT)".into(),
1604 ));
1605 }
1606 let parts: Vec<String> = self
1607 .arbor
1608 .children(p)
1609 .into_iter()
1610 .map(|c| self.pred_expr(c, qual))
1611 .collect::<Result<_, _>>()?;
1612 Ok(parts.join(" AND "))
1613 }
1614
1615 fn pred_expr(&mut self, e: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
1616 match self.kind(e).as_str() {
1617 "and" | "or" => {
1618 let op = self.kind(e).to_uppercase();
1619 let kids: Vec<String> = self
1620 .arbor
1621 .children(e)
1622 .into_iter()
1623 .map(|c| self.pred_expr(c, qual))
1624 .collect::<Result<_, _>>()?;
1625 Ok(format!("({})", kids.join(&format!(" {op} "))))
1626 }
1627 "not" => {
1628 // SQL's `NOT` propagates UNKNOWN: `NOT (x = 5)` is
1629 // UNKNOWN for a NULL `x` and drops the row, but Quarb's
1630 // negation keeps it (the inner `value_eq` is false, so
1631 // its negation is true). A pushed plan says the
1632 // negation the way that keeps the row on every
1633 // engine: the condition as a CASE, which takes
1634 // UNKNOWN to its ELSE. Inside a join's bracket the
1635 // engine's own logic is three-valued for the key
1636 // comparisons and two-valued for the rest, which no
1637 // one SQL form follows: there the negation stays
1638 // with the engine.
1639 if self.strict && self.in_on {
1640 return Err(mismatch(
1641 Refusal::Negation,
1642 "a negation inside a join condition (the engine leaves a key \
1643 comparison with a null unknown there, and reads the rest as \
1644 true or false)"
1645 .into(),
1646 ));
1647 }
1648 let inner: Vec<String> = self
1649 .arbor
1650 .children(e)
1651 .into_iter()
1652 .map(|c| self.pred_expr(c, qual))
1653 .collect::<Result<_, _>>()?;
1654 if self.strict {
1655 return Ok(format!(
1656 "(CASE WHEN {} THEN 0 ELSE 1 END = 1)",
1657 inner.join(" AND ")
1658 ));
1659 }
1660 Ok(format!("NOT ({})", inner.join(" AND ")))
1661 }
1662 "parens" => {
1663 let inner: Vec<String> = self
1664 .arbor
1665 .children(e)
1666 .into_iter()
1667 .map(|c| self.pred_expr(c, qual))
1668 .collect::<Result<_, _>>()?;
1669 Ok(format!("({})", inner.join(" AND ")))
1670 }
1671 "compare" => {
1672 let op = self.prop_s(e, "op");
1673 let kids = self.arbor.children(e);
1674 // A comparison against a bare `null` literal. Quarb's
1675 // `value_eq` treats NULL as an ordinary value
1676 // (`value_eq(NULL, NULL)` is true, `value_eq(NULL, x)`
1677 // false), so `= null` keeps exactly the NULL rows and
1678 // `!= null` the non-NULL rows. SQL's `= NULL` / `<>
1679 // NULL` are always UNKNOWN and drop every row; the
1680 // `IS [NOT] NULL` forms are provably identical (and
1681 // portable across every target dialect).
1682 if matches!(op.as_str(), "=" | "!=")
1683 && (self.is_null_literal(kids[0]) || self.is_null_literal(kids[1]))
1684 {
1685 let other = if self.is_null_literal(kids[0]) {
1686 kids[1]
1687 } else {
1688 kids[0]
1689 };
1690 // A comparison with the literal null is the
1691 // presence test wherever it stands, inside a join
1692 // condition too (ruling 2026-11-18: no key
1693 // comparison, true or false): IS [NOT] NULL. In
1694 // 0.69 the engine left it unknown there and the
1695 // plan was refused.
1696 let col = self.operand(other, qual)?;
1697 return Ok(if op == "=" {
1698 format!("{col} IS NULL")
1699 } else {
1700 format!("{col} IS NOT NULL")
1701 });
1702 }
1703 // JSON-column-path pushdown: `[/col/a/b:: = 'lit']`
1704 // navigates into a JSON column and compares a fixed
1705 // path to a string literal. Only this exact shape —
1706 // fixed object path, string equality, and a literal
1707 // that does NOT look numeric — is provably identical
1708 // to the client-side graft (each engine's scalar
1709 // extractor unquotes to text, and an absent path or
1710 // non-string value excludes the row on both sides,
1711 // matching Quarb's `value_eq` on non-numeric text).
1712 // Numeric casts, `!=`, wildcards, and deeper
1713 // predicates fall through to the ordinary operand
1714 // logic below, which refuses the navigation; the
1715 // partial-pushdown prefilter ladder picks those up
1716 // with superset semantics. Enabled only when a
1717 // dialect is set.
1718 if op == "="
1719 && let Some(dialect) = self.dialect
1720 {
1721 for (pi, li) in [(0usize, 1usize), (1, 0)] {
1722 if self.is_text_literal(kids[li])
1723 && let Some((col, path)) = self.json_path(kids[pi])
1724 {
1725 self.note_json_column(kids[pi], &col);
1726 // Quarb's value_eq compares numeric-looking
1727 // strings numerically — '150' matches the
1728 // JSON number 150, and the string "150.0".
1729 // No engine's text extractor coerces that
1730 // way, so the pushed compare would drop
1731 // rows the graft keeps. Refuse; the
1732 // prefilter ladder handles it as a
1733 // superset.
1734 let raw = self
1735 .prop(kids[li], "value")
1736 .map(|v| v.to_string())
1737 .unwrap_or_default();
1738 if raw.trim().parse::<f64>().is_ok() {
1739 return Err(mismatch(
1740 Refusal::Type,
1741 "a numeric-looking text literal against a \
1742 JSON path compares numerically in Quarb \
1743 (value coercion); no SQL extractor \
1744 matches that"
1745 .into(),
1746 ));
1747 }
1748 // An extractor answers a container as
1749 // its JSON text (SQLite `[1,2]`,
1750 // PostgreSQL `[1, 2]`), so a literal that
1751 // is such a text equalled the array or
1752 // the object itself, which has no value
1753 // in the graft: the push kept a row the
1754 // scan drops. No scalar's text opens
1755 // with a bracket or a brace that a
1756 // container's does not, so such a
1757 // literal rides the prefilter.
1758 if raw.starts_with('[') || raw.starts_with('{') {
1759 return Err(mismatch(
1760 Refusal::Type,
1761 "a text literal that opens like a JSON container \
1762 could equal an array's or an object's own text \
1763 in the extractor, which has no value in Quarb"
1764 .into(),
1765 ));
1766 }
1767 let lit = self.operand(kids[li], qual)?;
1768 let extract = json_extract(dialect, qual, &col, &path);
1769 return Ok(json_valid_guard(
1770 dialect,
1771 qual,
1772 &col,
1773 format!("{extract} = {lit}"),
1774 ));
1775 }
1776 }
1777 // The property form, `[/col/a::b = 'lit']`: the
1778 // same question on a scalar, and on an array of
1779 // scalars the list, which equals the literal when
1780 // any item does (an array that holds a container
1781 // is no property). SQLite says both in one
1782 // condition, exactly: the scalar branch by the
1783 // value's type and text, the array branch by
1784 // `json_each`. The other engines' array branches
1785 // are not verified live, so there the shape rides
1786 // the prefilter (PostgreSQL) or the scan.
1787 for (pi, li) in [(0usize, 1usize), (1, 0)] {
1788 if self.is_text_literal(kids[li])
1789 && let Some((col, path)) = self.json_property_path(kids[pi])
1790 {
1791 self.note_json_column(kids[pi], &col);
1792 let raw = self
1793 .prop(kids[li], "value")
1794 .map(|v| v.to_string())
1795 .unwrap_or_default();
1796 if raw.trim().parse::<f64>().is_ok() {
1797 return Err(mismatch(
1798 Refusal::Type,
1799 "a numeric-looking text literal against a \
1800 JSON path compares numerically in Quarb \
1801 (value coercion); no SQL extractor \
1802 matches that"
1803 .into(),
1804 ));
1805 }
1806 // `json_each` names its own columns; an
1807 // unqualified JSON column of one of those
1808 // names would read as them inside it.
1809 let shadowed = qual.is_none()
1810 && JSON_EACH_COLUMNS.contains(&col.to_ascii_lowercase().as_str());
1811 if dialect != Dialect::Sqlite || shadowed {
1812 return Err(mismatch(
1813 Refusal::Type,
1814 "a property of a JSON value may be a list (an \
1815 array of scalars equals the literal when any \
1816 item does); only SQLite's condition carries \
1817 that branch whole; this shape rides the \
1818 partial prefilter"
1819 .into(),
1820 ));
1821 }
1822 let lit = self.operand(kids[li], qual)?;
1823 let qcol = match qual {
1824 Some(q) => format!("{q}.{col}"),
1825 None => col.clone(),
1826 };
1827 let at = format!("'$.{}'", path.join("."));
1828 let ty = format!("json_type({qcol}, {at})");
1829 let ex = json_extract(dialect, qual, &col, &path);
1830 return Ok(json_valid_guard(
1831 dialect,
1832 qual,
1833 &col,
1834 format!(
1835 "(({ty} = 'text' AND {ex} = {lit}) OR ({ty} = 'array' \
1836 AND EXISTS (SELECT 1 FROM json_each({qcol}, {at}) \
1837 WHERE json_each.type = 'text' AND json_each.value = {lit}) \
1838 AND NOT EXISTS (SELECT 1 FROM json_each({qcol}, {at}) \
1839 WHERE json_each.type IN ('array', 'object'))))"
1840 ),
1841 ));
1842 }
1843 }
1844 }
1845 // Any other JSON-path comparison: name the real
1846 // reason, not the generic flat-rows refusal — only
1847 // fixed-path string equality is provably identical
1848 // (Quarb coerces numeric-looking values; no
1849 // engine's extractor matches that). The partial
1850 // prefilter ladder covers these shapes.
1851 if self.dialect.is_some() {
1852 for side in [kids[0], kids[1]] {
1853 if self.json_path(side).is_some()
1854 || self.json_path_loose(side).is_some()
1855 || self.json_property_path(side).is_some()
1856 {
1857 return Err(mismatch(
1858 Refusal::Type,
1859 "a JSON-path comparison pushes whole only as \
1860 fixed-path string equality (Quarb coerces \
1861 numeric-looking values; no extractor matches \
1862 that); this shape rides the partial prefilter"
1863 .into(),
1864 ));
1865 }
1866 }
1867 }
1868 // Quarb compares by value; SQL by the column's type.
1869 // A column against a numeric literal is the scan's
1870 // comparison only on a numeric-typed column, and
1871 // against a text literal only on a column that is
1872 // not (MySQL reads `n = 'abc'` as `n = 0`): the
1873 // catalog decides, so both are recorded for the
1874 // caller. A numeric-looking TEXT literal meets
1875 // numbers as a number in Quarb and compares as text
1876 // in SQL, on every engine, so it does not push. A
1877 // regex is no value: its refusal below is the
1878 // pattern's, whatever its text reads as.
1879 if self.strict && !matches!(op.as_str(), "==" | "!==") {
1880 for (ci, li) in [(0usize, 1usize), (1, 0)] {
1881 let Some(column) = self.column_operand(kids[ci]) else {
1882 continue;
1883 };
1884 if self.kind(kids[li]) != "literal" {
1885 continue;
1886 }
1887 let numeric = self
1888 .prop(kids[li], "value")
1889 .is_some_and(|v| Value::Str(v.to_string()).numeric_reading().is_some());
1890 let list = match (self.prop_s(kids[li], "type").as_str(), numeric) {
1891 ("null", _) => continue,
1892 ("text", true) => {
1893 return Err(mismatch(
1894 Refusal::Type,
1895 "a numeric-looking text literal compares \
1896 numerically in Quarb (value coercion); SQL \
1897 compares it as text"
1898 .into(),
1899 ));
1900 }
1901 ("text", false) => &mut self.column_types.text,
1902 (_, true) => &mut self.column_types.numeric,
1903 (_, false) => continue,
1904 };
1905 if !list.contains(&column) {
1906 list.push(column);
1907 }
1908 }
1909 }
1910 let l = self.operand(kids[0], qual)?;
1911 // Ruling #33: a pattern literal on `=` pushes as
1912 // LIKE — a `%` per star, each literal segment
1913 // escaped, in order. Anchoring matches exactly:
1914 // LIKE anchors both ends, a flanking star lifts
1915 // one. The case-folding caveat is `*=`'s; `!=`
1916 // with a pattern rides the scan (NOT LIKE drops
1917 // the NULL rows Quarb keeps).
1918 if self.kind(kids[1]) == "pattern" {
1919 if op.as_str() != "=" {
1920 return Err(not_pushed(
1921 Refusal::Pattern,
1922 format!("a pattern literal on '{op}' (only '=' pushes)"),
1923 ));
1924 }
1925 // PostgreSQL's LIKE is case-sensitive under its
1926 // deterministic collations — provably what the
1927 // pattern test does — so the strict push is
1928 // sound there (and a prefix pattern is
1929 // index-sargable server-side). Everywhere else
1930 // case folding is ambient state (SQLite pragma,
1931 // MySQL/MSSQL collation), so strict refuses.
1932 if self.strict && self.dialect != Some(Dialect::Postgres) {
1933 return Err(mismatch(
1934 Refusal::Pattern,
1935 "LIKE case folding differs per engine \
1936 (provably case-sensitive only on PostgreSQL)"
1937 .into(),
1938 ));
1939 }
1940 if !self.strict {
1941 self.notes.push(
1942 "pattern → LIKE: Quarb's pattern test is \
1943 case-sensitive; LIKE folds case on \
1944 SQLite/MySQL but not PostgreSQL"
1945 .to_string(),
1946 );
1947 }
1948 let mut like = String::new();
1949 for kid in self.arbor.children(kids[1]) {
1950 match self.kind(kid).as_str() {
1951 "star" => like.push('%'),
1952 _ => {
1953 let raw = self
1954 .prop(kid, "value")
1955 .map(|v| v.to_string())
1956 .unwrap_or_default();
1957 like.push_str(
1958 &raw.replace('\\', "\\\\")
1959 .replace('%', "\\%")
1960 .replace('_', "\\_")
1961 .replace('\'', "''"),
1962 );
1963 }
1964 }
1965 }
1966 return Ok(format!("{l} LIKE '{like}' ESCAPE '\\'"));
1967 }
1968 let r = self.operand(kids[1], qual)?;
1969 // Which sides can be NULL: every side that is no
1970 // literal. And whether this is a key comparison of a
1971 // join condition, which the engine leaves unknown for
1972 // a null on either side, as SQL does: there the plain
1973 // operators are the engine's own.
1974 let nullable: Vec<&str> = [(kids[0], l.as_str()), (kids[1], r.as_str())]
1975 .into_iter()
1976 .filter(|(k, _)| self.kind(*k) != "literal")
1977 .map(|(_, sql)| sql)
1978 .collect();
1979 let keyed = self.in_on
1980 && (self.subtree_has_driver(kids[0]) || self.subtree_has_driver(kids[1]));
1981 Ok(match op.as_str() {
1982 // Two NULLs are equal in Quarb (`value_eq`), and
1983 // SQL's `=` is UNKNOWN for them: an equality of
1984 // two columns says the second case too. (It was
1985 // pushed as the bare `a = b`, which dropped the
1986 // row where both are NULL.)
1987 "=" if self.strict && !keyed && nullable.len() == 2 => {
1988 format!("({l} = {r} OR ({l} IS NULL AND {r} IS NULL))")
1989 }
1990 "=" => format!("{l} = {r}"),
1991 // Quarb's `!=` holds for a NULL against a value
1992 // and fails for two NULLs; SQL's `<>` is UNKNOWN
1993 // for either. The plan adds the cases `<>` leaves
1994 // out, in SQL every engine reads.
1995 "!=" if self.strict && !keyed => match nullable.as_slice() {
1996 [] => format!("{l} <> {r}"),
1997 [one] => format!("({l} <> {r} OR {one} IS NULL)"),
1998 _ => format!(
1999 "({l} <> {r} OR ({l} IS NULL AND {r} IS NOT NULL) OR ({l} IS NOT \
2000 NULL AND {r} IS NULL))"
2001 ),
2002 },
2003 "!=" if self.strict => format!("{l} <> {r}"),
2004 "!=" => {
2005 // The display translation keeps `<>` and
2006 // notes the divergence.
2007 self.notes.push(
2008 "'!=' → '<>': Quarb keeps rows whose column is NULL; \
2009 SQL's '<>' drops them (use '!= null' for IS NOT NULL)"
2010 .to_string(),
2011 );
2012 format!("{l} <> {r}")
2013 }
2014 "<" | "<=" | ">" | ">=" => format!("{l} {op} {r}"),
2015 // SQLite's instr is a substring test by bytes,
2016 // case and all, as `*=` is; the column is a text
2017 // one (recorded above with the literal: a number
2018 // would be searched in SQLite's rendering of it,
2019 // not the engine's). A NULL has no substring on
2020 // either side.
2021 "*=" if self.strict
2022 && self.dialect == Some(Dialect::Sqlite)
2023 && self.is_text_literal(kids[1])
2024 && self.column_operand(kids[0]).is_some() =>
2025 {
2026 format!("instr({l}, {r}) > 0")
2027 }
2028 "*=" => {
2029 // The same PostgreSQL rung as the pattern
2030 // literal above: LIKE is provably
2031 // case-sensitive there, so `*=` pushes
2032 // strict too.
2033 if self.strict && self.dialect != Some(Dialect::Postgres) {
2034 return Err(mismatch(
2035 Refusal::Pattern,
2036 "LIKE case folding differs per engine \
2037 (a substring test is pushed on SQLite as instr and on \
2038 PostgreSQL as LIKE)"
2039 .into(),
2040 ));
2041 }
2042 // The pattern must be a text literal: a
2043 // column or computed operand holds a value,
2044 // not a pattern, and SQL LIKE cannot express
2045 // "contains that value" portably.
2046 if !self.is_text_literal(kids[1]) {
2047 return Err(not_pushed(
2048 Refusal::Pattern,
2049 "'*=' with a non-literal pattern".into(),
2050 ));
2051 }
2052 self.notes.push(
2053 "*= → LIKE: Quarb's substring test is case-sensitive; LIKE \
2054 folds case on SQLite/MySQL but not PostgreSQL"
2055 .to_string(),
2056 );
2057 // Escape LIKE's metacharacters, then quote.
2058 // The explicit ESCAPE makes '\' the escape
2059 // everywhere — SQLite, MSSQL, and Oracle
2060 // have no default escape character.
2061 let raw = self
2062 .prop(kids[1], "value")
2063 .map(|v| v.to_string())
2064 .unwrap_or_default();
2065 let pat = raw
2066 .replace('\\', "\\\\")
2067 .replace('%', "\\%")
2068 .replace('_', "\\_")
2069 .replace('\'', "''");
2070 format!("{l} LIKE '%{pat}%' ESCAPE '\\'")
2071 }
2072 "==" | "!==" | "=~" | "!~" => {
2073 return Err(mismatch(
2074 Refusal::Pattern,
2075 "regex matching means a different REGEXP engine per \
2076 backend; regexes run engine-side"
2077 .into(),
2078 ));
2079 }
2080 other => {
2081 return Err(not_pushed(
2082 Refusal::Operator,
2083 format!("the '{other}' comparison"),
2084 ));
2085 }
2086 })
2087 }
2088 // A bare truthy operand.
2089 _ => {
2090 if self.strict {
2091 return Err(mismatch(
2092 Refusal::Type,
2093 "truthiness diverges (0 and '' are falsy in Quarb)".into(),
2094 ));
2095 }
2096 self.notes.push(
2097 "truthiness: '[::c]' exports as IS NOT NULL, but Quarb also treats \
2098 0 and '' as falsy"
2099 .to_string(),
2100 );
2101 Ok(format!("{} IS NOT NULL", self.operand(e, qual)?))
2102 }
2103 }
2104 }
2105
2106 fn operand(&mut self, o: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
2107 match self.kind(o).as_str() {
2108 "literal" => {
2109 let v = self.prop(o, "value").unwrap_or(Value::Null);
2110 match self.prop_s(o, "type").as_str() {
2111 "text" => {
2112 let s = v.to_string();
2113 // No single escaping is portable across the
2114 // pushdown's target dialects: MySQL (default
2115 // sql_mode) and BigQuery read `\` as an escape
2116 // while SQLite/PostgreSQL/DuckDB take it
2117 // literally, and BigQuery rejects the `''`
2118 // quote-doubling the others require. A literal
2119 // carrying either character cannot be pushed as
2120 // provably identical SQL, so refuse it and let
2121 // the caller scan. (The display translation
2122 // keeps its best-effort `''`-doubling.)
2123 if self.strict && (s.contains('\'') || s.contains('\\')) {
2124 return Err(mismatch(
2125 Refusal::Name,
2126 "a text literal with a quote or backslash \
2127 has no escaping portable across SQL dialects"
2128 .into(),
2129 ));
2130 }
2131 Ok(format!("'{}'", s.replace('\'', "''")))
2132 }
2133 "null" => Ok("NULL".to_string()),
2134 _ => Ok(v.to_string()),
2135 }
2136 }
2137 "path" => {
2138 if self.kid(o, "step").is_some() {
2139 // A step here is either navigation (refused) or
2140 // a resolution chain (refused with the reason).
2141 let s = self.kids(o, "step")[0];
2142 if self.prop_s(s, "axis") == "-->" {
2143 return Err(not_pushed(
2144 Refusal::Resolution,
2145 "a '-->' resolution chain: the foreign-key targets live in \
2146 the schema, not the query — spell the join with '<=>' to \
2147 export it"
2148 .into(),
2149 ));
2150 }
2151 return Err(not_pushed(
2152 Refusal::Resolution,
2153 "navigation inside a predicate (SQL rows are flat)".into(),
2154 ));
2155 }
2156 let p = self
2157 .kid(o, "projection")
2158 .ok_or_else(|| not_pushed(Refusal::Operator, "an empty path operand".into()))?;
2159 let col = self.projection_col(p)?;
2160 let col = self.sql_ident(&col, "column name")?;
2161 // a read through a mark: the row the mark names
2162 let (named, any) = self.mark_anchor(o);
2163 if any {
2164 let Some(name) = named else {
2165 return Err(not_pushed(
2166 Refusal::State,
2167 "a mark read by position, or of several marks".into(),
2168 ));
2169 };
2170 if self.join_marks.contains(&name) {
2171 // `$$.al::col`: the witness, as `$$1::col`
2172 if self.in_on {
2173 return Err(not_pushed(
2174 Refusal::Join,
2175 "the joined expression's own mark inside its ON".into(),
2176 ));
2177 }
2178 let Some(join) = self.join_sql.clone() else {
2179 return Err(not_pushed(
2180 Refusal::Join,
2181 "a join mark outside a correlation join".into(),
2182 ));
2183 };
2184 return Ok(format!("{join}.{col}"));
2185 }
2186 if self.from_marks.contains(&name) {
2187 // `$$.t::col`: the driver's row, as `$$0::col`
2188 // in the ON
2189 return Ok(if self.join_sql.is_some() {
2190 format!("{}.{col}", self.from_sql.clone())
2191 } else {
2192 match qual {
2193 Some(q) => format!("{q}.{col}"),
2194 None => col,
2195 }
2196 });
2197 }
2198 return Err(not_pushed(
2199 Refusal::State,
2200 format!("a read of the mark '.{name}' (not a row of the query's tables)"),
2201 ));
2202 }
2203 Ok(match qual {
2204 Some(q) => format!("{q}.{col}"),
2205 None => col,
2206 })
2207 }
2208 "context" => {
2209 // `$$1::col` — the joined expression's witness, in
2210 // pipeline position: the joined table's column.
2211 // Anything else is outside the verified-safe set.
2212 let p = self
2213 .kid(o, "projection")
2214 .ok_or_else(|| not_pushed(Refusal::Join, "a bare '$$N' reference".into()))?;
2215 let col = self.projection_col(p)?;
2216 let col = self.sql_ident(&col, "column name")?;
2217 if matches!(self.prop(o, "index"), Some(Value::Int(0))) {
2218 // `$$0::col` — the driver, legal only inside the
2219 // joined expression's ON bracket (the parser
2220 // refuses it anywhere else).
2221 if !self.in_on {
2222 return Err(not_pushed(
2223 Refusal::Join,
2224 "a '$$0' reference outside the join's ON".into(),
2225 ));
2226 }
2227 if self.kid(o, "step").is_some() {
2228 return Err(not_pushed(
2229 Refusal::Join,
2230 "a '$$0' reference beyond a plain column ($$0::col)".into(),
2231 ));
2232 }
2233 return Ok(format!("{}.{col}", self.from_sql.clone()));
2234 }
2235 if self.in_on {
2236 return Err(not_pushed(
2237 Refusal::Join,
2238 "a '$$N' reference inside the ON (the driver is '$$0')".into(),
2239 ));
2240 }
2241 let Some(join) = self.join_sql.clone() else {
2242 return Err(not_pushed(
2243 Refusal::Join,
2244 "a '$$N' reference outside a correlation join".into(),
2245 ));
2246 };
2247 match self.prop(o, "index") {
2248 Some(Value::Int(1)) => Ok(format!("{join}.{col}")),
2249 None => Err(not_pushed(Refusal::Join, "a bare '$$N' reference".into())),
2250 Some(v) => Err(not_pushed(
2251 Refusal::Join,
2252 format!("$${v} beyond a two-branch correlation"),
2253 )),
2254 }
2255 }
2256 "invoking" => {
2257 // `$$__::col` — the invoking position of an enclosing
2258 // query body, never the driver (that is `$$0`, a
2259 // context of index 0, since draft 153). SQL has no
2260 // enclosing body to read.
2261 Err(not_pushed(
2262 Refusal::Join,
2263 "a '$$__' reference (the driver inside the ON is '$$0')".into(),
2264 ))
2265 }
2266 "arith" => {
2267 let op = self.prop_s(o, "op");
2268 let kids = self.arbor.children(o);
2269 let l = self.operand(kids[0], qual)?;
2270 let r = self.operand(kids[1], qual)?;
2271 Ok(match op.as_str() {
2272 "+" | "-" | "*" => format!("({l} {op} {r})"),
2273 "div" => format!("({l} / {r})"),
2274 "mod" => format!("({l} % {r})"),
2275 other => {
2276 return Err(not_pushed(
2277 Refusal::Operator,
2278 format!("'{other}' arithmetic"),
2279 ));
2280 }
2281 })
2282 }
2283 other => Err(not_pushed(
2284 Refusal::State,
2285 format!(
2286 "the '{other}' operand (registers, topics, and captures are Quarb-side state)"
2287 ),
2288 )),
2289 }
2290 }
2291
2292 fn projection_col(&mut self, p: NodeId) -> Result<String, SqlError> {
2293 match self.prop_s(p, "kind").as_str() {
2294 "property" => match self.prop(p, "key") {
2295 Some(k) => Ok(k.to_string()),
2296 None => Err(not_pushed(
2297 Refusal::Operator,
2298 "the bare '::' projection (name the column)".into(),
2299 )),
2300 },
2301 other => Err(not_pushed(
2302 Refusal::Operator,
2303 format!("the {other} metadata projection"),
2304 )),
2305 }
2306 }
2307
2308 /// The column a plain column operand names (`::col`, `$*1::col`):
2309 /// a path without a step, or a context reference, projecting a
2310 /// named property.
2311 /// A numeric reducer (`sum`, `mean`, `min`, `max`) pushed over a
2312 /// column is the scan's only on a numeric-typed column: the
2313 /// scan lifts unit text (`'18 parasang'` under a declared unit)
2314 /// to quantities and orders texts as texts, where SQL sums a
2315 /// text column by its leading digits and orders it by
2316 /// collation. Recorded for the caller's catalog as a
2317 /// comparison's assumption is.
2318 fn assume_numeric(&mut self, column: Option<String>) {
2319 if !self.strict {
2320 return;
2321 }
2322 if let Some(c) = column
2323 && !self.column_types.numeric.contains(&c)
2324 {
2325 self.column_types.numeric.push(c);
2326 }
2327 }
2328
2329 fn column_operand(&self, o: NodeId) -> Option<String> {
2330 match self.kind(o).as_str() {
2331 "path" if self.kid(o, "step").is_none() => {}
2332 "context" => {}
2333 _ => return None,
2334 }
2335 let p = self.kid(o, "projection")?;
2336 if self.prop_s(p, "kind") != "property" {
2337 return None;
2338 }
2339 self.prop(p, "key").map(|k| k.to_string())
2340 }
2341
2342 /// Whether `o` is a text string literal (`'London'`).
2343 fn is_text_literal(&self, o: NodeId) -> bool {
2344 self.kind(o) == "literal" && self.prop_s(o, "type") == "text"
2345 }
2346
2347 /// If `o` is the one JSON-column-path shape pushdown handles —
2348 /// `/col/seg/seg…::`, a plain-navigation path (every step `/`
2349 /// and a plain-identifier object key, no wildcards, no nested
2350 /// predicate), at least one segment past the column, ending in
2351 /// the bare `::` projection — return `(column, [json segments])`.
2352 /// Anything else is `None` (and falls back to the graft).
2353 fn json_path(&self, o: NodeId) -> Option<(String, Vec<String>)> {
2354 if self.kind(o) != "path" {
2355 return None;
2356 }
2357 let steps = self.kids(o, "step");
2358 if steps.len() < 2 {
2359 return None;
2360 }
2361 // The projection must be the bare `::` (default value of
2362 // the JSON leaf), not `::key` or a `:::`/`:` metadata form.
2363 let proj = self.kid(o, "projection")?;
2364 if self.prop_s(proj, "kind") != "property" || self.prop(proj, "key").is_some() {
2365 return None;
2366 }
2367 let mut names = Vec::with_capacity(steps.len());
2368 for s in &steps {
2369 if self.prop_s(*s, "axis") != "/"
2370 || self.prop_s(*s, "matcher-kind") != "name"
2371 || self.kid(*s, "predicate").is_some()
2372 {
2373 return None;
2374 }
2375 let name = self.prop_s(*s, "matcher");
2376 // Plain object keys only — no array indices, no
2377 // characters that would need per-dialect path escaping.
2378 let plain = !name.is_empty()
2379 && name
2380 .chars()
2381 .next()
2382 .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
2383 && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
2384 if !plain {
2385 return None;
2386 }
2387 names.push(name);
2388 }
2389 let col = names.remove(0);
2390 Some((col, names))
2391 }
2392
2393 /// The property form of a JSON-column path, `/col/seg…::key`:
2394 /// plain-navigation steps as in [`json_path`], at least the
2395 /// column's own, ending in the projection of a plain-identifier
2396 /// property. It asks for the same value as `/col/seg…/key::`
2397 /// where that is a scalar; on an array of scalars it is the
2398 /// list (see [`json_property_prefilter`]). Returns
2399 /// `(column, [json segments, the key last])`.
2400 ///
2401 /// [`json_path`]: Self::json_path
2402 /// [`json_property_prefilter`]: Self::json_property_prefilter
2403 fn json_property_path(&self, o: NodeId) -> Option<(String, Vec<String>)> {
2404 if self.kind(o) != "path" {
2405 return None;
2406 }
2407 let steps = self.kids(o, "step");
2408 if steps.is_empty() {
2409 return None;
2410 }
2411 let proj = self.kid(o, "projection")?;
2412 if self.prop_s(proj, "kind") != "property" {
2413 return None;
2414 }
2415 let key = self.prop(proj, "key")?.to_string();
2416 let plain = |name: &str| {
2417 !name.is_empty()
2418 && name
2419 .chars()
2420 .next()
2421 .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
2422 && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
2423 };
2424 if !plain(&key) {
2425 return None;
2426 }
2427 let mut names = Vec::with_capacity(steps.len() + 1);
2428 for s in &steps {
2429 if self.prop_s(*s, "axis") != "/"
2430 || self.prop_s(*s, "matcher-kind") != "name"
2431 || self.kid(*s, "predicate").is_some()
2432 {
2433 return None;
2434 }
2435 let name = self.prop_s(*s, "matcher");
2436 if !plain(&name) {
2437 return None;
2438 }
2439 names.push(name);
2440 }
2441 names.push(key);
2442 let col = names.remove(0);
2443 Some((col, names))
2444 }
2445
2446 /// A safe `AS` alias: bare when it is a plain identifier and
2447 /// not an SQL keyword; otherwise strict mode refuses (quoting
2448 /// dialects disagree) and export mode double-quotes, noting it.
2449 fn alias(&mut self, name: &str) -> Result<String, SqlError> {
2450 if is_plain_ident(name) {
2451 return Ok(name.to_string());
2452 }
2453 if self.strict {
2454 return Err(not_pushed(
2455 Refusal::Name,
2456 format!(
2457 "field name {name:?} needs SQL quoting \
2458 (dialects disagree); rename the field"
2459 ),
2460 ));
2461 }
2462 self.notes
2463 .push(format!("field name {name:?} double-quoted (ANSI)"));
2464 Ok(format!("\"{}\"", name.replace('"', "\"\"")))
2465 }
2466
2467 /// A table or column name rendered into SQL. Bare when it is a
2468 /// plain identifier; otherwise strict mode refuses — a name
2469 /// like `a OR b` would silently rewrite the emitted SQL's
2470 /// meaning, breaking the provably-identical guarantee (and a
2471 /// portable quoting does not exist) — and export mode
2472 /// double-quotes with a note.
2473 fn sql_ident(&mut self, name: &str, what: &str) -> Result<String, SqlError> {
2474 if is_plain_ident(name) {
2475 return Ok(name.to_string());
2476 }
2477 if self.strict {
2478 return Err(not_pushed(
2479 Refusal::Name,
2480 format!("{what} {name:?} is not a plain SQL identifier"),
2481 ));
2482 }
2483 self.notes
2484 .push(format!("{what} {name:?} double-quoted (ANSI)"));
2485 Ok(format!("\"{}\"", name.replace('"', "\"\"")))
2486 }
2487
2488 /// Split a joined-side predicate: `col = $*1::col2` equalities
2489 /// become the ON condition; everything else the WHERE.
2490 /// `ltable` and `rtable` are the tables' SQL renderings.
2491 fn split_join_pred(
2492 &mut self,
2493 p: NodeId,
2494 rtable: &str,
2495 on: &mut Vec<String>,
2496 wheres: &mut Vec<String>,
2497 ) -> Result<(), SqlError> {
2498 if self.prop_s(p, "kind") != "expr" {
2499 return Err(not_pushed(
2500 Refusal::Take,
2501 "a positional predicate on the joined side".into(),
2502 ));
2503 }
2504 // Flatten top-level ANDs; each conjunct routes to ON or
2505 // WHERE.
2506 fn conjuncts(ex: &Exporter, e: NodeId, out: &mut Vec<NodeId>) {
2507 if ex.kind(e) == "and" {
2508 for c in ex.arbor.children(e) {
2509 conjuncts(ex, c, out);
2510 }
2511 } else {
2512 out.push(e);
2513 }
2514 }
2515 let mut parts = Vec::new();
2516 for c in self.arbor.children(p) {
2517 conjuncts(self, c, &mut parts);
2518 }
2519 for e in parts {
2520 let uses_driver = self.subtree_has_driver(e);
2521 self.in_on = true;
2522 let cond = self.pred_expr(e, Some(rtable));
2523 self.in_on = false;
2524 let cond = cond?;
2525 if uses_driver && self.kind(e) == "compare" && self.prop_s(e, "op") == "=" {
2526 // Record which joined-table columns the ON binds —
2527 // the uniqueness obligation (see
2528 // Pushdown::join_left). Collected from the arbor's
2529 // bare-column operand nodes, never from the
2530 // rendered SQL text, so neither a literal nor an
2531 // unusual column name can corrupt the obligation.
2532 self.collect_join_cols(e)?;
2533 on.push(cond);
2534 } else {
2535 wheres.push(cond);
2536 }
2537 }
2538 Ok(())
2539 }
2540
2541 /// The joined-table columns the ON equality binds: every bare
2542 /// column operand (`::col`) in `e`'s subtree, appended to the
2543 /// join obligation with their raw (catalog) names.
2544 fn collect_join_cols(&mut self, e: NodeId) -> Result<(), SqlError> {
2545 // The `$$0` side is the driver — not part of the joined
2546 // table's obligation.
2547 if self.is_driver(e) {
2548 return Ok(());
2549 }
2550 if self.kind(e) == "path"
2551 && self.kid(e, "step").is_none()
2552 && let Some(p) = self.kid(e, "projection")
2553 {
2554 let col = self.projection_col(p)?;
2555 self.join_on_cols.push(col);
2556 }
2557 for c in self.arbor.children(e) {
2558 self.collect_join_cols(c)?;
2559 }
2560 Ok(())
2561 }
2562
2563 /// `$$0`: a context operand of index 0 (the driver), or a read
2564 /// of the driver's row through its mark (`$$.t::col`).
2565 fn is_driver(&self, n: NodeId) -> bool {
2566 (self.kind(n) == "context" && matches!(self.prop(n, "index"), Some(Value::Int(0))))
2567 || (self.kind(n) == "path"
2568 && matches!(self.mark_anchor(n).0, Some(name) if self.from_marks.contains(&name)))
2569 }
2570
2571 fn subtree_has_driver(&self, n: NodeId) -> bool {
2572 self.is_driver(n)
2573 || self
2574 .arbor
2575 .children(n)
2576 .into_iter()
2577 .any(|c| self.subtree_has_driver(c))
2578 }
2579
2580 /// Consume the pipeline into SELECT clauses. `projected` is the
2581 /// driving path's own terminal projection, where it has one:
2582 /// the column as SQL and its name.
2583 fn pipeline(
2584 &mut self,
2585 q: NodeId,
2586 sel: &mut Select,
2587 join: Option<(&str, &str)>,
2588 projected: Option<(String, String)>,
2589 ) -> Result<(), SqlError> {
2590 let Some(pipe) = self.kid(q, "pipeline") else {
2591 return Ok(());
2592 };
2593 let commands: Vec<NodeId> = self.arbor.children(pipe);
2594 let mut i = 0;
2595 // A pending per-row value (`| ::col`) feeding an aggregate,
2596 // and the column it names where it is one. The path's own
2597 // projection is that value from the start, so the glued
2598 // spelling plans as the piped one: `/t/*::col @| max` is
2599 // `/t/* | ::col @| max` (it was refused as a reducer "over
2600 // row nodes", with a hint to write the piped form).
2601 let (mut pending_col, mut pending_name) = match projected {
2602 Some((col, name)) => (Some(col), Some(name)),
2603 None => (None, None),
2604 };
2605 // After a grouped reduction: (key, agg_sql, alias).
2606 let mut grouped: Option<(String, String, String)> = None;
2607 // A pushed key awaiting its fold: (the regula's name, key_sql).
2608 let mut pushed_key: Option<(String, String)> = None;
2609 // …and the column it is, where it is one plain column.
2610 let mut pushed_key_column: Option<String> = None;
2611 // The regula a fold went by: the name its key has in the
2612 // record `%.` answers.
2613 let mut grouped_reg: Option<String> = None;
2614
2615 while i < commands.len() {
2616 let s = commands[i];
2617 match self.kind(s).as_str() {
2618 "expr" => {
2619 let kids = self.arbor.children(s);
2620 pending_col = Some(self.operand(kids[0], join.map(|(l, _)| l))?);
2621 pending_name = self.column_operand(kids[0]);
2622 }
2623 "cmd" => {
2624 let name = self.prop_s(s, "name");
2625 match name.as_str() {
2626 "rec" | "record" => {
2627 sel.select = self.record_fields(s, join)?;
2628 self.order.record = true;
2629 }
2630 // `| %` on a row node is the record of its
2631 // properties, which are the row's columns in
2632 // the table's order: SELECT *, a record even
2633 // of one field. It is the plan a bare
2634 // selection of row nodes had before the
2635 // ruling of 2026-11-18 gave that one its
2636 // locators. Last in the pipeline and over
2637 // the rows themselves: after a projection
2638 // the thread holds a value, and a joined
2639 // row's record is the driver's alone.
2640 "%" if self.strict
2641 && join.is_none()
2642 && sel.select.is_empty()
2643 && pending_col.is_none()
2644 && grouped.is_none()
2645 && pushed_key.is_none()
2646 && !self.aggregate
2647 && self.arbor.children(s).is_empty()
2648 && i + 1 == commands.len() =>
2649 {
2650 sel.select = vec!["*".to_string()];
2651 self.order.record = true;
2652 self.order.properties = true;
2653 }
2654 // A reducing aggregate on the plain pipe:
2655 // the grouped reduction.
2656 "count" | "sum" | "mean" | "min" | "max" => {
2657 let (key, _, _) = grouped.as_ref().ok_or_else(|| {
2658 not_pushed(
2659 Refusal::Reducer,
2660 format!("'| {name}' outside a group (use '@| {name}')"),
2661 )
2662 })?;
2663 // Quarb's count counts every member,
2664 // nulls included: COUNT(*); the
2665 // NULL-skipping COUNT(col) is
2666 // `count(--values)`.
2667 let values =
2668 self.reducer_counts_values(s, &name, pending_col.is_some())?;
2669 let col = if name == "count" {
2670 pending_col.take().filter(|_| values)
2671 } else {
2672 self.assume_numeric(pending_name.take());
2673 pending_col.take()
2674 };
2675 let agg = sql_agg(&name, col)?;
2676 grouped = Some((key.clone(), agg.clone(), agg));
2677 }
2678 other => {
2679 // sort/unique/top and kin are spellable
2680 // in SQL but with the backend's own
2681 // collation and duplicate semantics —
2682 // name the divergence, not a missing
2683 // feature.
2684 if matches!(other, "sort" | "sort_by" | "unique" | "top" | "bottom") {
2685 return Err(mismatch(
2686 if other == "unique" {
2687 Refusal::Unique
2688 } else {
2689 Refusal::Sort
2690 },
2691 format!(
2692 "'{other}' means the backend's collation and \
2693 duplicate semantics; one engine-side ordering \
2694 keeps it identical everywhere"
2695 ),
2696 ));
2697 }
2698 return Err(not_pushed(
2699 Refusal::Operator,
2700 format!("the '{other}' pipeline command"),
2701 ));
2702 }
2703 }
2704 }
2705 "push" => {
2706 // An alias for the grouped aggregate.
2707 if let Some((k, agg, _)) = grouped.take() {
2708 let alias = self.prop_s(s, "name");
2709 grouped = Some((k, agg, alias));
2710 } else {
2711 return Err(not_pushed(
2712 Refusal::State,
2713 "a register push (Quarb-side state)".into(),
2714 ));
2715 }
2716 }
2717 // `| .k(::k)` before a fold by `.k`: the GROUP BY key
2718 // (a projection body is a subcontext of one branch).
2719 "expr-push" if grouped.is_none() && pushed_key.is_none() => {
2720 let kids = self.arbor.children(s);
2721 let key = self.operand(kids[0], join.map(|(l, _)| l))?;
2722 pushed_key = Some((self.prop_s(s, "name"), key));
2723 pushed_key_column = self.column_operand(kids[0]);
2724 }
2725 "subcontext" if grouped.is_none() && pushed_key.is_none() => {
2726 let key = self.pushed_column(s, join.map(|(l, _)| l))?;
2727 // (unqualified, the SQL is the column's own name)
2728 pushed_key_column = join.is_none().then(|| key.clone());
2729 pushed_key = Some((self.prop_s(s, "name"), key));
2730 }
2731 "filter" => {
2732 if grouped.is_some() {
2733 // HAVING: `$_` / the alias refer to the
2734 // aggregate.
2735 let cond = self.having_cond(s)?;
2736 sel.having = Some(cond);
2737 } else {
2738 return Err(not_pushed(
2739 Refusal::State,
2740 "a mid-pipeline filter (put it in the row predicate)".into(),
2741 ));
2742 }
2743 }
2744 "recall" => {
2745 // `| %.` finalizes the grouped record.
2746 if self.prop_s(s, "ref") != "%." {
2747 return Err(not_pushed(
2748 Refusal::State,
2749 "a register recall (Quarb-side state)".into(),
2750 ));
2751 }
2752 let (key, agg, alias) = grouped.clone().ok_or_else(|| {
2753 not_pushed(Refusal::Fold, "'%.', with nothing grouped".into())
2754 })?;
2755 let alias = self.alias(&alias)?;
2756 // The record names the key by its regula (`.a`),
2757 // which need not be the column's name: the scan
2758 // answers %(a = …), and so must the plan.
2759 let key_field = match &grouped_reg {
2760 Some(reg) if *reg != key => format!("{key} AS {}", self.alias(reg)?),
2761 _ => key.clone(),
2762 };
2763 sel.select = vec![key_field, format!("{agg} AS {alias}")];
2764 self.order.record = true;
2765 // The HAVING condition compared the aggregate
2766 // through $_ — substitute the real expression.
2767 if let Some(h) = sel.having.take() {
2768 sel.having = Some(h.replace("__AGG__", &agg));
2769 }
2770 }
2771 "agg" if self.prop(s, "group").is_some() => {
2772 // The plan takes its first rows last: a command
2773 // over the rows a selection kept is the engine's.
2774 if self.strict && self.order.limit.is_some() {
2775 return Err(not_pushed(
2776 Refusal::Take,
2777 format!(
2778 "the '{}' command after a positional selection (a plan \
2779 takes its first rows last)",
2780 self.prop_s(s, "name")
2781 ),
2782 ));
2783 }
2784 // `@|{.k} agg`: the fold by the pushed key is the
2785 // grouped reduction, GROUP BY key.
2786 let name = self.prop_s(s, "name");
2787 if !matches!(name.as_str(), "count" | "sum" | "mean" | "min" | "max") {
2788 return Err(not_pushed(
2789 Refusal::Fold,
2790 format!("the '{name}' command per group (GROUP BY reduces)"),
2791 ));
2792 }
2793 let selector = self.prop_s(s, "group");
2794 if selector.contains(';') {
2795 return Err(not_pushed(
2796 Refusal::Fold,
2797 "a fold by several regulae (one GROUP BY key translates)".into(),
2798 ));
2799 }
2800 let (reg, key) = pushed_key.take().ok_or_else(|| {
2801 not_pushed(
2802 Refusal::Fold,
2803 "a fold by a regula no push of a key made".into(),
2804 )
2805 })?;
2806 grouped_reg = Some(reg.clone());
2807 if selector != "." && selector != format!(".{reg}") {
2808 return Err(not_pushed(
2809 Refusal::Fold,
2810 format!("a fold by '{selector}' (the pushed key is '.{reg}')"),
2811 ));
2812 }
2813 if self.strict {
2814 // SQL gives its groups in no stated order; the
2815 // engine gives them as each first appears. A
2816 // fold by one numeric column of the table is
2817 // pushed with that order asked of the driver
2818 // (the least key of each group). Numeric: two
2819 // texts that read as one number are one key
2820 // to the engine and two to GROUP BY.
2821 let plain = join.is_none()
2822 && self.order.sort.is_none()
2823 && self.order.limit.is_none()
2824 && !self.order.reversed;
2825 match pushed_key_column.take() {
2826 Some(column) if plain => {
2827 self.assume_numeric(Some(column.clone()));
2828 self.order.groups = true;
2829 self.order.keyed_by = Some((Refusal::Fold, column));
2830 }
2831 _ => {
2832 return Err(mismatch(
2833 Refusal::Fold,
2834 "a fold over a join, or after a sort or a selection, or by \
2835 anything but one column"
2836 .into(),
2837 ));
2838 }
2839 }
2840 }
2841 sel.group_by = Some(key.clone());
2842 let values = self.reducer_counts_values(s, &name, pending_col.is_some())?;
2843 let col = if name == "count" {
2844 // `count(--values)` over a projected column is
2845 // COUNT(col); the bare count is every row
2846 pending_col.take().filter(|_| values)
2847 } else {
2848 self.assume_numeric(pending_name.take());
2849 pending_col.take()
2850 };
2851 let agg = sql_agg(&name, col)?;
2852 grouped = Some((key, agg.clone(), agg));
2853 }
2854 "agg" => {
2855 // The plan takes its first rows last: a command
2856 // over the rows a selection kept is the engine's.
2857 if self.strict && self.order.limit.is_some() {
2858 return Err(not_pushed(
2859 Refusal::Take,
2860 format!(
2861 "the '{}' command after a positional selection (a plan \
2862 takes its first rows last)",
2863 self.prop_s(s, "name")
2864 ),
2865 ));
2866 }
2867 let name = self.prop_s(s, "name");
2868 match name.as_str() {
2869 "count" | "sum" | "mean" | "min" | "max" => {
2870 // Quarb's count counts every row, nulls
2871 // included: COUNT(*) regardless of a
2872 // pending column. `count(--values)`
2873 // counts the values other than null:
2874 // COUNT(col) over a projected column.
2875 let values =
2876 self.reducer_counts_values(s, &name, pending_col.is_some())?;
2877 let col = if name == "count" {
2878 pending_col.take().filter(|_| values)
2879 } else {
2880 self.assume_numeric(pending_name.take());
2881 pending_col.take()
2882 };
2883 sel.select = vec![sql_agg(&name, col)?];
2884 self.aggregate = true;
2885 }
2886 "sort_by" if self.strict => {
2887 // A database orders text by its own
2888 // collation. A sort by one numeric column
2889 // of the table has one order everywhere:
2890 // it is pushed, the key recorded for the
2891 // catalog to confirm, a null key last and
2892 // the ties in the table's order, which the
2893 // driver's ORDER BY says after the plan's.
2894 let kids = self.arbor.children(s);
2895 let column = kids.first().and_then(|&k| self.column_operand(k));
2896 let plain = join.is_none()
2897 && self.order.sort.is_none()
2898 && self.order.limit.is_none()
2899 && !self.order.reversed
2900 && !self.order.groups
2901 && !self.aggregate
2902 && grouped.is_none();
2903 let column = match (column, plain) {
2904 (Some(column), true) => column,
2905 // one column, and no place for its
2906 // order in the plan
2907 (Some(_), false) => {
2908 return Err(not_pushed(
2909 Refusal::Sort,
2910 "a sort over a join, or after a selection, a fold or \
2911 another sort (a plan has one order)"
2912 .into(),
2913 ));
2914 }
2915 (None, _) => {
2916 return Err(mismatch(
2917 Refusal::Sort,
2918 "ORDER BY collations differ per engine".into(),
2919 ));
2920 }
2921 };
2922 let mut desc = false;
2923 for &k in &kids[1..] {
2924 let named =
2925 (self.kind(k) == "option").then(|| self.prop_s(k, "name"));
2926 match named.as_deref() {
2927 Some("--desc" | "-d") => desc = true,
2928 _ => {
2929 return Err(mismatch(
2930 Refusal::Sort,
2931 "ORDER BY collations differ per engine".into(),
2932 ));
2933 }
2934 }
2935 }
2936 let e = self.operand(kids[0], None)?;
2937 self.assume_numeric(Some(column.clone()));
2938 self.order.sort = Some((e, desc));
2939 self.order.keyed_by = Some((Refusal::Sort, column));
2940 }
2941 "sort_by" => {
2942 // A sort after a positional selection
2943 // (or a second sort) cannot render: the
2944 // fixed SELECT shape orders before
2945 // LIMIT, and has one ORDER BY.
2946 if sel.limit.is_some() {
2947 return Err(not_pushed(
2948 Refusal::Sort,
2949 "a sort after a positional selection (SQL orders \
2950 before LIMIT)"
2951 .into(),
2952 ));
2953 }
2954 if sel.order_by.is_some() {
2955 return Err(not_pushed(
2956 Refusal::Sort,
2957 "a second sort (SQL has a single ORDER BY)".into(),
2958 ));
2959 }
2960 let kids = self.arbor.children(s);
2961 // The options are the command's own:
2962 // `--desc` is the direction, a named
2963 // collation (`--locale=tag`, ruling
2964 // 2026-11-11) is the engine's order and no
2965 // backend's; a second key has no place in
2966 // the one ORDER BY this shape holds.
2967 let mut desc = false;
2968 for &k in &kids[1..] {
2969 if self.kind(k) != "option" {
2970 return Err(not_pushed(
2971 Refusal::Sort,
2972 "a sort by several keys".into(),
2973 ));
2974 }
2975 match self.prop_s(k, "name").as_str() {
2976 "--desc" | "-d" => desc = true,
2977 "--locale" => {
2978 return Err(mismatch(
2979 Refusal::Sort,
2980 "sort_by(--locale=…) names the engine's collation; \
2981 a backend's differs"
2982 .into(),
2983 ));
2984 }
2985 // a case order is that
2986 // collation's (ruling 2026-11-12)
2987 "--upper-first" | "-u" | "--lower-first" | "-l"
2988 | "--ignore-case" | "-i" => {
2989 return Err(mismatch(
2990 Refusal::Sort,
2991 "sort_by's case order is the engine's collation's; \
2992 a backend's differs"
2993 .into(),
2994 ));
2995 }
2996 other => {
2997 return Err(not_pushed(
2998 Refusal::Sort,
2999 format!("the '{other}' option of sort_by"),
3000 ));
3001 }
3002 }
3003 }
3004 let e = self.operand(kids[0], join.map(|(l, _)| l))?;
3005 sel.order_by = Some((e, desc));
3006 }
3007 // The context reversed: every term of the
3008 // plan's order turned, the keys too.
3009 "reverse" if self.strict => {
3010 if self.order.reversed
3011 || self.order.limit.is_some()
3012 || self.order.groups
3013 || self.aggregate
3014 || grouped.is_some()
3015 {
3016 return Err(not_pushed(
3017 Refusal::Sort,
3018 "reverse after a positional selection, a fold or another \
3019 reverse"
3020 .into(),
3021 ));
3022 }
3023 self.order.reversed = true;
3024 }
3025 "reverse" => match &mut sel.order_by {
3026 Some((_, desc)) => *desc = true,
3027 None => {
3028 return Err(not_pushed(
3029 Refusal::Sort,
3030 "reverse without an ORDER BY (rows are unordered)".into(),
3031 ));
3032 }
3033 },
3034 // `top(k; ::n)` and `bottom(k; ::n)` in a plan:
3035 // the rows whose key is not null, by the key
3036 // descending or ascending, the ties in the
3037 // table's order, and the first k of them. A
3038 // sort and a cut, so the sort's conditions:
3039 // one numeric column of the table, nothing
3040 // ordered or cut before.
3041 "top" | "bottom" if self.strict => {
3042 let kids = self.arbor.children(s);
3043 let count = kids.first().and_then(|&k| {
3044 (self.kind(k) == "literal")
3045 .then(|| self.prop(k, "value"))
3046 .flatten()
3047 });
3048 let column = kids.get(1).and_then(|&k| self.column_operand(k));
3049 let plain = kids.len() == 2
3050 && join.is_none()
3051 && self.order.sort.is_none()
3052 && self.order.limit.is_none()
3053 && !self.order.reversed
3054 && !self.order.groups
3055 && !self.aggregate
3056 && grouped.is_none();
3057 let (Some(Value::Int(k)), Some(column), true) = (count, column, plain)
3058 else {
3059 return Err(not_pushed(
3060 Refusal::Sort,
3061 "'top' and 'bottom' by anything but one column of the \
3062 table, under an option, over a join, or after a sort, a \
3063 selection or a fold (a plan has one order)"
3064 .into(),
3065 ));
3066 };
3067 if k < 1 {
3068 return Err(not_pushed(
3069 Refusal::Sort,
3070 "'top' and 'bottom' of no rows".into(),
3071 ));
3072 }
3073 let e = self.operand(kids[1], None)?;
3074 sel.wheres.push(format!("{e} IS NOT NULL"));
3075 self.assume_numeric(Some(column.clone()));
3076 self.order.sort = Some((e, name == "top"));
3077 self.order.limit = Some(k as u64);
3078 self.order.keyed_by = Some((Refusal::Sort, column));
3079 }
3080 "top" => {
3081 if sel.limit.is_some() {
3082 return Err(not_pushed(
3083 Refusal::Sort,
3084 "'top' after a positional selection (SQL orders \
3085 before LIMIT)"
3086 .into(),
3087 ));
3088 }
3089 if sel.order_by.is_some() {
3090 return Err(not_pushed(
3091 Refusal::Sort,
3092 "a second sort (SQL has a single ORDER BY)".into(),
3093 ));
3094 }
3095 let kids = self.arbor.children(s);
3096 // the options name the engine's collation
3097 // and its case order: no backend's (they
3098 // were dropped, and the SQL ordered as the
3099 // backend pleased)
3100 if let Some(&k) = kids
3101 .get(2..)
3102 .and_then(|rest| rest.iter().find(|&&k| self.kind(k) == "option"))
3103 {
3104 return Err(mismatch(
3105 Refusal::Sort,
3106 format!(
3107 "top({}) names the engine's collation; a backend's differs",
3108 self.prop_s(k, "name")
3109 ),
3110 ));
3111 }
3112 let n = self.prop_s(kids[0], "value");
3113 let e = self.operand(kids[1], join.map(|(l, _)| l))?;
3114 sel.order_by = Some((e, true));
3115 sel.limit = Some(n);
3116 }
3117 "unique" => {
3118 if self.strict {
3119 // A count of the distinct values asks
3120 // for no order: `| ::n @| unique @|
3121 // count`, the last two commands of the
3122 // pipeline. COUNT(DISTINCT n) leaves
3123 // the NULLs out, and a null is one
3124 // value to `unique`: the plan adds it.
3125 // The column is a numeric one: two
3126 // texts that read as one number
3127 // ('300', '300.0') are one value to
3128 // the engine and two to DISTINCT.
3129 let counted = self.arbor.children(s).is_empty()
3130 && i + 2 == commands.len()
3131 && commands.get(i + 1).is_some_and(|&c| {
3132 self.kind(c) == "agg"
3133 && self.prop_s(c, "name") == "count"
3134 && self.prop(c, "group").is_none()
3135 && self.arbor.children(c).is_empty()
3136 });
3137 match (counted, pending_col.take(), pending_name.take()) {
3138 (true, Some(col), Some(name)) => {
3139 self.assume_numeric(Some(name.clone()));
3140 self.order.keyed_by = Some((Refusal::Unique, name));
3141 sel.select = vec![format!(
3142 "COUNT(DISTINCT {col}) + COALESCE(MAX(CASE WHEN \
3143 {col} IS NULL THEN 1 ELSE 0 END), 0)"
3144 )];
3145 self.aggregate = true;
3146 // the count is taken with it
3147 i += 2;
3148 continue;
3149 }
3150 _ => {
3151 return Err(not_pushed(
3152 Refusal::Unique,
3153 "DISTINCT returns rows in no stated order (a count \
3154 of the distinct values of a numeric column is \
3155 pushed: '| ::col @| unique @| count')"
3156 .into(),
3157 ));
3158 }
3159 }
3160 }
3161 // Quarb dedups the limited rows; SQL
3162 // applies DISTINCT before LIMIT.
3163 if sel.limit.is_some() {
3164 return Err(not_pushed(
3165 Refusal::Unique,
3166 "'unique' after a positional selection (SQL applies \
3167 DISTINCT before LIMIT)"
3168 .into(),
3169 ));
3170 }
3171 if let Some(c) = pending_col.take() {
3172 sel.select = vec![c];
3173 }
3174 sel.distinct = true;
3175 }
3176 other => {
3177 return Err(not_pushed(
3178 Refusal::Reducer,
3179 format!("the '{other}' aggregate"),
3180 ));
3181 }
3182 }
3183 }
3184 // `@| [..n]` in a plan: the first rows of the order the
3185 // driver writes (the plan's own sort, then the keys),
3186 // so the rows the scan's context begins with.
3187 "select" if self.strict => {
3188 if self.order.limit.is_some()
3189 || self.order.groups
3190 || self.aggregate
3191 || grouped.is_some()
3192 || pushed_key.is_some()
3193 {
3194 return Err(not_pushed(
3195 Refusal::Take,
3196 "a positional selection after a reducer, a fold or another \
3197 selection"
3198 .into(),
3199 ));
3200 }
3201 let p = self.arbor.children(s)[0];
3202 match (self.prop_s(p, "kind").as_str(), self.prop(p, "to")) {
3203 ("range", Some(Value::Int(n)))
3204 if self.prop(p, "from").is_none() && n > 0 =>
3205 {
3206 self.order.limit = Some(n as u64);
3207 }
3208 _ => {
3209 return Err(not_pushed(
3210 Refusal::Take,
3211 "positional selection beyond '@| [..n]'".into(),
3212 ));
3213 }
3214 }
3215 }
3216 "select" => {
3217 // `@| [..n]` → LIMIT.
3218 if sel.limit.is_some() {
3219 return Err(not_pushed(
3220 Refusal::Take,
3221 "a second positional selection".into(),
3222 ));
3223 }
3224 let p = self.arbor.children(s)[0];
3225 match (self.prop_s(p, "kind").as_str(), self.prop(p, "to")) {
3226 ("range", Some(Value::Int(n)))
3227 if self.prop(p, "from").is_none() && n > 0 =>
3228 {
3229 sel.limit = Some(n.to_string());
3230 }
3231 _ => {
3232 return Err(not_pushed(
3233 Refusal::Take,
3234 "positional selection beyond '@| [..n]'".into(),
3235 ));
3236 }
3237 }
3238 }
3239 other => {
3240 return Err(not_pushed(
3241 Refusal::Operator,
3242 format!(
3243 "the '{other}' command (windows, subcontexts, and registers are \
3244 Quarb-side state)"
3245 ),
3246 ));
3247 }
3248 }
3249 i += 1;
3250 }
3251 // A pending column with no aggregate is a one-column select.
3252 if let Some(c) = pending_col
3253 && sel.select.is_empty()
3254 {
3255 sel.select = vec![c];
3256 }
3257 // A plan answers row nodes as their rows, where the scan
3258 // answers the nodes: a sorted, reversed or cut selection of
3259 // nodes was the scan's to answer, and stays so; with a
3260 // projection or a record after it, it is the plan's.
3261 if self.strict
3262 && sel.select.is_empty()
3263 && (self.order.sort.is_some() || self.order.reversed || self.order.limit.is_some())
3264 {
3265 let word = if self.order.limit.is_some() {
3266 Refusal::Take
3267 } else {
3268 Refusal::Sort
3269 };
3270 return Err(not_pushed(
3271 word,
3272 "a sorted, reversed or cut selection of row nodes (project a column or build \
3273 a record after it: '| ::col', '| %(…)')"
3274 .into(),
3275 ));
3276 }
3277 // A grouped reduction never recorded (`@|{.k} count` with no
3278 // `| .n | %.`) answers one value per group: the aggregate
3279 // alone, grouped by the key.
3280 if let Some((_, agg, _)) = grouped
3281 && sel.select.is_empty()
3282 {
3283 sel.select = vec![agg];
3284 }
3285 Ok(())
3286 }
3287
3288 /// The column a pushed projection body names — `.k(::k)` is a
3289 /// subcontext whose one branch is the bare projection; any
3290 /// other body is Quarb-side state.
3291 fn pushed_column(&mut self, s: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
3292 let body = || {
3293 let q = self.kid(s, "query")?;
3294 let b = self.kid(q, "branch")?;
3295 let p = self.kid(b, "projection")?;
3296 let bare = self.kids(q, "branch").len() == 1
3297 && self.kids(q, "pipeline").is_empty()
3298 && self.arbor.children(b).len() == 1
3299 && self.prop_s(p, "kind") == "property";
3300 bare.then_some(p)
3301 };
3302 let p = body()
3303 .ok_or_else(|| not_pushed(Refusal::State, "a pushed body (Quarb-side state)".into()))?;
3304 let col = self.projection_col(p)?;
3305 let col = self.sql_ident(&col, "column name")?;
3306 Ok(match qual {
3307 Some(q) => format!("{q}.{col}"),
3308 None => col,
3309 })
3310 }
3311
3312 /// A HAVING filter: `$_` and `$.name` refer to the aggregate.
3313 fn having_cond(&mut self, s: NodeId) -> Result<String, SqlError> {
3314 let kids = self.arbor.children(s);
3315 if kids.len() != 1 || self.kind(kids[0]) != "compare" {
3316 return Err(not_pushed(
3317 Refusal::Fold,
3318 "HAVING translates for a single comparison".into(),
3319 ));
3320 }
3321 let e = kids[0];
3322 let op = self.prop_s(e, "op");
3323 let cmp_kids = self.arbor.children(e);
3324 let l = match self.kind(cmp_kids[0]).as_str() {
3325 "topic" | "recall" => "__AGG__".to_string(),
3326 _ => {
3327 return Err(not_pushed(
3328 Refusal::Fold,
3329 "HAVING compares the aggregate ($_ or its register)".into(),
3330 ));
3331 }
3332 };
3333 let r = self.operand(cmp_kids[1], None)?;
3334 Ok(format!("{l} {op} {r}"))
3335 }
3336
3337 /// `rec(...)` fields as a select list.
3338 fn record_fields(
3339 &mut self,
3340 s: NodeId,
3341 join: Option<(&str, &str)>,
3342 ) -> Result<Vec<String>, SqlError> {
3343 let kids = self.arbor.children(s);
3344 let mut fields = Vec::new();
3345 let mut i = 0;
3346 while i < kids.len() {
3347 let k = kids[i];
3348 if self.kind(k) == "literal" {
3349 let name = self.prop_s(k, "value");
3350 let value = self.operand(kids[i + 1], join.map(|(l, _)| l))?;
3351 let name = self.alias(&name)?;
3352 fields.push(format!("{value} AS {name}"));
3353 i += 2;
3354 } else {
3355 let value = self.operand(k, join.map(|(l, _)| l))?;
3356 fields.push(value);
3357 i += 1;
3358 }
3359 }
3360 Ok(fields)
3361 }
3362}
3363
3364impl Exporter {
3365 /// What a reducer's own arguments ask of the plan. A pushed
3366 /// reducer is the bare command: `count` is COUNT(*), `sum` is
3367 /// SUM(col). `count(--values)` counts the values other than
3368 /// null, which over a projected column is what COUNT(col)
3369 /// counts.
3370 /// Any other option, and any operand, changes what is reduced
3371 /// (`--nulls`, `--of=`, `--by=`), and the reducer stays with the
3372 /// engine. The plan took no notice of them until 0.68:
3373 /// `count(--values)` and `count(--nulls)` were both answered as
3374 /// COUNT(*), where the scan counts five and one of six.
3375 fn reducer_counts_values(
3376 &self,
3377 s: NodeId,
3378 name: &str,
3379 projected: bool,
3380 ) -> Result<bool, SqlError> {
3381 let mut values = false;
3382 for k in self.arbor.children(s) {
3383 if self.kind(k) != "option" {
3384 return Err(not_pushed(
3385 Refusal::Reducer,
3386 format!("an operand of '{name}'"),
3387 ));
3388 }
3389 match (name, self.prop_s(k, "name").as_str()) {
3390 ("count", "--values" | "-v") => values = true,
3391 (_, option) => {
3392 return Err(not_pushed(
3393 Refusal::Reducer,
3394 format!("the '{option}' option of '{name}'"),
3395 ));
3396 }
3397 }
3398 }
3399 // a row node is no value: what the count answers there is
3400 // the engine's to say
3401 if values && !projected {
3402 return Err(not_pushed(
3403 Refusal::Reducer,
3404 "'count(--values)' over row nodes (project a column: '/table/*::col @| \
3405 count(--values)')"
3406 .into(),
3407 ));
3408 }
3409 Ok(values)
3410 }
3411}
3412
3413fn sql_agg(name: &str, col: Option<String>) -> Result<String, SqlError> {
3414 let f = match name {
3415 "count" => "COUNT",
3416 "sum" => "SUM",
3417 "mean" => "AVG",
3418 "min" => "MIN",
3419 "max" => "MAX",
3420 _ => unreachable!("checked by caller"),
3421 };
3422 match col {
3423 Some(c) => Ok(format!("{f}({c})")),
3424 // Only COUNT aggregates bare rows; SUM(*) and friends are
3425 // not SQL.
3426 None if f == "COUNT" => Ok("COUNT(*)".to_string()),
3427 None => Err(not_pushed(
3428 Refusal::Reducer,
3429 format!("'{name}' over row nodes (project a column: '/table/*::col @| {name}')"),
3430 )),
3431 }
3432}
3433
3434#[cfg(test)]
3435mod null_and_literal_tests {
3436 use super::{Dialect, export, partial_pushdown, pushdown};
3437
3438 // Grouped pipeline that never pushes, so `partial_pushdown` hinges
3439 // only on the leading predicate (mirrors the crate's partial gate).
3440 const GROUPED: &str = " | ::x | .g(::x) @|{.g} count | .n | %.";
3441
3442 #[test]
3443 fn pattern_literal_pushes_as_like() {
3444 // Ruling #33: segments in order, a `%` per star, LIKE's
3445 // metacharacters escaped. Strict push only where LIKE is
3446 // provably case-sensitive (PostgreSQL); everywhere else the
3447 // pattern rides the scan.
3448 let q = "/users/*[::name == 'app-'*]::id";
3449 let p = pushdown(q, Some(Dialect::Postgres)).unwrap();
3450 assert_eq!(
3451 p.sql,
3452 "SELECT id FROM users WHERE name LIKE 'app-%' ESCAPE '\\'"
3453 );
3454 assert!(pushdown(q, Some(Dialect::Sqlite)).is_none());
3455 assert!(pushdown(q, Some(Dialect::MySql)).is_none());
3456 // contains and multi-segment shapes
3457 let p = pushdown("/users/*[::name == *'web'*]::id", Some(Dialect::Postgres)).unwrap();
3458 assert!(p.sql.contains("LIKE '%web%'"), "{}", p.sql);
3459 let p = pushdown(
3460 "/users/*[::name == *'a'*'.gz']::id",
3461 Some(Dialect::Postgres),
3462 )
3463 .unwrap();
3464 assert!(p.sql.contains("LIKE '%a%.gz'"), "{}", p.sql);
3465 // LIKE metacharacters in a segment are escaped
3466 let p = pushdown("/users/*[::name == *'50%_x'*]::id", Some(Dialect::Postgres)).unwrap();
3467 assert!(p.sql.contains("LIKE '%50\\%\\_x%'"), "{}", p.sql);
3468 // `!=` with a pattern rides the scan
3469 assert!(pushdown("/users/*[::name !== *'web'*]::id", Some(Dialect::Postgres)).is_none());
3470 // the `*=` alias gains the same PostgreSQL rung
3471 let p = pushdown("/users/*[::name *= 'web']::id", Some(Dialect::Postgres)).unwrap();
3472 assert!(p.sql.contains("LIKE '%web%'"), "{}", p.sql);
3473 // and on SQLite it is instr, a substring test by bytes and by
3474 // case as `*=` is; MySQL's INSTR folds case, and scans
3475 assert_eq!(
3476 pushdown("/users/*[::name *= 'web']::id", Some(Dialect::Sqlite))
3477 .unwrap()
3478 .sql,
3479 "SELECT id FROM users WHERE instr(name, 'web') > 0"
3480 );
3481 assert!(pushdown("/users/*[::name *= 'web']::id", Some(Dialect::MySql)).is_none());
3482 assert!(pushdown("/users/*[::name *= 'web']::id", None).is_none());
3483 }
3484
3485 #[test]
3486 fn json_column_path_pushdown_per_dialect() {
3487 // `[/col/a/b:: = 'lit']` navigates into a JSON column; each
3488 // dialect extracts the fixed path to text and compares.
3489 // Verified live against all five engines to match the graft.
3490 let q = "/orders/*[/data/meta/tier:: = 'gold']::id";
3491 let sql = |d| pushdown(q, Some(d)).unwrap().sql;
3492 assert_eq!(
3493 sql(Dialect::Postgres),
3494 "SELECT id FROM orders WHERE ((data::jsonb #>> '{meta,tier}') = 'gold')"
3495 );
3496 assert_eq!(
3497 sql(Dialect::MySql),
3498 "SELECT id FROM orders WHERE (JSON_VALID(data) AND \
3499 JSON_UNQUOTE(JSON_EXTRACT(data, '$.meta.tier')) = 'gold')"
3500 );
3501 assert_eq!(
3502 sql(Dialect::Sqlite),
3503 "SELECT id FROM orders WHERE (json_valid(data) AND \
3504 json_extract(data, '$.meta.tier') = 'gold')"
3505 );
3506 assert_eq!(
3507 sql(Dialect::Mssql),
3508 "SELECT id FROM orders WHERE (ISJSON(data) = 1 AND \
3509 JSON_VALUE(data, '$.meta.tier') = 'gold')"
3510 );
3511 assert_eq!(
3512 sql(Dialect::Oracle),
3513 "SELECT id FROM orders WHERE (JSON_VALUE(data, '$.meta.tier') = 'gold')"
3514 );
3515 // With no dialect, the JSON navigation is not pushable — it
3516 // falls back to the client-side graft.
3517 assert!(pushdown(q, None).is_none());
3518 }
3519
3520 #[test]
3521 fn json_pushdown_only_string_equality() {
3522 // Numeric comparison, `!=`, and a wildcard step stay off the
3523 // pushdown path (they are not provably identical to the
3524 // graft), so they refuse and scan even with a dialect set.
3525 let d = Some(Dialect::Sqlite);
3526 assert!(pushdown("/o/*[/data/n:: > 2]::id", d).is_none());
3527 assert!(pushdown("/o/*[/data/tier:: != 'gold']::id", d).is_none());
3528 assert!(pushdown("/o/*[/data/items/*/sku:: = 'A1']::id", d).is_none());
3529 }
3530
3531 #[test]
3532 fn json_pushdown_refuses_numeric_looking_literal() {
3533 // value_eq coerces numeric-looking strings ('150' matches
3534 // the JSON number 150 and the string "150.0"); no engine's
3535 // extractor does, so the push would drop rows.
3536 let q = "/orders/*[/data/total:: = '150']::id";
3537 assert!(pushdown(q, Some(Dialect::Sqlite)).is_none());
3538 assert!(pushdown(q, Some(Dialect::Postgres)).is_none());
3539 }
3540
3541 #[test]
3542 fn a_regex_names_the_literals_it_cannot_match_without() {
3543 let lits = |p: &str| super::required_literals(p);
3544 assert_eq!(lits("^Ma.*s$"), ["Ma", "s"]);
3545 assert_eq!(lits("(us)+$"), ["us"]);
3546 assert_eq!(lits("a?b"), ["b"]);
3547 assert_eq!(lits("(?:foo|bar)baz"), ["baz"]);
3548 assert_eq!(lits("fo{2,}"), ["f", "o"]);
3549 assert_eq!(lits(r"\d+-\d+"), ["-"]);
3550 assert_eq!(lits(r"\bfoo\b"), ["foo"]);
3551 assert_eq!(lits(r"No\.1"), ["No.1"]);
3552 assert_eq!(lits("na\u{ef}ve"), ["na\u{ef}ve"]);
3553 assert_eq!(lits("(?x) a b"), ["ab"]);
3554 assert_eq!(lits("(a|b)c*d"), ["d"]);
3555 assert_eq!(lits("x{0}y"), ["y"]);
3556 assert_eq!(lits("ab(ab)"), ["ab"]);
3557 // nothing promised: a class, an alternation, an optional
3558 // part, a letter under (?i), a pattern that does not parse
3559 for p in ["(?i)ma", "Ven|Jup", "a*", "[ab]", "(ab)?", ".*", "", "["] {
3560 assert!(lits(p).is_empty(), "{p}");
3561 }
3562 }
3563
3564 #[test]
3565 fn a_regex_is_narrowed_by_its_literals() {
3566 let part = |q: &str, d: Dialect| {
3567 partial_pushdown(q, Some(d)).map(|p| (p.where_sql, p.column_types.text))
3568 };
3569 assert_eq!(
3570 part("/t/*[::a == (/^Ma.*s$/)]::b", Dialect::Sqlite),
3571 Some((
3572 "instr(a, 'Ma') > 0 AND instr(a, 's') > 0".to_string(),
3573 vec!["a".to_string()]
3574 ))
3575 );
3576 assert_eq!(
3577 part("/t/*[::a == (/50%_off/)]::b", Dialect::Postgres).map(|p| p.0),
3578 Some(r"a LIKE '%50\%\_off%' ESCAPE '\'".to_string())
3579 );
3580 // a conjunction keeps the side that translates; a
3581 // disjunction needs both
3582 assert_eq!(
3583 part("/t/*[::n > 2 && ::a == (/on/)]::b", Dialect::Sqlite).map(|p| p.0),
3584 Some("(n > 2 AND instr(a, 'on') > 0)".to_string())
3585 );
3586 assert_eq!(
3587 part(
3588 "/t/*[::a == (/(?i)x/) && ::a == (/on/)]::b",
3589 Dialect::Sqlite
3590 )
3591 .map(|p| p.0),
3592 Some("(instr(a, 'on') > 0)".to_string())
3593 );
3594 assert_eq!(
3595 part("/t/*[::a == (/Ven/) || ::a == (/Jup/)]::b", Dialect::Sqlite).map(|p| p.0),
3596 Some("(instr(a, 'Ven') > 0 OR instr(a, 'Jup') > 0)".to_string())
3597 );
3598 for q in [
3599 // one side promises nothing: the disjunction is not narrowed
3600 "/t/*[::a == (/Ven/) || ::a == (/(?i)jup/)]::b",
3601 // a negation is never narrowed, nor a non-match
3602 "/t/*[!(::a == (/Ven/))]::b",
3603 "/t/*[::a !== (/Ven/)]::b",
3604 // a literal a SQL string would not carry everywhere
3605 "/t/*[::a == (/it's/)]::b",
3606 // no literal at all
3607 "/t/*[::a == (/(?i)ven/)]::b",
3608 "/t/*[::a == (/Ven|Jup/)]::b",
3609 ] {
3610 assert_eq!(part(q, Dialect::Sqlite), None, "{q}");
3611 }
3612 // no function says "holds, by bytes and case" on MySQL
3613 assert_eq!(part("/t/*[::a == (/Ven/)]::b", Dialect::MySql), None);
3614 }
3615
3616 #[test]
3617 fn partial_json_prefilters_sqlite() {
3618 // Exact string equality rides the strict gate.
3619 let p = partial_pushdown(
3620 "/orders/*[/payload/customer/geo/city:: = 'Lyon']::id",
3621 Some(Dialect::Sqlite),
3622 )
3623 .unwrap();
3624 assert_eq!(p.table, "orders");
3625 assert_eq!(
3626 p.where_sql,
3627 "(json_valid(payload) AND \
3628 json_extract(payload, '$.customer.geo.city') = 'Lyon')"
3629 );
3630 // Numeric comparison: typed compare, text values escape.
3631 let p = partial_pushdown(
3632 "/orders/*[/payload/total:: > 150]::id",
3633 Some(Dialect::Sqlite),
3634 )
3635 .unwrap();
3636 assert_eq!(
3637 p.where_sql,
3638 "(json_valid(payload) AND (json_extract(payload, '$.total') > 150 \
3639 OR json_type(payload, '$.total') = 'text'))"
3640 );
3641 // Bare existence.
3642 let p = partial_pushdown("/orders/*[/payload/gift]::id", Some(Dialect::Sqlite)).unwrap();
3643 assert_eq!(
3644 p.where_sql,
3645 "(json_valid(payload) AND json_type(payload, '$.gift') IS NOT NULL)"
3646 );
3647 // != floors at existence.
3648 let p = partial_pushdown(
3649 "/orders/*[/payload/status:: != 'x']::id",
3650 Some(Dialect::Sqlite),
3651 )
3652 .unwrap();
3653 assert_eq!(
3654 p.where_sql,
3655 "(json_valid(payload) AND json_type(payload, '$.status') IS NOT NULL)"
3656 );
3657 // A flipped literal flips the operator.
3658 let p = partial_pushdown(
3659 "/orders/*[150 < /payload/total::]::id",
3660 Some(Dialect::Sqlite),
3661 )
3662 .unwrap();
3663 assert!(p.where_sql.contains("> 150"), "{}", p.where_sql);
3664 // Without a dialect, JSON predicates stay on the engine.
3665 assert!(partial_pushdown("/orders/*[/payload/gift]::id", None).is_none());
3666 }
3667
3668 #[test]
3669 fn partial_json_prefilters_postgres() {
3670 let p = partial_pushdown(
3671 "/orders/*[/payload/total:: > 150]::id",
3672 Some(Dialect::Postgres),
3673 )
3674 .unwrap();
3675 assert_eq!(
3676 p.where_sql,
3677 "(CASE WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'number' \
3678 THEN ((payload::jsonb #>> '{total}'))::float8 > 150 \
3679 WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'string' \
3680 THEN true ELSE false END)"
3681 );
3682 let p = partial_pushdown("/orders/*[/payload/gift]::id", Some(Dialect::Postgres)).unwrap();
3683 assert_eq!(
3684 p.where_sql,
3685 "(jsonb_typeof(payload::jsonb #> '{gift}') IS NOT NULL)"
3686 );
3687 }
3688
3689 #[test]
3690 fn json_property_path_pushdown() {
3691 // `[/col/a::b = 'lit']`, the property form: the scalar's
3692 // question and, on an array of scalars, the list's (any item
3693 // equals). SQLite's condition says both whole.
3694 let q = "/orders/*[/payload/customer/geo::city = 'Lyon']::id";
3695 assert_eq!(
3696 pushdown(q, Some(Dialect::Sqlite)).unwrap().sql,
3697 "SELECT id FROM orders WHERE (json_valid(payload) AND \
3698 ((json_type(payload, '$.customer.geo.city') = 'text' AND \
3699 json_extract(payload, '$.customer.geo.city') = 'Lyon') OR \
3700 (json_type(payload, '$.customer.geo.city') = 'array' AND \
3701 EXISTS (SELECT 1 FROM json_each(payload, '$.customer.geo.city') \
3702 WHERE json_each.type = 'text' AND json_each.value = 'Lyon') AND \
3703 NOT EXISTS (SELECT 1 FROM json_each(payload, '$.customer.geo.city') \
3704 WHERE json_each.type IN ('array', 'object')))))"
3705 );
3706 // a property of the column's own value
3707 assert!(
3708 pushdown(
3709 "/orders/*[/payload::city = 'Lyon']::id",
3710 Some(Dialect::Sqlite)
3711 )
3712 .unwrap()
3713 .sql
3714 .contains("json_extract(payload, '$.city') = 'Lyon'")
3715 );
3716 // the other engines' array branches are not verified: no
3717 // whole push there, and none with no dialect
3718 for d in [
3719 Dialect::Postgres,
3720 Dialect::MySql,
3721 Dialect::Mssql,
3722 Dialect::Oracle,
3723 ] {
3724 assert!(pushdown(q, Some(d)).is_none(), "{d:?}");
3725 }
3726 assert!(pushdown(q, None).is_none());
3727 // a numeric-looking literal compares by value: no whole push
3728 assert!(
3729 pushdown(
3730 "/orders/*[/payload::total = '150']::id",
3731 Some(Dialect::Sqlite)
3732 )
3733 .is_none()
3734 );
3735 // a column named as one of json_each's own columns would be
3736 // read as that column inside the subquery
3737 assert!(
3738 pushdown(
3739 "/orders/*[/value::city = 'Lyon']::id",
3740 Some(Dialect::Sqlite)
3741 )
3742 .is_none()
3743 );
3744 }
3745
3746 #[test]
3747 fn partial_json_property_prefilters() {
3748 let sqlite = |q: &str| partial_pushdown(q, Some(Dialect::Sqlite)).map(|p| p.where_sql);
3749 // a comparison lets the arrays through with the text values:
3750 // a list matches when any item does, and the engine decides
3751 assert_eq!(
3752 sqlite("/orders/*[/payload::total > 150]::id").unwrap(),
3753 "(json_valid(payload) AND (json_extract(payload, '$.total') > 150 \
3754 OR json_type(payload, '$.total') IN ('text', 'array')))"
3755 );
3756 assert_eq!(
3757 sqlite("/orders/*[/payload/customer::tier < 'm']::id").unwrap(),
3758 "(json_valid(payload) AND (json_extract(payload, '$.customer.tier') < 'm' \
3759 OR json_type(payload, '$.customer.tier') = 'array'))"
3760 );
3761 // a bare property: present, as the child form
3762 assert_eq!(
3763 sqlite("/orders/*[/payload::gift]::id").unwrap(),
3764 "(json_valid(payload) AND json_type(payload, '$.gift') IS NOT NULL)"
3765 );
3766 // `!=` keeps a row whose key is absent: its floor is the node
3767 // the property is read on, and on the column itself there is
3768 // none
3769 assert_eq!(
3770 sqlite("/orders/*[/payload/customer::tier != 'x']::id").unwrap(),
3771 "(json_valid(payload) AND json_type(payload, '$.customer') IS NOT NULL)"
3772 );
3773 assert!(sqlite("/orders/*[/payload::status != 'x']::id").is_none());
3774 // PostgreSQL: the equality as a prefilter, the arrays through
3775 assert_eq!(
3776 partial_pushdown(
3777 "/orders/*[/payload/customer/geo::city = 'Lyon']::id",
3778 Some(Dialect::Postgres)
3779 )
3780 .unwrap()
3781 .where_sql,
3782 "(CASE WHEN jsonb_typeof(payload::jsonb #> '{customer,geo,city}') = 'string' \
3783 THEN (payload::jsonb #>> '{customer,geo,city}') = 'Lyon' \
3784 WHEN jsonb_typeof(payload::jsonb #> '{customer,geo,city}') = 'array' \
3785 THEN true ELSE false END)"
3786 );
3787 assert_eq!(
3788 partial_pushdown(
3789 "/orders/*[/payload::total > 150]::id",
3790 Some(Dialect::Postgres)
3791 )
3792 .unwrap()
3793 .where_sql,
3794 "(CASE WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'number' \
3795 THEN ((payload::jsonb #>> '{total}'))::float8 > 150 \
3796 WHEN jsonb_typeof(payload::jsonb #> '{total}') IN ('string', 'array') \
3797 THEN true ELSE false END)"
3798 );
3799 // no type probe, no prefilter
3800 assert!(
3801 partial_pushdown("/orders/*[/payload::total > 150]::id", Some(Dialect::MySql))
3802 .is_none()
3803 );
3804 }
3805
3806 #[test]
3807 fn json_pushdown_refuses_a_container_looking_literal() {
3808 // An extractor answers an array or an object as its JSON
3809 // text, so `'[1,2]'` equalled the array itself, which has no
3810 // value in the graft: the whole push kept a row the scan
3811 // drops. It rides the prefilter (a superset, re-checked).
3812 for q in [
3813 "/orders/*[/data/a:: = '[1,2]']::id",
3814 "/orders/*[/data/a:: = '{\"k\":1}']::id",
3815 ] {
3816 assert!(pushdown(q, Some(Dialect::Sqlite)).is_none(), "{q}");
3817 assert!(pushdown(q, Some(Dialect::Postgres)).is_none(), "{q}");
3818 }
3819 assert_eq!(
3820 partial_pushdown("/orders/*[/data/a:: = '[1,2]']::id", Some(Dialect::Sqlite))
3821 .unwrap()
3822 .where_sql,
3823 "(json_valid(data) AND json_extract(data, '$.a') = '[1,2]')"
3824 );
3825 }
3826
3827 #[test]
3828 fn partial_skips_untranslatable_keeps_prefix() {
3829 // A refused predicate no prefilter covers is skipped — the
3830 // shorter conjunction is still a superset (the engine
3831 // re-applies the original) — rather than aborting the plan.
3832 let p = partial_pushdown(
3833 "/orders/*[::status = 'shipped'][/payload/line_items/*/sku:: = 'X']::id",
3834 Some(Dialect::Sqlite),
3835 )
3836 .unwrap();
3837 assert_eq!(p.where_sql, "status = 'shipped'");
3838 }
3839
3840 #[test]
3841 fn null_literal_compares_use_is_null() {
3842 // `= null` / `!= null` are provably identical to Quarb's
3843 // value_eq(NULL, …) semantics, never the always-UNKNOWN
3844 // `x = NULL`; they translate — and push — in both modes.
3845 assert_eq!(
3846 export("/t/*[::x = null] | ::x").unwrap().query,
3847 "SELECT x FROM t WHERE x IS NULL"
3848 );
3849 assert_eq!(
3850 export("/t/*[::x != null] | ::x").unwrap().query,
3851 "SELECT x FROM t WHERE x IS NOT NULL"
3852 );
3853 assert_eq!(
3854 pushdown("/t/*[::x = null] | ::x", None).unwrap().sql,
3855 "SELECT x FROM t WHERE x IS NULL"
3856 );
3857 assert_eq!(
3858 pushdown("/t/*[::x != null] | ::x", None).unwrap().sql,
3859 "SELECT x FROM t WHERE x IS NOT NULL"
3860 );
3861 }
3862
3863 #[test]
3864 fn ne_and_not_push_in_the_form_that_keeps_the_null_rows() {
3865 // `!=` against a value and `!(...)` hold for a NULL in Quarb
3866 // and are UNKNOWN in SQL. The plan says the cases SQL's
3867 // operators leave out, in SQL every engine reads (the scan's
3868 // answers beside the plan's: tests/sql.rs).
3869 assert_eq!(
3870 pushdown("/t/*[::x != 5] | ::x", None).unwrap().sql,
3871 "SELECT x FROM t WHERE (x <> 5 OR x IS NULL)"
3872 );
3873 assert_eq!(
3874 pushdown("/t/*[::x != ::y] | ::x", None).unwrap().sql,
3875 "SELECT x FROM t WHERE (x <> y OR (x IS NULL AND y IS NOT NULL) OR (x IS NOT NULL \
3876 AND y IS NULL))"
3877 );
3878 assert_eq!(
3879 pushdown("/t/*[!::x = 5] | ::x", None).unwrap().sql,
3880 "SELECT x FROM t WHERE (CASE WHEN x = 5 THEN 0 ELSE 1 END = 1)"
3881 );
3882 // two NULLs are equal in Quarb: an equality of two columns
3883 // says so
3884 assert_eq!(
3885 pushdown("/t/*[::x = ::y] | ::x", None).unwrap().sql,
3886 "SELECT x FROM t WHERE (x = y OR (x IS NULL AND y IS NULL))"
3887 );
3888 // the prefilter takes them too
3889 assert_eq!(
3890 partial_pushdown(&format!("/t/*[::x != 5]{GROUPED}"), None)
3891 .unwrap()
3892 .where_sql,
3893 "(x <> 5 OR x IS NULL)"
3894 );
3895 // The display translation still emits `<>`, flagged with a note.
3896 let t = export("/t/*[::x != 5] | ::x").unwrap();
3897 assert_eq!(t.query, "SELECT x FROM t WHERE x <> 5");
3898 assert!(t.notes.iter().any(|n| n.contains("NULL")));
3899 }
3900
3901 #[test]
3902 fn unescapable_text_literal_refuses_pushdown() {
3903 // A backslash (MySQL/BigQuery escape) or an apostrophe
3904 // (BigQuery rejects '' doubling) has no portable escaping, so
3905 // pushdown refuses; a clean literal still pushes.
3906 assert!(pushdown("/files/*[::path = \"C:\\temp\"] | ::path", None).is_none());
3907 assert!(pushdown("/t/*[::name = \"it's\"] | ::name", None).is_none());
3908 assert!(partial_pushdown(&format!("/t/*[::name = \"it's\"]{GROUPED}"), None).is_none());
3909 assert_eq!(
3910 pushdown("/t/*[::name = \"rare\"] | ::name", None)
3911 .unwrap()
3912 .sql,
3913 "SELECT name FROM t WHERE name = 'rare'"
3914 );
3915 }
3916}