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 // Inside a join condition a comparison that reads
1691 // the driver is a key comparison, unknown for a
1692 // null on either side, the literal too (spec:
1693 // Null keys): `[$$0::x != null && …]` admits no
1694 // candidate. IS [NOT] NULL would answer, so the
1695 // plan is not the scan's. (It was pushed so: five
1696 // pairs from the plan, none from the scan.)
1697 if self.in_on && self.subtree_has_driver(other) {
1698 return Err(not_pushed(
1699 Refusal::Join,
1700 "a test of the driver's key for null inside the join condition (a \
1701 key comparison never holds for a null there: test it on the \
1702 driver, '/t/*[::x != null] <=> …')"
1703 .into(),
1704 ));
1705 }
1706 let col = self.operand(other, qual)?;
1707 return Ok(if op == "=" {
1708 format!("{col} IS NULL")
1709 } else {
1710 format!("{col} IS NOT NULL")
1711 });
1712 }
1713 // JSON-column-path pushdown: `[/col/a/b:: = 'lit']`
1714 // navigates into a JSON column and compares a fixed
1715 // path to a string literal. Only this exact shape —
1716 // fixed object path, string equality, and a literal
1717 // that does NOT look numeric — is provably identical
1718 // to the client-side graft (each engine's scalar
1719 // extractor unquotes to text, and an absent path or
1720 // non-string value excludes the row on both sides,
1721 // matching Quarb's `value_eq` on non-numeric text).
1722 // Numeric casts, `!=`, wildcards, and deeper
1723 // predicates fall through to the ordinary operand
1724 // logic below, which refuses the navigation; the
1725 // partial-pushdown prefilter ladder picks those up
1726 // with superset semantics. Enabled only when a
1727 // dialect is set.
1728 if op == "="
1729 && let Some(dialect) = self.dialect
1730 {
1731 for (pi, li) in [(0usize, 1usize), (1, 0)] {
1732 if self.is_text_literal(kids[li])
1733 && let Some((col, path)) = self.json_path(kids[pi])
1734 {
1735 self.note_json_column(kids[pi], &col);
1736 // Quarb's value_eq compares numeric-looking
1737 // strings numerically — '150' matches the
1738 // JSON number 150, and the string "150.0".
1739 // No engine's text extractor coerces that
1740 // way, so the pushed compare would drop
1741 // rows the graft keeps. Refuse; the
1742 // prefilter ladder handles it as a
1743 // superset.
1744 let raw = self
1745 .prop(kids[li], "value")
1746 .map(|v| v.to_string())
1747 .unwrap_or_default();
1748 if raw.trim().parse::<f64>().is_ok() {
1749 return Err(mismatch(
1750 Refusal::Type,
1751 "a numeric-looking text literal against a \
1752 JSON path compares numerically in Quarb \
1753 (value coercion); no SQL extractor \
1754 matches that"
1755 .into(),
1756 ));
1757 }
1758 // An extractor answers a container as
1759 // its JSON text (SQLite `[1,2]`,
1760 // PostgreSQL `[1, 2]`), so a literal that
1761 // is such a text equalled the array or
1762 // the object itself, which has no value
1763 // in the graft: the push kept a row the
1764 // scan drops. No scalar's text opens
1765 // with a bracket or a brace that a
1766 // container's does not, so such a
1767 // literal rides the prefilter.
1768 if raw.starts_with('[') || raw.starts_with('{') {
1769 return Err(mismatch(
1770 Refusal::Type,
1771 "a text literal that opens like a JSON container \
1772 could equal an array's or an object's own text \
1773 in the extractor, which has no value in Quarb"
1774 .into(),
1775 ));
1776 }
1777 let lit = self.operand(kids[li], qual)?;
1778 let extract = json_extract(dialect, qual, &col, &path);
1779 return Ok(json_valid_guard(
1780 dialect,
1781 qual,
1782 &col,
1783 format!("{extract} = {lit}"),
1784 ));
1785 }
1786 }
1787 // The property form, `[/col/a::b = 'lit']`: the
1788 // same question on a scalar, and on an array of
1789 // scalars the list, which equals the literal when
1790 // any item does (an array that holds a container
1791 // is no property). SQLite says both in one
1792 // condition, exactly: the scalar branch by the
1793 // value's type and text, the array branch by
1794 // `json_each`. The other engines' array branches
1795 // are not verified live, so there the shape rides
1796 // the prefilter (PostgreSQL) or the scan.
1797 for (pi, li) in [(0usize, 1usize), (1, 0)] {
1798 if self.is_text_literal(kids[li])
1799 && let Some((col, path)) = self.json_property_path(kids[pi])
1800 {
1801 self.note_json_column(kids[pi], &col);
1802 let raw = self
1803 .prop(kids[li], "value")
1804 .map(|v| v.to_string())
1805 .unwrap_or_default();
1806 if raw.trim().parse::<f64>().is_ok() {
1807 return Err(mismatch(
1808 Refusal::Type,
1809 "a numeric-looking text literal against a \
1810 JSON path compares numerically in Quarb \
1811 (value coercion); no SQL extractor \
1812 matches that"
1813 .into(),
1814 ));
1815 }
1816 // `json_each` names its own columns; an
1817 // unqualified JSON column of one of those
1818 // names would read as them inside it.
1819 let shadowed = qual.is_none()
1820 && JSON_EACH_COLUMNS.contains(&col.to_ascii_lowercase().as_str());
1821 if dialect != Dialect::Sqlite || shadowed {
1822 return Err(mismatch(
1823 Refusal::Type,
1824 "a property of a JSON value may be a list (an \
1825 array of scalars equals the literal when any \
1826 item does); only SQLite's condition carries \
1827 that branch whole; this shape rides the \
1828 partial prefilter"
1829 .into(),
1830 ));
1831 }
1832 let lit = self.operand(kids[li], qual)?;
1833 let qcol = match qual {
1834 Some(q) => format!("{q}.{col}"),
1835 None => col.clone(),
1836 };
1837 let at = format!("'$.{}'", path.join("."));
1838 let ty = format!("json_type({qcol}, {at})");
1839 let ex = json_extract(dialect, qual, &col, &path);
1840 return Ok(json_valid_guard(
1841 dialect,
1842 qual,
1843 &col,
1844 format!(
1845 "(({ty} = 'text' AND {ex} = {lit}) OR ({ty} = 'array' \
1846 AND EXISTS (SELECT 1 FROM json_each({qcol}, {at}) \
1847 WHERE json_each.type = 'text' AND json_each.value = {lit}) \
1848 AND NOT EXISTS (SELECT 1 FROM json_each({qcol}, {at}) \
1849 WHERE json_each.type IN ('array', 'object'))))"
1850 ),
1851 ));
1852 }
1853 }
1854 }
1855 // Any other JSON-path comparison: name the real
1856 // reason, not the generic flat-rows refusal — only
1857 // fixed-path string equality is provably identical
1858 // (Quarb coerces numeric-looking values; no
1859 // engine's extractor matches that). The partial
1860 // prefilter ladder covers these shapes.
1861 if self.dialect.is_some() {
1862 for side in [kids[0], kids[1]] {
1863 if self.json_path(side).is_some()
1864 || self.json_path_loose(side).is_some()
1865 || self.json_property_path(side).is_some()
1866 {
1867 return Err(mismatch(
1868 Refusal::Type,
1869 "a JSON-path comparison pushes whole only as \
1870 fixed-path string equality (Quarb coerces \
1871 numeric-looking values; no extractor matches \
1872 that); this shape rides the partial prefilter"
1873 .into(),
1874 ));
1875 }
1876 }
1877 }
1878 // Quarb compares by value; SQL by the column's type.
1879 // A column against a numeric literal is the scan's
1880 // comparison only on a numeric-typed column, and
1881 // against a text literal only on a column that is
1882 // not (MySQL reads `n = 'abc'` as `n = 0`): the
1883 // catalog decides, so both are recorded for the
1884 // caller. A numeric-looking TEXT literal meets
1885 // numbers as a number in Quarb and compares as text
1886 // in SQL, on every engine, so it does not push. A
1887 // regex is no value: its refusal below is the
1888 // pattern's, whatever its text reads as.
1889 if self.strict && !matches!(op.as_str(), "==" | "!==") {
1890 for (ci, li) in [(0usize, 1usize), (1, 0)] {
1891 let Some(column) = self.column_operand(kids[ci]) else {
1892 continue;
1893 };
1894 if self.kind(kids[li]) != "literal" {
1895 continue;
1896 }
1897 let numeric = self
1898 .prop(kids[li], "value")
1899 .is_some_and(|v| Value::Str(v.to_string()).numeric_reading().is_some());
1900 let list = match (self.prop_s(kids[li], "type").as_str(), numeric) {
1901 ("null", _) => continue,
1902 ("text", true) => {
1903 return Err(mismatch(
1904 Refusal::Type,
1905 "a numeric-looking text literal compares \
1906 numerically in Quarb (value coercion); SQL \
1907 compares it as text"
1908 .into(),
1909 ));
1910 }
1911 ("text", false) => &mut self.column_types.text,
1912 (_, true) => &mut self.column_types.numeric,
1913 (_, false) => continue,
1914 };
1915 if !list.contains(&column) {
1916 list.push(column);
1917 }
1918 }
1919 }
1920 let l = self.operand(kids[0], qual)?;
1921 // Ruling #33: a pattern literal on `=` pushes as
1922 // LIKE — a `%` per star, each literal segment
1923 // escaped, in order. Anchoring matches exactly:
1924 // LIKE anchors both ends, a flanking star lifts
1925 // one. The case-folding caveat is `*=`'s; `!=`
1926 // with a pattern rides the scan (NOT LIKE drops
1927 // the NULL rows Quarb keeps).
1928 if self.kind(kids[1]) == "pattern" {
1929 if op.as_str() != "=" {
1930 return Err(not_pushed(
1931 Refusal::Pattern,
1932 format!("a pattern literal on '{op}' (only '=' pushes)"),
1933 ));
1934 }
1935 // PostgreSQL's LIKE is case-sensitive under its
1936 // deterministic collations — provably what the
1937 // pattern test does — so the strict push is
1938 // sound there (and a prefix pattern is
1939 // index-sargable server-side). Everywhere else
1940 // case folding is ambient state (SQLite pragma,
1941 // MySQL/MSSQL collation), so strict refuses.
1942 if self.strict && self.dialect != Some(Dialect::Postgres) {
1943 return Err(mismatch(
1944 Refusal::Pattern,
1945 "LIKE case folding differs per engine \
1946 (provably case-sensitive only on PostgreSQL)"
1947 .into(),
1948 ));
1949 }
1950 if !self.strict {
1951 self.notes.push(
1952 "pattern → LIKE: Quarb's pattern test is \
1953 case-sensitive; LIKE folds case on \
1954 SQLite/MySQL but not PostgreSQL"
1955 .to_string(),
1956 );
1957 }
1958 let mut like = String::new();
1959 for kid in self.arbor.children(kids[1]) {
1960 match self.kind(kid).as_str() {
1961 "star" => like.push('%'),
1962 _ => {
1963 let raw = self
1964 .prop(kid, "value")
1965 .map(|v| v.to_string())
1966 .unwrap_or_default();
1967 like.push_str(
1968 &raw.replace('\\', "\\\\")
1969 .replace('%', "\\%")
1970 .replace('_', "\\_")
1971 .replace('\'', "''"),
1972 );
1973 }
1974 }
1975 }
1976 return Ok(format!("{l} LIKE '{like}' ESCAPE '\\'"));
1977 }
1978 let r = self.operand(kids[1], qual)?;
1979 // Which sides can be NULL: every side that is no
1980 // literal. And whether this is a key comparison of a
1981 // join condition, which the engine leaves unknown for
1982 // a null on either side, as SQL does: there the plain
1983 // operators are the engine's own.
1984 let nullable: Vec<&str> = [(kids[0], l.as_str()), (kids[1], r.as_str())]
1985 .into_iter()
1986 .filter(|(k, _)| self.kind(*k) != "literal")
1987 .map(|(_, sql)| sql)
1988 .collect();
1989 let keyed = self.in_on
1990 && (self.subtree_has_driver(kids[0]) || self.subtree_has_driver(kids[1]));
1991 Ok(match op.as_str() {
1992 // Two NULLs are equal in Quarb (`value_eq`), and
1993 // SQL's `=` is UNKNOWN for them: an equality of
1994 // two columns says the second case too. (It was
1995 // pushed as the bare `a = b`, which dropped the
1996 // row where both are NULL.)
1997 "=" if self.strict && !keyed && nullable.len() == 2 => {
1998 format!("({l} = {r} OR ({l} IS NULL AND {r} IS NULL))")
1999 }
2000 "=" => format!("{l} = {r}"),
2001 // Quarb's `!=` holds for a NULL against a value
2002 // and fails for two NULLs; SQL's `<>` is UNKNOWN
2003 // for either. The plan adds the cases `<>` leaves
2004 // out, in SQL every engine reads.
2005 "!=" if self.strict && !keyed => match nullable.as_slice() {
2006 [] => format!("{l} <> {r}"),
2007 [one] => format!("({l} <> {r} OR {one} IS NULL)"),
2008 _ => format!(
2009 "({l} <> {r} OR ({l} IS NULL AND {r} IS NOT NULL) OR ({l} IS NOT \
2010 NULL AND {r} IS NULL))"
2011 ),
2012 },
2013 "!=" if self.strict => format!("{l} <> {r}"),
2014 "!=" => {
2015 // The display translation keeps `<>` and
2016 // notes the divergence.
2017 self.notes.push(
2018 "'!=' → '<>': Quarb keeps rows whose column is NULL; \
2019 SQL's '<>' drops them (use '!= null' for IS NOT NULL)"
2020 .to_string(),
2021 );
2022 format!("{l} <> {r}")
2023 }
2024 "<" | "<=" | ">" | ">=" => format!("{l} {op} {r}"),
2025 // SQLite's instr is a substring test by bytes,
2026 // case and all, as `*=` is; the column is a text
2027 // one (recorded above with the literal: a number
2028 // would be searched in SQLite's rendering of it,
2029 // not the engine's). A NULL has no substring on
2030 // either side.
2031 "*=" if self.strict
2032 && self.dialect == Some(Dialect::Sqlite)
2033 && self.is_text_literal(kids[1])
2034 && self.column_operand(kids[0]).is_some() =>
2035 {
2036 format!("instr({l}, {r}) > 0")
2037 }
2038 "*=" => {
2039 // The same PostgreSQL rung as the pattern
2040 // literal above: LIKE is provably
2041 // case-sensitive there, so `*=` pushes
2042 // strict too.
2043 if self.strict && self.dialect != Some(Dialect::Postgres) {
2044 return Err(mismatch(
2045 Refusal::Pattern,
2046 "LIKE case folding differs per engine \
2047 (a substring test is pushed on SQLite as instr and on \
2048 PostgreSQL as LIKE)"
2049 .into(),
2050 ));
2051 }
2052 // The pattern must be a text literal: a
2053 // column or computed operand holds a value,
2054 // not a pattern, and SQL LIKE cannot express
2055 // "contains that value" portably.
2056 if !self.is_text_literal(kids[1]) {
2057 return Err(not_pushed(
2058 Refusal::Pattern,
2059 "'*=' with a non-literal pattern".into(),
2060 ));
2061 }
2062 self.notes.push(
2063 "*= → LIKE: Quarb's substring test is case-sensitive; LIKE \
2064 folds case on SQLite/MySQL but not PostgreSQL"
2065 .to_string(),
2066 );
2067 // Escape LIKE's metacharacters, then quote.
2068 // The explicit ESCAPE makes '\' the escape
2069 // everywhere — SQLite, MSSQL, and Oracle
2070 // have no default escape character.
2071 let raw = self
2072 .prop(kids[1], "value")
2073 .map(|v| v.to_string())
2074 .unwrap_or_default();
2075 let pat = raw
2076 .replace('\\', "\\\\")
2077 .replace('%', "\\%")
2078 .replace('_', "\\_")
2079 .replace('\'', "''");
2080 format!("{l} LIKE '%{pat}%' ESCAPE '\\'")
2081 }
2082 "==" | "!==" | "=~" | "!~" => {
2083 return Err(mismatch(
2084 Refusal::Pattern,
2085 "regex matching means a different REGEXP engine per \
2086 backend; regexes run engine-side"
2087 .into(),
2088 ));
2089 }
2090 other => {
2091 return Err(not_pushed(
2092 Refusal::Operator,
2093 format!("the '{other}' comparison"),
2094 ));
2095 }
2096 })
2097 }
2098 // A bare truthy operand.
2099 _ => {
2100 if self.strict {
2101 return Err(mismatch(
2102 Refusal::Type,
2103 "truthiness diverges (0 and '' are falsy in Quarb)".into(),
2104 ));
2105 }
2106 self.notes.push(
2107 "truthiness: '[::c]' exports as IS NOT NULL, but Quarb also treats \
2108 0 and '' as falsy"
2109 .to_string(),
2110 );
2111 Ok(format!("{} IS NOT NULL", self.operand(e, qual)?))
2112 }
2113 }
2114 }
2115
2116 fn operand(&mut self, o: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
2117 match self.kind(o).as_str() {
2118 "literal" => {
2119 let v = self.prop(o, "value").unwrap_or(Value::Null);
2120 match self.prop_s(o, "type").as_str() {
2121 "text" => {
2122 let s = v.to_string();
2123 // No single escaping is portable across the
2124 // pushdown's target dialects: MySQL (default
2125 // sql_mode) and BigQuery read `\` as an escape
2126 // while SQLite/PostgreSQL/DuckDB take it
2127 // literally, and BigQuery rejects the `''`
2128 // quote-doubling the others require. A literal
2129 // carrying either character cannot be pushed as
2130 // provably identical SQL, so refuse it and let
2131 // the caller scan. (The display translation
2132 // keeps its best-effort `''`-doubling.)
2133 if self.strict && (s.contains('\'') || s.contains('\\')) {
2134 return Err(mismatch(
2135 Refusal::Name,
2136 "a text literal with a quote or backslash \
2137 has no escaping portable across SQL dialects"
2138 .into(),
2139 ));
2140 }
2141 Ok(format!("'{}'", s.replace('\'', "''")))
2142 }
2143 "null" => Ok("NULL".to_string()),
2144 _ => Ok(v.to_string()),
2145 }
2146 }
2147 "path" => {
2148 if self.kid(o, "step").is_some() {
2149 // A step here is either navigation (refused) or
2150 // a resolution chain (refused with the reason).
2151 let s = self.kids(o, "step")[0];
2152 if self.prop_s(s, "axis") == "-->" {
2153 return Err(not_pushed(
2154 Refusal::Resolution,
2155 "a '-->' resolution chain: the foreign-key targets live in \
2156 the schema, not the query — spell the join with '<=>' to \
2157 export it"
2158 .into(),
2159 ));
2160 }
2161 return Err(not_pushed(
2162 Refusal::Resolution,
2163 "navigation inside a predicate (SQL rows are flat)".into(),
2164 ));
2165 }
2166 let p = self
2167 .kid(o, "projection")
2168 .ok_or_else(|| not_pushed(Refusal::Operator, "an empty path operand".into()))?;
2169 let col = self.projection_col(p)?;
2170 let col = self.sql_ident(&col, "column name")?;
2171 // a read through a mark: the row the mark names
2172 let (named, any) = self.mark_anchor(o);
2173 if any {
2174 let Some(name) = named else {
2175 return Err(not_pushed(
2176 Refusal::State,
2177 "a mark read by position, or of several marks".into(),
2178 ));
2179 };
2180 if self.join_marks.contains(&name) {
2181 // `$$.al::col`: the witness, as `$$1::col`
2182 if self.in_on {
2183 return Err(not_pushed(
2184 Refusal::Join,
2185 "the joined expression's own mark inside its ON".into(),
2186 ));
2187 }
2188 let Some(join) = self.join_sql.clone() else {
2189 return Err(not_pushed(
2190 Refusal::Join,
2191 "a join mark outside a correlation join".into(),
2192 ));
2193 };
2194 return Ok(format!("{join}.{col}"));
2195 }
2196 if self.from_marks.contains(&name) {
2197 // `$$.t::col`: the driver's row, as `$$0::col`
2198 // in the ON
2199 return Ok(if self.join_sql.is_some() {
2200 format!("{}.{col}", self.from_sql.clone())
2201 } else {
2202 match qual {
2203 Some(q) => format!("{q}.{col}"),
2204 None => col,
2205 }
2206 });
2207 }
2208 return Err(not_pushed(
2209 Refusal::State,
2210 format!("a read of the mark '.{name}' (not a row of the query's tables)"),
2211 ));
2212 }
2213 Ok(match qual {
2214 Some(q) => format!("{q}.{col}"),
2215 None => col,
2216 })
2217 }
2218 "context" => {
2219 // `$$1::col` — the joined expression's witness, in
2220 // pipeline position: the joined table's column.
2221 // Anything else is outside the verified-safe set.
2222 let p = self
2223 .kid(o, "projection")
2224 .ok_or_else(|| not_pushed(Refusal::Join, "a bare '$$N' reference".into()))?;
2225 let col = self.projection_col(p)?;
2226 let col = self.sql_ident(&col, "column name")?;
2227 if matches!(self.prop(o, "index"), Some(Value::Int(0))) {
2228 // `$$0::col` — the driver, legal only inside the
2229 // joined expression's ON bracket (the parser
2230 // refuses it anywhere else).
2231 if !self.in_on {
2232 return Err(not_pushed(
2233 Refusal::Join,
2234 "a '$$0' reference outside the join's ON".into(),
2235 ));
2236 }
2237 if self.kid(o, "step").is_some() {
2238 return Err(not_pushed(
2239 Refusal::Join,
2240 "a '$$0' reference beyond a plain column ($$0::col)".into(),
2241 ));
2242 }
2243 return Ok(format!("{}.{col}", self.from_sql.clone()));
2244 }
2245 if self.in_on {
2246 return Err(not_pushed(
2247 Refusal::Join,
2248 "a '$$N' reference inside the ON (the driver is '$$0')".into(),
2249 ));
2250 }
2251 let Some(join) = self.join_sql.clone() else {
2252 return Err(not_pushed(
2253 Refusal::Join,
2254 "a '$$N' reference outside a correlation join".into(),
2255 ));
2256 };
2257 match self.prop(o, "index") {
2258 Some(Value::Int(1)) => Ok(format!("{join}.{col}")),
2259 None => Err(not_pushed(Refusal::Join, "a bare '$$N' reference".into())),
2260 Some(v) => Err(not_pushed(
2261 Refusal::Join,
2262 format!("$${v} beyond a two-branch correlation"),
2263 )),
2264 }
2265 }
2266 "invoking" => {
2267 // `$$__::col` — the invoking position of an enclosing
2268 // query body, never the driver (that is `$$0`, a
2269 // context of index 0, since draft 153). SQL has no
2270 // enclosing body to read.
2271 Err(not_pushed(
2272 Refusal::Join,
2273 "a '$$__' reference (the driver inside the ON is '$$0')".into(),
2274 ))
2275 }
2276 "arith" => {
2277 let op = self.prop_s(o, "op");
2278 let kids = self.arbor.children(o);
2279 let l = self.operand(kids[0], qual)?;
2280 let r = self.operand(kids[1], qual)?;
2281 Ok(match op.as_str() {
2282 "+" | "-" | "*" => format!("({l} {op} {r})"),
2283 "div" => format!("({l} / {r})"),
2284 "mod" => format!("({l} % {r})"),
2285 other => {
2286 return Err(not_pushed(
2287 Refusal::Operator,
2288 format!("'{other}' arithmetic"),
2289 ));
2290 }
2291 })
2292 }
2293 other => Err(not_pushed(
2294 Refusal::State,
2295 format!(
2296 "the '{other}' operand (registers, topics, and captures are Quarb-side state)"
2297 ),
2298 )),
2299 }
2300 }
2301
2302 fn projection_col(&mut self, p: NodeId) -> Result<String, SqlError> {
2303 match self.prop_s(p, "kind").as_str() {
2304 "property" => match self.prop(p, "key") {
2305 Some(k) => Ok(k.to_string()),
2306 None => Err(not_pushed(
2307 Refusal::Operator,
2308 "the bare '::' projection (name the column)".into(),
2309 )),
2310 },
2311 other => Err(not_pushed(
2312 Refusal::Operator,
2313 format!("the {other} metadata projection"),
2314 )),
2315 }
2316 }
2317
2318 /// The column a plain column operand names (`::col`, `$*1::col`):
2319 /// a path without a step, or a context reference, projecting a
2320 /// named property.
2321 /// A numeric reducer (`sum`, `mean`, `min`, `max`) pushed over a
2322 /// column is the scan's only on a numeric-typed column: the
2323 /// scan lifts unit text (`'18 parasang'` under a declared unit)
2324 /// to quantities and orders texts as texts, where SQL sums a
2325 /// text column by its leading digits and orders it by
2326 /// collation. Recorded for the caller's catalog as a
2327 /// comparison's assumption is.
2328 fn assume_numeric(&mut self, column: Option<String>) {
2329 if !self.strict {
2330 return;
2331 }
2332 if let Some(c) = column
2333 && !self.column_types.numeric.contains(&c)
2334 {
2335 self.column_types.numeric.push(c);
2336 }
2337 }
2338
2339 fn column_operand(&self, o: NodeId) -> Option<String> {
2340 match self.kind(o).as_str() {
2341 "path" if self.kid(o, "step").is_none() => {}
2342 "context" => {}
2343 _ => return None,
2344 }
2345 let p = self.kid(o, "projection")?;
2346 if self.prop_s(p, "kind") != "property" {
2347 return None;
2348 }
2349 self.prop(p, "key").map(|k| k.to_string())
2350 }
2351
2352 /// Whether `o` is a text string literal (`'London'`).
2353 fn is_text_literal(&self, o: NodeId) -> bool {
2354 self.kind(o) == "literal" && self.prop_s(o, "type") == "text"
2355 }
2356
2357 /// If `o` is the one JSON-column-path shape pushdown handles —
2358 /// `/col/seg/seg…::`, a plain-navigation path (every step `/`
2359 /// and a plain-identifier object key, no wildcards, no nested
2360 /// predicate), at least one segment past the column, ending in
2361 /// the bare `::` projection — return `(column, [json segments])`.
2362 /// Anything else is `None` (and falls back to the graft).
2363 fn json_path(&self, o: NodeId) -> Option<(String, Vec<String>)> {
2364 if self.kind(o) != "path" {
2365 return None;
2366 }
2367 let steps = self.kids(o, "step");
2368 if steps.len() < 2 {
2369 return None;
2370 }
2371 // The projection must be the bare `::` (default value of
2372 // the JSON leaf), not `::key` or a `:::`/`:` metadata form.
2373 let proj = self.kid(o, "projection")?;
2374 if self.prop_s(proj, "kind") != "property" || self.prop(proj, "key").is_some() {
2375 return None;
2376 }
2377 let mut names = Vec::with_capacity(steps.len());
2378 for s in &steps {
2379 if self.prop_s(*s, "axis") != "/"
2380 || self.prop_s(*s, "matcher-kind") != "name"
2381 || self.kid(*s, "predicate").is_some()
2382 {
2383 return None;
2384 }
2385 let name = self.prop_s(*s, "matcher");
2386 // Plain object keys only — no array indices, no
2387 // characters that would need per-dialect path escaping.
2388 let plain = !name.is_empty()
2389 && name
2390 .chars()
2391 .next()
2392 .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
2393 && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
2394 if !plain {
2395 return None;
2396 }
2397 names.push(name);
2398 }
2399 let col = names.remove(0);
2400 Some((col, names))
2401 }
2402
2403 /// The property form of a JSON-column path, `/col/seg…::key`:
2404 /// plain-navigation steps as in [`json_path`], at least the
2405 /// column's own, ending in the projection of a plain-identifier
2406 /// property. It asks for the same value as `/col/seg…/key::`
2407 /// where that is a scalar; on an array of scalars it is the
2408 /// list (see [`json_property_prefilter`]). Returns
2409 /// `(column, [json segments, the key last])`.
2410 ///
2411 /// [`json_path`]: Self::json_path
2412 /// [`json_property_prefilter`]: Self::json_property_prefilter
2413 fn json_property_path(&self, o: NodeId) -> Option<(String, Vec<String>)> {
2414 if self.kind(o) != "path" {
2415 return None;
2416 }
2417 let steps = self.kids(o, "step");
2418 if steps.is_empty() {
2419 return None;
2420 }
2421 let proj = self.kid(o, "projection")?;
2422 if self.prop_s(proj, "kind") != "property" {
2423 return None;
2424 }
2425 let key = self.prop(proj, "key")?.to_string();
2426 let plain = |name: &str| {
2427 !name.is_empty()
2428 && name
2429 .chars()
2430 .next()
2431 .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
2432 && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
2433 };
2434 if !plain(&key) {
2435 return None;
2436 }
2437 let mut names = Vec::with_capacity(steps.len() + 1);
2438 for s in &steps {
2439 if self.prop_s(*s, "axis") != "/"
2440 || self.prop_s(*s, "matcher-kind") != "name"
2441 || self.kid(*s, "predicate").is_some()
2442 {
2443 return None;
2444 }
2445 let name = self.prop_s(*s, "matcher");
2446 if !plain(&name) {
2447 return None;
2448 }
2449 names.push(name);
2450 }
2451 names.push(key);
2452 let col = names.remove(0);
2453 Some((col, names))
2454 }
2455
2456 /// A safe `AS` alias: bare when it is a plain identifier and
2457 /// not an SQL keyword; otherwise strict mode refuses (quoting
2458 /// dialects disagree) and export mode double-quotes, noting it.
2459 fn alias(&mut self, name: &str) -> Result<String, SqlError> {
2460 if is_plain_ident(name) {
2461 return Ok(name.to_string());
2462 }
2463 if self.strict {
2464 return Err(not_pushed(
2465 Refusal::Name,
2466 format!(
2467 "field name {name:?} needs SQL quoting \
2468 (dialects disagree); rename the field"
2469 ),
2470 ));
2471 }
2472 self.notes
2473 .push(format!("field name {name:?} double-quoted (ANSI)"));
2474 Ok(format!("\"{}\"", name.replace('"', "\"\"")))
2475 }
2476
2477 /// A table or column name rendered into SQL. Bare when it is a
2478 /// plain identifier; otherwise strict mode refuses — a name
2479 /// like `a OR b` would silently rewrite the emitted SQL's
2480 /// meaning, breaking the provably-identical guarantee (and a
2481 /// portable quoting does not exist) — and export mode
2482 /// double-quotes with a note.
2483 fn sql_ident(&mut self, name: &str, what: &str) -> Result<String, SqlError> {
2484 if is_plain_ident(name) {
2485 return Ok(name.to_string());
2486 }
2487 if self.strict {
2488 return Err(not_pushed(
2489 Refusal::Name,
2490 format!("{what} {name:?} is not a plain SQL identifier"),
2491 ));
2492 }
2493 self.notes
2494 .push(format!("{what} {name:?} double-quoted (ANSI)"));
2495 Ok(format!("\"{}\"", name.replace('"', "\"\"")))
2496 }
2497
2498 /// Split a joined-side predicate: `col = $*1::col2` equalities
2499 /// become the ON condition; everything else the WHERE.
2500 /// `ltable` and `rtable` are the tables' SQL renderings.
2501 fn split_join_pred(
2502 &mut self,
2503 p: NodeId,
2504 rtable: &str,
2505 on: &mut Vec<String>,
2506 wheres: &mut Vec<String>,
2507 ) -> Result<(), SqlError> {
2508 if self.prop_s(p, "kind") != "expr" {
2509 return Err(not_pushed(
2510 Refusal::Take,
2511 "a positional predicate on the joined side".into(),
2512 ));
2513 }
2514 // Flatten top-level ANDs; each conjunct routes to ON or
2515 // WHERE.
2516 fn conjuncts(ex: &Exporter, e: NodeId, out: &mut Vec<NodeId>) {
2517 if ex.kind(e) == "and" {
2518 for c in ex.arbor.children(e) {
2519 conjuncts(ex, c, out);
2520 }
2521 } else {
2522 out.push(e);
2523 }
2524 }
2525 let mut parts = Vec::new();
2526 for c in self.arbor.children(p) {
2527 conjuncts(self, c, &mut parts);
2528 }
2529 for e in parts {
2530 let uses_driver = self.subtree_has_driver(e);
2531 self.in_on = true;
2532 let cond = self.pred_expr(e, Some(rtable));
2533 self.in_on = false;
2534 let cond = cond?;
2535 if uses_driver && self.kind(e) == "compare" && self.prop_s(e, "op") == "=" {
2536 // Record which joined-table columns the ON binds —
2537 // the uniqueness obligation (see
2538 // Pushdown::join_left). Collected from the arbor's
2539 // bare-column operand nodes, never from the
2540 // rendered SQL text, so neither a literal nor an
2541 // unusual column name can corrupt the obligation.
2542 self.collect_join_cols(e)?;
2543 on.push(cond);
2544 } else {
2545 wheres.push(cond);
2546 }
2547 }
2548 Ok(())
2549 }
2550
2551 /// The joined-table columns the ON equality binds: every bare
2552 /// column operand (`::col`) in `e`'s subtree, appended to the
2553 /// join obligation with their raw (catalog) names.
2554 fn collect_join_cols(&mut self, e: NodeId) -> Result<(), SqlError> {
2555 // The `$$0` side is the driver — not part of the joined
2556 // table's obligation.
2557 if self.is_driver(e) {
2558 return Ok(());
2559 }
2560 if self.kind(e) == "path"
2561 && self.kid(e, "step").is_none()
2562 && let Some(p) = self.kid(e, "projection")
2563 {
2564 let col = self.projection_col(p)?;
2565 self.join_on_cols.push(col);
2566 }
2567 for c in self.arbor.children(e) {
2568 self.collect_join_cols(c)?;
2569 }
2570 Ok(())
2571 }
2572
2573 /// `$$0`: a context operand of index 0 (the driver), or a read
2574 /// of the driver's row through its mark (`$$.t::col`).
2575 fn is_driver(&self, n: NodeId) -> bool {
2576 (self.kind(n) == "context" && matches!(self.prop(n, "index"), Some(Value::Int(0))))
2577 || (self.kind(n) == "path"
2578 && matches!(self.mark_anchor(n).0, Some(name) if self.from_marks.contains(&name)))
2579 }
2580
2581 fn subtree_has_driver(&self, n: NodeId) -> bool {
2582 self.is_driver(n)
2583 || self
2584 .arbor
2585 .children(n)
2586 .into_iter()
2587 .any(|c| self.subtree_has_driver(c))
2588 }
2589
2590 /// Consume the pipeline into SELECT clauses. `projected` is the
2591 /// driving path's own terminal projection, where it has one:
2592 /// the column as SQL and its name.
2593 fn pipeline(
2594 &mut self,
2595 q: NodeId,
2596 sel: &mut Select,
2597 join: Option<(&str, &str)>,
2598 projected: Option<(String, String)>,
2599 ) -> Result<(), SqlError> {
2600 let Some(pipe) = self.kid(q, "pipeline") else {
2601 return Ok(());
2602 };
2603 let commands: Vec<NodeId> = self.arbor.children(pipe);
2604 let mut i = 0;
2605 // A pending per-row value (`| ::col`) feeding an aggregate,
2606 // and the column it names where it is one. The path's own
2607 // projection is that value from the start, so the glued
2608 // spelling plans as the piped one: `/t/*::col @| max` is
2609 // `/t/* | ::col @| max` (it was refused as a reducer "over
2610 // row nodes", with a hint to write the piped form).
2611 let (mut pending_col, mut pending_name) = match projected {
2612 Some((col, name)) => (Some(col), Some(name)),
2613 None => (None, None),
2614 };
2615 // After a grouped reduction: (key, agg_sql, alias).
2616 let mut grouped: Option<(String, String, String)> = None;
2617 // A pushed key awaiting its fold: (the regula's name, key_sql).
2618 let mut pushed_key: Option<(String, String)> = None;
2619 // …and the column it is, where it is one plain column.
2620 let mut pushed_key_column: Option<String> = None;
2621 // The regula a fold went by: the name its key has in the
2622 // record `%.` answers.
2623 let mut grouped_reg: Option<String> = None;
2624
2625 while i < commands.len() {
2626 let s = commands[i];
2627 match self.kind(s).as_str() {
2628 "expr" => {
2629 let kids = self.arbor.children(s);
2630 pending_col = Some(self.operand(kids[0], join.map(|(l, _)| l))?);
2631 pending_name = self.column_operand(kids[0]);
2632 }
2633 "cmd" => {
2634 let name = self.prop_s(s, "name");
2635 match name.as_str() {
2636 "rec" | "record" => {
2637 sel.select = self.record_fields(s, join)?;
2638 self.order.record = true;
2639 }
2640 // `| %` on a row node is the record of its
2641 // properties, which are the row's columns in
2642 // the table's order: SELECT *, a record even
2643 // of one field. It is the plan a bare
2644 // selection of row nodes had before the
2645 // ruling of 2026-11-18 gave that one its
2646 // locators. Last in the pipeline and over
2647 // the rows themselves: after a projection
2648 // the thread holds a value, and a joined
2649 // row's record is the driver's alone.
2650 "%" if self.strict
2651 && join.is_none()
2652 && sel.select.is_empty()
2653 && pending_col.is_none()
2654 && grouped.is_none()
2655 && pushed_key.is_none()
2656 && !self.aggregate
2657 && self.arbor.children(s).is_empty()
2658 && i + 1 == commands.len() =>
2659 {
2660 sel.select = vec!["*".to_string()];
2661 self.order.record = true;
2662 self.order.properties = true;
2663 }
2664 // A reducing aggregate on the plain pipe:
2665 // the grouped reduction.
2666 "count" | "sum" | "mean" | "min" | "max" => {
2667 let (key, _, _) = grouped.as_ref().ok_or_else(|| {
2668 not_pushed(
2669 Refusal::Reducer,
2670 format!("'| {name}' outside a group (use '@| {name}')"),
2671 )
2672 })?;
2673 // Quarb's count counts every member,
2674 // nulls included: COUNT(*); the
2675 // NULL-skipping COUNT(col) is
2676 // `count(--values)`.
2677 let values =
2678 self.reducer_counts_values(s, &name, pending_col.is_some())?;
2679 let col = if name == "count" {
2680 pending_col.take().filter(|_| values)
2681 } else {
2682 self.assume_numeric(pending_name.take());
2683 pending_col.take()
2684 };
2685 let agg = sql_agg(&name, col)?;
2686 grouped = Some((key.clone(), agg.clone(), agg));
2687 }
2688 other => {
2689 // sort/unique/top and kin are spellable
2690 // in SQL but with the backend's own
2691 // collation and duplicate semantics —
2692 // name the divergence, not a missing
2693 // feature.
2694 if matches!(other, "sort" | "sort_by" | "unique" | "top" | "bottom") {
2695 return Err(mismatch(
2696 if other == "unique" {
2697 Refusal::Unique
2698 } else {
2699 Refusal::Sort
2700 },
2701 format!(
2702 "'{other}' means the backend's collation and \
2703 duplicate semantics; one engine-side ordering \
2704 keeps it identical everywhere"
2705 ),
2706 ));
2707 }
2708 return Err(not_pushed(
2709 Refusal::Operator,
2710 format!("the '{other}' pipeline command"),
2711 ));
2712 }
2713 }
2714 }
2715 "push" => {
2716 // An alias for the grouped aggregate.
2717 if let Some((k, agg, _)) = grouped.take() {
2718 let alias = self.prop_s(s, "name");
2719 grouped = Some((k, agg, alias));
2720 } else {
2721 return Err(not_pushed(
2722 Refusal::State,
2723 "a register push (Quarb-side state)".into(),
2724 ));
2725 }
2726 }
2727 // `| .k(::k)` before a fold by `.k`: the GROUP BY key
2728 // (a projection body is a subcontext of one branch).
2729 "expr-push" if grouped.is_none() && pushed_key.is_none() => {
2730 let kids = self.arbor.children(s);
2731 let key = self.operand(kids[0], join.map(|(l, _)| l))?;
2732 pushed_key = Some((self.prop_s(s, "name"), key));
2733 pushed_key_column = self.column_operand(kids[0]);
2734 }
2735 "subcontext" if grouped.is_none() && pushed_key.is_none() => {
2736 let key = self.pushed_column(s, join.map(|(l, _)| l))?;
2737 // (unqualified, the SQL is the column's own name)
2738 pushed_key_column = join.is_none().then(|| key.clone());
2739 pushed_key = Some((self.prop_s(s, "name"), key));
2740 }
2741 "filter" => {
2742 if grouped.is_some() {
2743 // HAVING: `$_` / the alias refer to the
2744 // aggregate.
2745 let cond = self.having_cond(s)?;
2746 sel.having = Some(cond);
2747 } else {
2748 return Err(not_pushed(
2749 Refusal::State,
2750 "a mid-pipeline filter (put it in the row predicate)".into(),
2751 ));
2752 }
2753 }
2754 "recall" => {
2755 // `| %.` finalizes the grouped record.
2756 if self.prop_s(s, "ref") != "%." {
2757 return Err(not_pushed(
2758 Refusal::State,
2759 "a register recall (Quarb-side state)".into(),
2760 ));
2761 }
2762 let (key, agg, alias) = grouped.clone().ok_or_else(|| {
2763 not_pushed(Refusal::Fold, "'%.', with nothing grouped".into())
2764 })?;
2765 let alias = self.alias(&alias)?;
2766 // The record names the key by its regula (`.a`),
2767 // which need not be the column's name: the scan
2768 // answers %(a = …), and so must the plan.
2769 let key_field = match &grouped_reg {
2770 Some(reg) if *reg != key => format!("{key} AS {}", self.alias(reg)?),
2771 _ => key.clone(),
2772 };
2773 sel.select = vec![key_field, format!("{agg} AS {alias}")];
2774 self.order.record = true;
2775 // The HAVING condition compared the aggregate
2776 // through $_ — substitute the real expression.
2777 if let Some(h) = sel.having.take() {
2778 sel.having = Some(h.replace("__AGG__", &agg));
2779 }
2780 }
2781 "agg" if self.prop(s, "group").is_some() => {
2782 // The plan takes its first rows last: a command
2783 // over the rows a selection kept is the engine's.
2784 if self.strict && self.order.limit.is_some() {
2785 return Err(not_pushed(
2786 Refusal::Take,
2787 format!(
2788 "the '{}' command after a positional selection (a plan \
2789 takes its first rows last)",
2790 self.prop_s(s, "name")
2791 ),
2792 ));
2793 }
2794 // `@|{.k} agg`: the fold by the pushed key is the
2795 // grouped reduction, GROUP BY key.
2796 let name = self.prop_s(s, "name");
2797 if !matches!(name.as_str(), "count" | "sum" | "mean" | "min" | "max") {
2798 return Err(not_pushed(
2799 Refusal::Fold,
2800 format!("the '{name}' command per group (GROUP BY reduces)"),
2801 ));
2802 }
2803 let selector = self.prop_s(s, "group");
2804 if selector.contains(';') {
2805 return Err(not_pushed(
2806 Refusal::Fold,
2807 "a fold by several regulae (one GROUP BY key translates)".into(),
2808 ));
2809 }
2810 let (reg, key) = pushed_key.take().ok_or_else(|| {
2811 not_pushed(
2812 Refusal::Fold,
2813 "a fold by a regula no push of a key made".into(),
2814 )
2815 })?;
2816 grouped_reg = Some(reg.clone());
2817 if selector != "." && selector != format!(".{reg}") {
2818 return Err(not_pushed(
2819 Refusal::Fold,
2820 format!("a fold by '{selector}' (the pushed key is '.{reg}')"),
2821 ));
2822 }
2823 if self.strict {
2824 // SQL gives its groups in no stated order; the
2825 // engine gives them as each first appears. A
2826 // fold by one numeric column of the table is
2827 // pushed with that order asked of the driver
2828 // (the least key of each group). Numeric: two
2829 // texts that read as one number are one key
2830 // to the engine and two to GROUP BY.
2831 let plain = join.is_none()
2832 && self.order.sort.is_none()
2833 && self.order.limit.is_none()
2834 && !self.order.reversed;
2835 match pushed_key_column.take() {
2836 Some(column) if plain => {
2837 self.assume_numeric(Some(column.clone()));
2838 self.order.groups = true;
2839 self.order.keyed_by = Some((Refusal::Fold, column));
2840 }
2841 _ => {
2842 return Err(mismatch(
2843 Refusal::Fold,
2844 "a fold over a join, or after a sort or a selection, or by \
2845 anything but one column"
2846 .into(),
2847 ));
2848 }
2849 }
2850 }
2851 sel.group_by = Some(key.clone());
2852 let values = self.reducer_counts_values(s, &name, pending_col.is_some())?;
2853 let col = if name == "count" {
2854 // `count(--values)` over a projected column is
2855 // COUNT(col); the bare count is every row
2856 pending_col.take().filter(|_| values)
2857 } else {
2858 self.assume_numeric(pending_name.take());
2859 pending_col.take()
2860 };
2861 let agg = sql_agg(&name, col)?;
2862 grouped = Some((key, agg.clone(), agg));
2863 }
2864 "agg" => {
2865 // The plan takes its first rows last: a command
2866 // over the rows a selection kept is the engine's.
2867 if self.strict && self.order.limit.is_some() {
2868 return Err(not_pushed(
2869 Refusal::Take,
2870 format!(
2871 "the '{}' command after a positional selection (a plan \
2872 takes its first rows last)",
2873 self.prop_s(s, "name")
2874 ),
2875 ));
2876 }
2877 let name = self.prop_s(s, "name");
2878 match name.as_str() {
2879 "count" | "sum" | "mean" | "min" | "max" => {
2880 // Quarb's count counts every row, nulls
2881 // included: COUNT(*) regardless of a
2882 // pending column. `count(--values)`
2883 // counts the values other than null:
2884 // COUNT(col) over a projected column.
2885 let values =
2886 self.reducer_counts_values(s, &name, pending_col.is_some())?;
2887 let col = if name == "count" {
2888 pending_col.take().filter(|_| values)
2889 } else {
2890 self.assume_numeric(pending_name.take());
2891 pending_col.take()
2892 };
2893 sel.select = vec![sql_agg(&name, col)?];
2894 self.aggregate = true;
2895 }
2896 "sort_by" if self.strict => {
2897 // A database orders text by its own
2898 // collation. A sort by one numeric column
2899 // of the table has one order everywhere:
2900 // it is pushed, the key recorded for the
2901 // catalog to confirm, a null key last and
2902 // the ties in the table's order, which the
2903 // driver's ORDER BY says after the plan's.
2904 let kids = self.arbor.children(s);
2905 let column = kids.first().and_then(|&k| self.column_operand(k));
2906 let plain = join.is_none()
2907 && self.order.sort.is_none()
2908 && self.order.limit.is_none()
2909 && !self.order.reversed
2910 && !self.order.groups
2911 && !self.aggregate
2912 && grouped.is_none();
2913 let column = match (column, plain) {
2914 (Some(column), true) => column,
2915 // one column, and no place for its
2916 // order in the plan
2917 (Some(_), false) => {
2918 return Err(not_pushed(
2919 Refusal::Sort,
2920 "a sort over a join, or after a selection, a fold or \
2921 another sort (a plan has one order)"
2922 .into(),
2923 ));
2924 }
2925 (None, _) => {
2926 return Err(mismatch(
2927 Refusal::Sort,
2928 "ORDER BY collations differ per engine".into(),
2929 ));
2930 }
2931 };
2932 let mut desc = false;
2933 for &k in &kids[1..] {
2934 let named =
2935 (self.kind(k) == "option").then(|| self.prop_s(k, "name"));
2936 match named.as_deref() {
2937 Some("--desc" | "-d") => desc = true,
2938 _ => {
2939 return Err(mismatch(
2940 Refusal::Sort,
2941 "ORDER BY collations differ per engine".into(),
2942 ));
2943 }
2944 }
2945 }
2946 let e = self.operand(kids[0], None)?;
2947 self.assume_numeric(Some(column.clone()));
2948 self.order.sort = Some((e, desc));
2949 self.order.keyed_by = Some((Refusal::Sort, column));
2950 }
2951 "sort_by" => {
2952 // A sort after a positional selection
2953 // (or a second sort) cannot render: the
2954 // fixed SELECT shape orders before
2955 // LIMIT, and has one ORDER BY.
2956 if sel.limit.is_some() {
2957 return Err(not_pushed(
2958 Refusal::Sort,
2959 "a sort after a positional selection (SQL orders \
2960 before LIMIT)"
2961 .into(),
2962 ));
2963 }
2964 if sel.order_by.is_some() {
2965 return Err(not_pushed(
2966 Refusal::Sort,
2967 "a second sort (SQL has a single ORDER BY)".into(),
2968 ));
2969 }
2970 let kids = self.arbor.children(s);
2971 // The options are the command's own:
2972 // `--desc` is the direction, a named
2973 // collation (`--locale=tag`, ruling
2974 // 2026-11-11) is the engine's order and no
2975 // backend's; a second key has no place in
2976 // the one ORDER BY this shape holds.
2977 let mut desc = false;
2978 for &k in &kids[1..] {
2979 if self.kind(k) != "option" {
2980 return Err(not_pushed(
2981 Refusal::Sort,
2982 "a sort by several keys".into(),
2983 ));
2984 }
2985 match self.prop_s(k, "name").as_str() {
2986 "--desc" | "-d" => desc = true,
2987 "--locale" => {
2988 return Err(mismatch(
2989 Refusal::Sort,
2990 "sort_by(--locale=…) names the engine's collation; \
2991 a backend's differs"
2992 .into(),
2993 ));
2994 }
2995 // a case order is that
2996 // collation's (ruling 2026-11-12)
2997 "--upper-first" | "-u" | "--lower-first" | "-l"
2998 | "--ignore-case" | "-i" => {
2999 return Err(mismatch(
3000 Refusal::Sort,
3001 "sort_by's case order is the engine's collation's; \
3002 a backend's differs"
3003 .into(),
3004 ));
3005 }
3006 other => {
3007 return Err(not_pushed(
3008 Refusal::Sort,
3009 format!("the '{other}' option of sort_by"),
3010 ));
3011 }
3012 }
3013 }
3014 let e = self.operand(kids[0], join.map(|(l, _)| l))?;
3015 sel.order_by = Some((e, desc));
3016 }
3017 // The context reversed: every term of the
3018 // plan's order turned, the keys too.
3019 "reverse" if self.strict => {
3020 if self.order.reversed
3021 || self.order.limit.is_some()
3022 || self.order.groups
3023 || self.aggregate
3024 || grouped.is_some()
3025 {
3026 return Err(not_pushed(
3027 Refusal::Sort,
3028 "reverse after a positional selection, a fold or another \
3029 reverse"
3030 .into(),
3031 ));
3032 }
3033 self.order.reversed = true;
3034 }
3035 "reverse" => match &mut sel.order_by {
3036 Some((_, desc)) => *desc = true,
3037 None => {
3038 return Err(not_pushed(
3039 Refusal::Sort,
3040 "reverse without an ORDER BY (rows are unordered)".into(),
3041 ));
3042 }
3043 },
3044 // `top(k; ::n)` and `bottom(k; ::n)` in a plan:
3045 // the rows whose key is not null, by the key
3046 // descending or ascending, the ties in the
3047 // table's order, and the first k of them. A
3048 // sort and a cut, so the sort's conditions:
3049 // one numeric column of the table, nothing
3050 // ordered or cut before.
3051 "top" | "bottom" if self.strict => {
3052 let kids = self.arbor.children(s);
3053 let count = kids.first().and_then(|&k| {
3054 (self.kind(k) == "literal")
3055 .then(|| self.prop(k, "value"))
3056 .flatten()
3057 });
3058 let column = kids.get(1).and_then(|&k| self.column_operand(k));
3059 let plain = kids.len() == 2
3060 && join.is_none()
3061 && self.order.sort.is_none()
3062 && self.order.limit.is_none()
3063 && !self.order.reversed
3064 && !self.order.groups
3065 && !self.aggregate
3066 && grouped.is_none();
3067 let (Some(Value::Int(k)), Some(column), true) = (count, column, plain)
3068 else {
3069 return Err(not_pushed(
3070 Refusal::Sort,
3071 "'top' and 'bottom' by anything but one column of the \
3072 table, under an option, over a join, or after a sort, a \
3073 selection or a fold (a plan has one order)"
3074 .into(),
3075 ));
3076 };
3077 if k < 1 {
3078 return Err(not_pushed(
3079 Refusal::Sort,
3080 "'top' and 'bottom' of no rows".into(),
3081 ));
3082 }
3083 let e = self.operand(kids[1], None)?;
3084 sel.wheres.push(format!("{e} IS NOT NULL"));
3085 self.assume_numeric(Some(column.clone()));
3086 self.order.sort = Some((e, name == "top"));
3087 self.order.limit = Some(k as u64);
3088 self.order.keyed_by = Some((Refusal::Sort, column));
3089 }
3090 "top" => {
3091 if sel.limit.is_some() {
3092 return Err(not_pushed(
3093 Refusal::Sort,
3094 "'top' after a positional selection (SQL orders \
3095 before LIMIT)"
3096 .into(),
3097 ));
3098 }
3099 if sel.order_by.is_some() {
3100 return Err(not_pushed(
3101 Refusal::Sort,
3102 "a second sort (SQL has a single ORDER BY)".into(),
3103 ));
3104 }
3105 let kids = self.arbor.children(s);
3106 // the options name the engine's collation
3107 // and its case order: no backend's (they
3108 // were dropped, and the SQL ordered as the
3109 // backend pleased)
3110 if let Some(&k) = kids
3111 .get(2..)
3112 .and_then(|rest| rest.iter().find(|&&k| self.kind(k) == "option"))
3113 {
3114 return Err(mismatch(
3115 Refusal::Sort,
3116 format!(
3117 "top({}) names the engine's collation; a backend's differs",
3118 self.prop_s(k, "name")
3119 ),
3120 ));
3121 }
3122 let n = self.prop_s(kids[0], "value");
3123 let e = self.operand(kids[1], join.map(|(l, _)| l))?;
3124 sel.order_by = Some((e, true));
3125 sel.limit = Some(n);
3126 }
3127 "unique" => {
3128 if self.strict {
3129 // A count of the distinct values asks
3130 // for no order: `| ::n @| unique @|
3131 // count`, the last two commands of the
3132 // pipeline. COUNT(DISTINCT n) leaves
3133 // the NULLs out, and a null is one
3134 // value to `unique`: the plan adds it.
3135 // The column is a numeric one: two
3136 // texts that read as one number
3137 // ('300', '300.0') are one value to
3138 // the engine and two to DISTINCT.
3139 let counted = self.arbor.children(s).is_empty()
3140 && i + 2 == commands.len()
3141 && commands.get(i + 1).is_some_and(|&c| {
3142 self.kind(c) == "agg"
3143 && self.prop_s(c, "name") == "count"
3144 && self.prop(c, "group").is_none()
3145 && self.arbor.children(c).is_empty()
3146 });
3147 match (counted, pending_col.take(), pending_name.take()) {
3148 (true, Some(col), Some(name)) => {
3149 self.assume_numeric(Some(name.clone()));
3150 self.order.keyed_by = Some((Refusal::Unique, name));
3151 sel.select = vec![format!(
3152 "COUNT(DISTINCT {col}) + COALESCE(MAX(CASE WHEN \
3153 {col} IS NULL THEN 1 ELSE 0 END), 0)"
3154 )];
3155 self.aggregate = true;
3156 // the count is taken with it
3157 i += 2;
3158 continue;
3159 }
3160 _ => {
3161 return Err(not_pushed(
3162 Refusal::Unique,
3163 "DISTINCT returns rows in no stated order (a count \
3164 of the distinct values of a numeric column is \
3165 pushed: '| ::col @| unique @| count')"
3166 .into(),
3167 ));
3168 }
3169 }
3170 }
3171 // Quarb dedups the limited rows; SQL
3172 // applies DISTINCT before LIMIT.
3173 if sel.limit.is_some() {
3174 return Err(not_pushed(
3175 Refusal::Unique,
3176 "'unique' after a positional selection (SQL applies \
3177 DISTINCT before LIMIT)"
3178 .into(),
3179 ));
3180 }
3181 if let Some(c) = pending_col.take() {
3182 sel.select = vec![c];
3183 }
3184 sel.distinct = true;
3185 }
3186 other => {
3187 return Err(not_pushed(
3188 Refusal::Reducer,
3189 format!("the '{other}' aggregate"),
3190 ));
3191 }
3192 }
3193 }
3194 // `@| [..n]` in a plan: the first rows of the order the
3195 // driver writes (the plan's own sort, then the keys),
3196 // so the rows the scan's context begins with.
3197 "select" if self.strict => {
3198 if self.order.limit.is_some()
3199 || self.order.groups
3200 || self.aggregate
3201 || grouped.is_some()
3202 || pushed_key.is_some()
3203 {
3204 return Err(not_pushed(
3205 Refusal::Take,
3206 "a positional selection after a reducer, a fold or another \
3207 selection"
3208 .into(),
3209 ));
3210 }
3211 let p = self.arbor.children(s)[0];
3212 match (self.prop_s(p, "kind").as_str(), self.prop(p, "to")) {
3213 ("range", Some(Value::Int(n)))
3214 if self.prop(p, "from").is_none() && n > 0 =>
3215 {
3216 self.order.limit = Some(n as u64);
3217 }
3218 _ => {
3219 return Err(not_pushed(
3220 Refusal::Take,
3221 "positional selection beyond '@| [..n]'".into(),
3222 ));
3223 }
3224 }
3225 }
3226 "select" => {
3227 // `@| [..n]` → LIMIT.
3228 if sel.limit.is_some() {
3229 return Err(not_pushed(
3230 Refusal::Take,
3231 "a second positional selection".into(),
3232 ));
3233 }
3234 let p = self.arbor.children(s)[0];
3235 match (self.prop_s(p, "kind").as_str(), self.prop(p, "to")) {
3236 ("range", Some(Value::Int(n)))
3237 if self.prop(p, "from").is_none() && n > 0 =>
3238 {
3239 sel.limit = Some(n.to_string());
3240 }
3241 _ => {
3242 return Err(not_pushed(
3243 Refusal::Take,
3244 "positional selection beyond '@| [..n]'".into(),
3245 ));
3246 }
3247 }
3248 }
3249 other => {
3250 return Err(not_pushed(
3251 Refusal::Operator,
3252 format!(
3253 "the '{other}' command (windows, subcontexts, and registers are \
3254 Quarb-side state)"
3255 ),
3256 ));
3257 }
3258 }
3259 i += 1;
3260 }
3261 // A pending column with no aggregate is a one-column select.
3262 if let Some(c) = pending_col
3263 && sel.select.is_empty()
3264 {
3265 sel.select = vec![c];
3266 }
3267 // A plan answers row nodes as their rows, where the scan
3268 // answers the nodes: a sorted, reversed or cut selection of
3269 // nodes was the scan's to answer, and stays so; with a
3270 // projection or a record after it, it is the plan's.
3271 if self.strict
3272 && sel.select.is_empty()
3273 && (self.order.sort.is_some() || self.order.reversed || self.order.limit.is_some())
3274 {
3275 let word = if self.order.limit.is_some() {
3276 Refusal::Take
3277 } else {
3278 Refusal::Sort
3279 };
3280 return Err(not_pushed(
3281 word,
3282 "a sorted, reversed or cut selection of row nodes (project a column or build \
3283 a record after it: '| ::col', '| %(…)')"
3284 .into(),
3285 ));
3286 }
3287 // A grouped reduction never recorded (`@|{.k} count` with no
3288 // `| .n | %.`) answers one value per group: the aggregate
3289 // alone, grouped by the key.
3290 if let Some((_, agg, _)) = grouped
3291 && sel.select.is_empty()
3292 {
3293 sel.select = vec![agg];
3294 }
3295 Ok(())
3296 }
3297
3298 /// The column a pushed projection body names — `.k(::k)` is a
3299 /// subcontext whose one branch is the bare projection; any
3300 /// other body is Quarb-side state.
3301 fn pushed_column(&mut self, s: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
3302 let body = || {
3303 let q = self.kid(s, "query")?;
3304 let b = self.kid(q, "branch")?;
3305 let p = self.kid(b, "projection")?;
3306 let bare = self.kids(q, "branch").len() == 1
3307 && self.kids(q, "pipeline").is_empty()
3308 && self.arbor.children(b).len() == 1
3309 && self.prop_s(p, "kind") == "property";
3310 bare.then_some(p)
3311 };
3312 let p = body()
3313 .ok_or_else(|| not_pushed(Refusal::State, "a pushed body (Quarb-side state)".into()))?;
3314 let col = self.projection_col(p)?;
3315 let col = self.sql_ident(&col, "column name")?;
3316 Ok(match qual {
3317 Some(q) => format!("{q}.{col}"),
3318 None => col,
3319 })
3320 }
3321
3322 /// A HAVING filter: `$_` and `$.name` refer to the aggregate.
3323 fn having_cond(&mut self, s: NodeId) -> Result<String, SqlError> {
3324 let kids = self.arbor.children(s);
3325 if kids.len() != 1 || self.kind(kids[0]) != "compare" {
3326 return Err(not_pushed(
3327 Refusal::Fold,
3328 "HAVING translates for a single comparison".into(),
3329 ));
3330 }
3331 let e = kids[0];
3332 let op = self.prop_s(e, "op");
3333 let cmp_kids = self.arbor.children(e);
3334 let l = match self.kind(cmp_kids[0]).as_str() {
3335 "topic" | "recall" => "__AGG__".to_string(),
3336 _ => {
3337 return Err(not_pushed(
3338 Refusal::Fold,
3339 "HAVING compares the aggregate ($_ or its register)".into(),
3340 ));
3341 }
3342 };
3343 let r = self.operand(cmp_kids[1], None)?;
3344 Ok(format!("{l} {op} {r}"))
3345 }
3346
3347 /// `rec(...)` fields as a select list.
3348 fn record_fields(
3349 &mut self,
3350 s: NodeId,
3351 join: Option<(&str, &str)>,
3352 ) -> Result<Vec<String>, SqlError> {
3353 let kids = self.arbor.children(s);
3354 let mut fields = Vec::new();
3355 let mut i = 0;
3356 while i < kids.len() {
3357 let k = kids[i];
3358 if self.kind(k) == "literal" {
3359 let name = self.prop_s(k, "value");
3360 let value = self.operand(kids[i + 1], join.map(|(l, _)| l))?;
3361 let name = self.alias(&name)?;
3362 fields.push(format!("{value} AS {name}"));
3363 i += 2;
3364 } else {
3365 let value = self.operand(k, join.map(|(l, _)| l))?;
3366 fields.push(value);
3367 i += 1;
3368 }
3369 }
3370 Ok(fields)
3371 }
3372}
3373
3374impl Exporter {
3375 /// What a reducer's own arguments ask of the plan. A pushed
3376 /// reducer is the bare command: `count` is COUNT(*), `sum` is
3377 /// SUM(col). `count(--values)` counts the values other than
3378 /// null, which over a projected column is what COUNT(col)
3379 /// counts.
3380 /// Any other option, and any operand, changes what is reduced
3381 /// (`--nulls`, `--of=`, `--by=`), and the reducer stays with the
3382 /// engine. The plan took no notice of them until 0.68:
3383 /// `count(--values)` and `count(--nulls)` were both answered as
3384 /// COUNT(*), where the scan counts five and one of six.
3385 fn reducer_counts_values(
3386 &self,
3387 s: NodeId,
3388 name: &str,
3389 projected: bool,
3390 ) -> Result<bool, SqlError> {
3391 let mut values = false;
3392 for k in self.arbor.children(s) {
3393 if self.kind(k) != "option" {
3394 return Err(not_pushed(
3395 Refusal::Reducer,
3396 format!("an operand of '{name}'"),
3397 ));
3398 }
3399 match (name, self.prop_s(k, "name").as_str()) {
3400 ("count", "--values" | "-v") => values = true,
3401 (_, option) => {
3402 return Err(not_pushed(
3403 Refusal::Reducer,
3404 format!("the '{option}' option of '{name}'"),
3405 ));
3406 }
3407 }
3408 }
3409 // a row node is no value: what the count answers there is
3410 // the engine's to say
3411 if values && !projected {
3412 return Err(not_pushed(
3413 Refusal::Reducer,
3414 "'count(--values)' over row nodes (project a column: '/table/*::col @| \
3415 count(--values)')"
3416 .into(),
3417 ));
3418 }
3419 Ok(values)
3420 }
3421}
3422
3423fn sql_agg(name: &str, col: Option<String>) -> Result<String, SqlError> {
3424 let f = match name {
3425 "count" => "COUNT",
3426 "sum" => "SUM",
3427 "mean" => "AVG",
3428 "min" => "MIN",
3429 "max" => "MAX",
3430 _ => unreachable!("checked by caller"),
3431 };
3432 match col {
3433 Some(c) => Ok(format!("{f}({c})")),
3434 // Only COUNT aggregates bare rows; SUM(*) and friends are
3435 // not SQL.
3436 None if f == "COUNT" => Ok("COUNT(*)".to_string()),
3437 None => Err(not_pushed(
3438 Refusal::Reducer,
3439 format!("'{name}' over row nodes (project a column: '/table/*::col @| {name}')"),
3440 )),
3441 }
3442}
3443
3444#[cfg(test)]
3445mod null_and_literal_tests {
3446 use super::{Dialect, export, partial_pushdown, pushdown};
3447
3448 // Grouped pipeline that never pushes, so `partial_pushdown` hinges
3449 // only on the leading predicate (mirrors the crate's partial gate).
3450 const GROUPED: &str = " | ::x | .g(::x) @|{.g} count | .n | %.";
3451
3452 #[test]
3453 fn pattern_literal_pushes_as_like() {
3454 // Ruling #33: segments in order, a `%` per star, LIKE's
3455 // metacharacters escaped. Strict push only where LIKE is
3456 // provably case-sensitive (PostgreSQL); everywhere else the
3457 // pattern rides the scan.
3458 let q = "/users/*[::name == 'app-'*]::id";
3459 let p = pushdown(q, Some(Dialect::Postgres)).unwrap();
3460 assert_eq!(
3461 p.sql,
3462 "SELECT id FROM users WHERE name LIKE 'app-%' ESCAPE '\\'"
3463 );
3464 assert!(pushdown(q, Some(Dialect::Sqlite)).is_none());
3465 assert!(pushdown(q, Some(Dialect::MySql)).is_none());
3466 // contains and multi-segment shapes
3467 let p = pushdown("/users/*[::name == *'web'*]::id", Some(Dialect::Postgres)).unwrap();
3468 assert!(p.sql.contains("LIKE '%web%'"), "{}", p.sql);
3469 let p = pushdown(
3470 "/users/*[::name == *'a'*'.gz']::id",
3471 Some(Dialect::Postgres),
3472 )
3473 .unwrap();
3474 assert!(p.sql.contains("LIKE '%a%.gz'"), "{}", p.sql);
3475 // LIKE metacharacters in a segment are escaped
3476 let p = pushdown("/users/*[::name == *'50%_x'*]::id", Some(Dialect::Postgres)).unwrap();
3477 assert!(p.sql.contains("LIKE '%50\\%\\_x%'"), "{}", p.sql);
3478 // `!=` with a pattern rides the scan
3479 assert!(pushdown("/users/*[::name !== *'web'*]::id", Some(Dialect::Postgres)).is_none());
3480 // the `*=` alias gains the same PostgreSQL rung
3481 let p = pushdown("/users/*[::name *= 'web']::id", Some(Dialect::Postgres)).unwrap();
3482 assert!(p.sql.contains("LIKE '%web%'"), "{}", p.sql);
3483 // and on SQLite it is instr, a substring test by bytes and by
3484 // case as `*=` is; MySQL's INSTR folds case, and scans
3485 assert_eq!(
3486 pushdown("/users/*[::name *= 'web']::id", Some(Dialect::Sqlite))
3487 .unwrap()
3488 .sql,
3489 "SELECT id FROM users WHERE instr(name, 'web') > 0"
3490 );
3491 assert!(pushdown("/users/*[::name *= 'web']::id", Some(Dialect::MySql)).is_none());
3492 assert!(pushdown("/users/*[::name *= 'web']::id", None).is_none());
3493 }
3494
3495 #[test]
3496 fn json_column_path_pushdown_per_dialect() {
3497 // `[/col/a/b:: = 'lit']` navigates into a JSON column; each
3498 // dialect extracts the fixed path to text and compares.
3499 // Verified live against all five engines to match the graft.
3500 let q = "/orders/*[/data/meta/tier:: = 'gold']::id";
3501 let sql = |d| pushdown(q, Some(d)).unwrap().sql;
3502 assert_eq!(
3503 sql(Dialect::Postgres),
3504 "SELECT id FROM orders WHERE ((data::jsonb #>> '{meta,tier}') = 'gold')"
3505 );
3506 assert_eq!(
3507 sql(Dialect::MySql),
3508 "SELECT id FROM orders WHERE (JSON_VALID(data) AND \
3509 JSON_UNQUOTE(JSON_EXTRACT(data, '$.meta.tier')) = 'gold')"
3510 );
3511 assert_eq!(
3512 sql(Dialect::Sqlite),
3513 "SELECT id FROM orders WHERE (json_valid(data) AND \
3514 json_extract(data, '$.meta.tier') = 'gold')"
3515 );
3516 assert_eq!(
3517 sql(Dialect::Mssql),
3518 "SELECT id FROM orders WHERE (ISJSON(data) = 1 AND \
3519 JSON_VALUE(data, '$.meta.tier') = 'gold')"
3520 );
3521 assert_eq!(
3522 sql(Dialect::Oracle),
3523 "SELECT id FROM orders WHERE (JSON_VALUE(data, '$.meta.tier') = 'gold')"
3524 );
3525 // With no dialect, the JSON navigation is not pushable — it
3526 // falls back to the client-side graft.
3527 assert!(pushdown(q, None).is_none());
3528 }
3529
3530 #[test]
3531 fn json_pushdown_only_string_equality() {
3532 // Numeric comparison, `!=`, and a wildcard step stay off the
3533 // pushdown path (they are not provably identical to the
3534 // graft), so they refuse and scan even with a dialect set.
3535 let d = Some(Dialect::Sqlite);
3536 assert!(pushdown("/o/*[/data/n:: > 2]::id", d).is_none());
3537 assert!(pushdown("/o/*[/data/tier:: != 'gold']::id", d).is_none());
3538 assert!(pushdown("/o/*[/data/items/*/sku:: = 'A1']::id", d).is_none());
3539 }
3540
3541 #[test]
3542 fn json_pushdown_refuses_numeric_looking_literal() {
3543 // value_eq coerces numeric-looking strings ('150' matches
3544 // the JSON number 150 and the string "150.0"); no engine's
3545 // extractor does, so the push would drop rows.
3546 let q = "/orders/*[/data/total:: = '150']::id";
3547 assert!(pushdown(q, Some(Dialect::Sqlite)).is_none());
3548 assert!(pushdown(q, Some(Dialect::Postgres)).is_none());
3549 }
3550
3551 #[test]
3552 fn a_regex_names_the_literals_it_cannot_match_without() {
3553 let lits = |p: &str| super::required_literals(p);
3554 assert_eq!(lits("^Ma.*s$"), ["Ma", "s"]);
3555 assert_eq!(lits("(us)+$"), ["us"]);
3556 assert_eq!(lits("a?b"), ["b"]);
3557 assert_eq!(lits("(?:foo|bar)baz"), ["baz"]);
3558 assert_eq!(lits("fo{2,}"), ["f", "o"]);
3559 assert_eq!(lits(r"\d+-\d+"), ["-"]);
3560 assert_eq!(lits(r"\bfoo\b"), ["foo"]);
3561 assert_eq!(lits(r"No\.1"), ["No.1"]);
3562 assert_eq!(lits("na\u{ef}ve"), ["na\u{ef}ve"]);
3563 assert_eq!(lits("(?x) a b"), ["ab"]);
3564 assert_eq!(lits("(a|b)c*d"), ["d"]);
3565 assert_eq!(lits("x{0}y"), ["y"]);
3566 assert_eq!(lits("ab(ab)"), ["ab"]);
3567 // nothing promised: a class, an alternation, an optional
3568 // part, a letter under (?i), a pattern that does not parse
3569 for p in ["(?i)ma", "Ven|Jup", "a*", "[ab]", "(ab)?", ".*", "", "["] {
3570 assert!(lits(p).is_empty(), "{p}");
3571 }
3572 }
3573
3574 #[test]
3575 fn a_regex_is_narrowed_by_its_literals() {
3576 let part = |q: &str, d: Dialect| {
3577 partial_pushdown(q, Some(d)).map(|p| (p.where_sql, p.column_types.text))
3578 };
3579 assert_eq!(
3580 part("/t/*[::a == (/^Ma.*s$/)]::b", Dialect::Sqlite),
3581 Some((
3582 "instr(a, 'Ma') > 0 AND instr(a, 's') > 0".to_string(),
3583 vec!["a".to_string()]
3584 ))
3585 );
3586 assert_eq!(
3587 part("/t/*[::a == (/50%_off/)]::b", Dialect::Postgres).map(|p| p.0),
3588 Some(r"a LIKE '%50\%\_off%' ESCAPE '\'".to_string())
3589 );
3590 // a conjunction keeps the side that translates; a
3591 // disjunction needs both
3592 assert_eq!(
3593 part("/t/*[::n > 2 && ::a == (/on/)]::b", Dialect::Sqlite).map(|p| p.0),
3594 Some("(n > 2 AND instr(a, 'on') > 0)".to_string())
3595 );
3596 assert_eq!(
3597 part(
3598 "/t/*[::a == (/(?i)x/) && ::a == (/on/)]::b",
3599 Dialect::Sqlite
3600 )
3601 .map(|p| p.0),
3602 Some("(instr(a, 'on') > 0)".to_string())
3603 );
3604 assert_eq!(
3605 part("/t/*[::a == (/Ven/) || ::a == (/Jup/)]::b", Dialect::Sqlite).map(|p| p.0),
3606 Some("(instr(a, 'Ven') > 0 OR instr(a, 'Jup') > 0)".to_string())
3607 );
3608 for q in [
3609 // one side promises nothing: the disjunction is not narrowed
3610 "/t/*[::a == (/Ven/) || ::a == (/(?i)jup/)]::b",
3611 // a negation is never narrowed, nor a non-match
3612 "/t/*[!(::a == (/Ven/))]::b",
3613 "/t/*[::a !== (/Ven/)]::b",
3614 // a literal a SQL string would not carry everywhere
3615 "/t/*[::a == (/it's/)]::b",
3616 // no literal at all
3617 "/t/*[::a == (/(?i)ven/)]::b",
3618 "/t/*[::a == (/Ven|Jup/)]::b",
3619 ] {
3620 assert_eq!(part(q, Dialect::Sqlite), None, "{q}");
3621 }
3622 // no function says "holds, by bytes and case" on MySQL
3623 assert_eq!(part("/t/*[::a == (/Ven/)]::b", Dialect::MySql), None);
3624 }
3625
3626 #[test]
3627 fn partial_json_prefilters_sqlite() {
3628 // Exact string equality rides the strict gate.
3629 let p = partial_pushdown(
3630 "/orders/*[/payload/customer/geo/city:: = 'Lyon']::id",
3631 Some(Dialect::Sqlite),
3632 )
3633 .unwrap();
3634 assert_eq!(p.table, "orders");
3635 assert_eq!(
3636 p.where_sql,
3637 "(json_valid(payload) AND \
3638 json_extract(payload, '$.customer.geo.city') = 'Lyon')"
3639 );
3640 // Numeric comparison: typed compare, text values escape.
3641 let p = partial_pushdown(
3642 "/orders/*[/payload/total:: > 150]::id",
3643 Some(Dialect::Sqlite),
3644 )
3645 .unwrap();
3646 assert_eq!(
3647 p.where_sql,
3648 "(json_valid(payload) AND (json_extract(payload, '$.total') > 150 \
3649 OR json_type(payload, '$.total') = 'text'))"
3650 );
3651 // Bare existence.
3652 let p = partial_pushdown("/orders/*[/payload/gift]::id", Some(Dialect::Sqlite)).unwrap();
3653 assert_eq!(
3654 p.where_sql,
3655 "(json_valid(payload) AND json_type(payload, '$.gift') IS NOT NULL)"
3656 );
3657 // != floors at existence.
3658 let p = partial_pushdown(
3659 "/orders/*[/payload/status:: != 'x']::id",
3660 Some(Dialect::Sqlite),
3661 )
3662 .unwrap();
3663 assert_eq!(
3664 p.where_sql,
3665 "(json_valid(payload) AND json_type(payload, '$.status') IS NOT NULL)"
3666 );
3667 // A flipped literal flips the operator.
3668 let p = partial_pushdown(
3669 "/orders/*[150 < /payload/total::]::id",
3670 Some(Dialect::Sqlite),
3671 )
3672 .unwrap();
3673 assert!(p.where_sql.contains("> 150"), "{}", p.where_sql);
3674 // Without a dialect, JSON predicates stay on the engine.
3675 assert!(partial_pushdown("/orders/*[/payload/gift]::id", None).is_none());
3676 }
3677
3678 #[test]
3679 fn partial_json_prefilters_postgres() {
3680 let p = partial_pushdown(
3681 "/orders/*[/payload/total:: > 150]::id",
3682 Some(Dialect::Postgres),
3683 )
3684 .unwrap();
3685 assert_eq!(
3686 p.where_sql,
3687 "(CASE WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'number' \
3688 THEN ((payload::jsonb #>> '{total}'))::float8 > 150 \
3689 WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'string' \
3690 THEN true ELSE false END)"
3691 );
3692 let p = partial_pushdown("/orders/*[/payload/gift]::id", Some(Dialect::Postgres)).unwrap();
3693 assert_eq!(
3694 p.where_sql,
3695 "(jsonb_typeof(payload::jsonb #> '{gift}') IS NOT NULL)"
3696 );
3697 }
3698
3699 #[test]
3700 fn json_property_path_pushdown() {
3701 // `[/col/a::b = 'lit']`, the property form: the scalar's
3702 // question and, on an array of scalars, the list's (any item
3703 // equals). SQLite's condition says both whole.
3704 let q = "/orders/*[/payload/customer/geo::city = 'Lyon']::id";
3705 assert_eq!(
3706 pushdown(q, Some(Dialect::Sqlite)).unwrap().sql,
3707 "SELECT id FROM orders WHERE (json_valid(payload) AND \
3708 ((json_type(payload, '$.customer.geo.city') = 'text' AND \
3709 json_extract(payload, '$.customer.geo.city') = 'Lyon') OR \
3710 (json_type(payload, '$.customer.geo.city') = 'array' AND \
3711 EXISTS (SELECT 1 FROM json_each(payload, '$.customer.geo.city') \
3712 WHERE json_each.type = 'text' AND json_each.value = 'Lyon') AND \
3713 NOT EXISTS (SELECT 1 FROM json_each(payload, '$.customer.geo.city') \
3714 WHERE json_each.type IN ('array', 'object')))))"
3715 );
3716 // a property of the column's own value
3717 assert!(
3718 pushdown(
3719 "/orders/*[/payload::city = 'Lyon']::id",
3720 Some(Dialect::Sqlite)
3721 )
3722 .unwrap()
3723 .sql
3724 .contains("json_extract(payload, '$.city') = 'Lyon'")
3725 );
3726 // the other engines' array branches are not verified: no
3727 // whole push there, and none with no dialect
3728 for d in [
3729 Dialect::Postgres,
3730 Dialect::MySql,
3731 Dialect::Mssql,
3732 Dialect::Oracle,
3733 ] {
3734 assert!(pushdown(q, Some(d)).is_none(), "{d:?}");
3735 }
3736 assert!(pushdown(q, None).is_none());
3737 // a numeric-looking literal compares by value: no whole push
3738 assert!(
3739 pushdown(
3740 "/orders/*[/payload::total = '150']::id",
3741 Some(Dialect::Sqlite)
3742 )
3743 .is_none()
3744 );
3745 // a column named as one of json_each's own columns would be
3746 // read as that column inside the subquery
3747 assert!(
3748 pushdown(
3749 "/orders/*[/value::city = 'Lyon']::id",
3750 Some(Dialect::Sqlite)
3751 )
3752 .is_none()
3753 );
3754 }
3755
3756 #[test]
3757 fn partial_json_property_prefilters() {
3758 let sqlite = |q: &str| partial_pushdown(q, Some(Dialect::Sqlite)).map(|p| p.where_sql);
3759 // a comparison lets the arrays through with the text values:
3760 // a list matches when any item does, and the engine decides
3761 assert_eq!(
3762 sqlite("/orders/*[/payload::total > 150]::id").unwrap(),
3763 "(json_valid(payload) AND (json_extract(payload, '$.total') > 150 \
3764 OR json_type(payload, '$.total') IN ('text', 'array')))"
3765 );
3766 assert_eq!(
3767 sqlite("/orders/*[/payload/customer::tier < 'm']::id").unwrap(),
3768 "(json_valid(payload) AND (json_extract(payload, '$.customer.tier') < 'm' \
3769 OR json_type(payload, '$.customer.tier') = 'array'))"
3770 );
3771 // a bare property: present, as the child form
3772 assert_eq!(
3773 sqlite("/orders/*[/payload::gift]::id").unwrap(),
3774 "(json_valid(payload) AND json_type(payload, '$.gift') IS NOT NULL)"
3775 );
3776 // `!=` keeps a row whose key is absent: its floor is the node
3777 // the property is read on, and on the column itself there is
3778 // none
3779 assert_eq!(
3780 sqlite("/orders/*[/payload/customer::tier != 'x']::id").unwrap(),
3781 "(json_valid(payload) AND json_type(payload, '$.customer') IS NOT NULL)"
3782 );
3783 assert!(sqlite("/orders/*[/payload::status != 'x']::id").is_none());
3784 // PostgreSQL: the equality as a prefilter, the arrays through
3785 assert_eq!(
3786 partial_pushdown(
3787 "/orders/*[/payload/customer/geo::city = 'Lyon']::id",
3788 Some(Dialect::Postgres)
3789 )
3790 .unwrap()
3791 .where_sql,
3792 "(CASE WHEN jsonb_typeof(payload::jsonb #> '{customer,geo,city}') = 'string' \
3793 THEN (payload::jsonb #>> '{customer,geo,city}') = 'Lyon' \
3794 WHEN jsonb_typeof(payload::jsonb #> '{customer,geo,city}') = 'array' \
3795 THEN true ELSE false END)"
3796 );
3797 assert_eq!(
3798 partial_pushdown(
3799 "/orders/*[/payload::total > 150]::id",
3800 Some(Dialect::Postgres)
3801 )
3802 .unwrap()
3803 .where_sql,
3804 "(CASE WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'number' \
3805 THEN ((payload::jsonb #>> '{total}'))::float8 > 150 \
3806 WHEN jsonb_typeof(payload::jsonb #> '{total}') IN ('string', 'array') \
3807 THEN true ELSE false END)"
3808 );
3809 // no type probe, no prefilter
3810 assert!(
3811 partial_pushdown("/orders/*[/payload::total > 150]::id", Some(Dialect::MySql))
3812 .is_none()
3813 );
3814 }
3815
3816 #[test]
3817 fn json_pushdown_refuses_a_container_looking_literal() {
3818 // An extractor answers an array or an object as its JSON
3819 // text, so `'[1,2]'` equalled the array itself, which has no
3820 // value in the graft: the whole push kept a row the scan
3821 // drops. It rides the prefilter (a superset, re-checked).
3822 for q in [
3823 "/orders/*[/data/a:: = '[1,2]']::id",
3824 "/orders/*[/data/a:: = '{\"k\":1}']::id",
3825 ] {
3826 assert!(pushdown(q, Some(Dialect::Sqlite)).is_none(), "{q}");
3827 assert!(pushdown(q, Some(Dialect::Postgres)).is_none(), "{q}");
3828 }
3829 assert_eq!(
3830 partial_pushdown("/orders/*[/data/a:: = '[1,2]']::id", Some(Dialect::Sqlite))
3831 .unwrap()
3832 .where_sql,
3833 "(json_valid(data) AND json_extract(data, '$.a') = '[1,2]')"
3834 );
3835 }
3836
3837 #[test]
3838 fn partial_skips_untranslatable_keeps_prefix() {
3839 // A refused predicate no prefilter covers is skipped — the
3840 // shorter conjunction is still a superset (the engine
3841 // re-applies the original) — rather than aborting the plan.
3842 let p = partial_pushdown(
3843 "/orders/*[::status = 'shipped'][/payload/line_items/*/sku:: = 'X']::id",
3844 Some(Dialect::Sqlite),
3845 )
3846 .unwrap();
3847 assert_eq!(p.where_sql, "status = 'shipped'");
3848 }
3849
3850 #[test]
3851 fn null_literal_compares_use_is_null() {
3852 // `= null` / `!= null` are provably identical to Quarb's
3853 // value_eq(NULL, …) semantics, never the always-UNKNOWN
3854 // `x = NULL`; they translate — and push — in both modes.
3855 assert_eq!(
3856 export("/t/*[::x = null] | ::x").unwrap().query,
3857 "SELECT x FROM t WHERE x IS NULL"
3858 );
3859 assert_eq!(
3860 export("/t/*[::x != null] | ::x").unwrap().query,
3861 "SELECT x FROM t WHERE x IS NOT NULL"
3862 );
3863 assert_eq!(
3864 pushdown("/t/*[::x = null] | ::x", None).unwrap().sql,
3865 "SELECT x FROM t WHERE x IS NULL"
3866 );
3867 assert_eq!(
3868 pushdown("/t/*[::x != null] | ::x", None).unwrap().sql,
3869 "SELECT x FROM t WHERE x IS NOT NULL"
3870 );
3871 }
3872
3873 #[test]
3874 fn ne_and_not_push_in_the_form_that_keeps_the_null_rows() {
3875 // `!=` against a value and `!(...)` hold for a NULL in Quarb
3876 // and are UNKNOWN in SQL. The plan says the cases SQL's
3877 // operators leave out, in SQL every engine reads (the scan's
3878 // answers beside the plan's: tests/sql.rs).
3879 assert_eq!(
3880 pushdown("/t/*[::x != 5] | ::x", None).unwrap().sql,
3881 "SELECT x FROM t WHERE (x <> 5 OR x IS NULL)"
3882 );
3883 assert_eq!(
3884 pushdown("/t/*[::x != ::y] | ::x", None).unwrap().sql,
3885 "SELECT x FROM t WHERE (x <> y OR (x IS NULL AND y IS NOT NULL) OR (x IS NOT NULL \
3886 AND y IS NULL))"
3887 );
3888 assert_eq!(
3889 pushdown("/t/*[!::x = 5] | ::x", None).unwrap().sql,
3890 "SELECT x FROM t WHERE (CASE WHEN x = 5 THEN 0 ELSE 1 END = 1)"
3891 );
3892 // two NULLs are equal in Quarb: an equality of two columns
3893 // says so
3894 assert_eq!(
3895 pushdown("/t/*[::x = ::y] | ::x", None).unwrap().sql,
3896 "SELECT x FROM t WHERE (x = y OR (x IS NULL AND y IS NULL))"
3897 );
3898 // the prefilter takes them too
3899 assert_eq!(
3900 partial_pushdown(&format!("/t/*[::x != 5]{GROUPED}"), None)
3901 .unwrap()
3902 .where_sql,
3903 "(x <> 5 OR x IS NULL)"
3904 );
3905 // The display translation still emits `<>`, flagged with a note.
3906 let t = export("/t/*[::x != 5] | ::x").unwrap();
3907 assert_eq!(t.query, "SELECT x FROM t WHERE x <> 5");
3908 assert!(t.notes.iter().any(|n| n.contains("NULL")));
3909 }
3910
3911 #[test]
3912 fn unescapable_text_literal_refuses_pushdown() {
3913 // A backslash (MySQL/BigQuery escape) or an apostrophe
3914 // (BigQuery rejects '' doubling) has no portable escaping, so
3915 // pushdown refuses; a clean literal still pushes.
3916 assert!(pushdown("/files/*[::path = \"C:\\temp\"] | ::path", None).is_none());
3917 assert!(pushdown("/t/*[::name = \"it's\"] | ::name", None).is_none());
3918 assert!(partial_pushdown(&format!("/t/*[::name = \"it's\"]{GROUPED}"), None).is_none());
3919 assert_eq!(
3920 pushdown("/t/*[::name = \"rare\"] | ::name", None)
3921 .unwrap()
3922 .sql,
3923 "SELECT name FROM t WHERE name = 'rare'"
3924 );
3925 }
3926}