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::{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 aggregate: false,
55 keyed_hops: false,
56 from_marks: Vec::new(),
57 join_marks: Vec::new(),
58 };
59 let query = ex.query()?;
60 Ok(Translation {
61 query,
62 notes: ex.notes,
63 })
64}
65
66/// The exporter rewrites `__LEFT__` (the join's left table) and
67/// `__AGG__` (the HAVING aggregate) as internal placeholders.
68/// Query text containing either marker would be rewritten inside
69/// its own string literals — and could spoof the emitted SQL — so
70/// such queries stay on the scan path.
71fn refuse_marker(quarb: &str) -> Result<(), SqlError> {
72 for marker in ["__LEFT__", "__AGG__"] {
73 if quarb.contains(marker) {
74 return Err(SqlError::Unsupported(format!(
75 "query text contains the reserved marker \"{marker}\""
76 )));
77 }
78 }
79 Ok(())
80}
81
82/// A pushdown plan: SQL whose execution is provably identical to
83/// the Quarb query's — plus the table whose primary key must order
84/// the rows (`None` for a single aggregate row, where order is
85/// moot). The driver appends the `ORDER BY`, since the key lives in
86/// its catalog.
87pub struct Pushdown {
88 pub sql: String,
89 pub order_table: Option<String>,
90 /// Present when the plan contains a witness JOIN: the joined
91 /// table and the columns its ON equalities bind on it
92 /// (collected structurally from the arbor, so query text
93 /// cannot spoof them).
94 /// The plan is only sound if those columns form a unique key
95 /// of the joined table — each FROM row must find at most one
96 /// witness, else SQL multiplies rows where Quarb's existential
97 /// binding does not. The *driver* must verify against its
98 /// catalog before executing, and fall back to the scan if it
99 /// cannot.
100 pub join_left: Option<(String, Vec<String>)>,
101 /// Present when the plan is an every-witness JOIN (`<=>*`,
102 /// ruling 2026-11-11): the joined table. Such a JOIN is what the
103 /// query asks, so it carries no uniqueness obligation
104 /// (`join_left` is absent); its obligation is the ORDER: the
105 /// rows of one driver stand in the joined table's own order,
106 /// after the driver's (`order_table`'s key, then this table's).
107 /// A driver that cannot order by both must decline the plan.
108 pub order_then: Option<String>,
109 /// What the plan takes for granted about column types. Quarb
110 /// compares by value (a numeric-looking text and a number meet
111 /// as numbers, a number and other text never meet); SQL
112 /// compares by the column's type, and the loosely typed engines
113 /// (SQLite, MySQL) coerce by rules of their own. The plan is
114 /// the scan's only where the columns it compares with a number
115 /// are numeric-typed and those it compares with text are not:
116 /// the caller asks its catalog and scans when one is otherwise.
117 /// (A strictly typed engine rejects the mismatch itself, which
118 /// sends the caller to the scan as well.)
119 pub column_types: ColumnTypes,
120 /// The tables the plan reads (the FROM table, then a joined one).
121 pub tables: Vec<String>,
122}
123
124/// The column types a pushed plan assumes (see
125/// [`Pushdown::column_types`]).
126#[derive(Clone, Debug, Default, PartialEq, Eq)]
127pub struct ColumnTypes {
128 /// Columns compared with a numeric literal.
129 pub numeric: Vec<String>,
130 /// Columns compared with a text literal.
131 pub text: Vec<String>,
132 /// Columns the plan extracts a JSON path from on the strength
133 /// of the column's declaration alone (the hop carried no
134 /// `<json>`): the pushed `json_extract` is the scan's only where
135 /// the catalog declares the column json, since the scan grafts
136 /// a leaf only as declared (spec: Grafting).
137 pub json: Vec<String>,
138}
139
140impl ColumnTypes {
141 pub fn is_empty(&self) -> bool {
142 self.numeric.is_empty() && self.text.is_empty() && self.json.is_empty()
143 }
144
145 /// The assumptions a catalog does not bear out: the columns
146 /// compared with a number that are not numeric-typed, and those
147 /// compared with text that are. `catalog` lists every column of
148 /// the tables read, with whether its type is numeric and
149 /// whether it is declared json; names meet without regard to
150 /// case. A column the catalog does not list is unknown, and
151 /// counts as unmet.
152 pub fn unmet(&self, catalog: &[(String, bool, bool)]) -> Vec<String> {
153 let met = |column: &str, pick: fn(&(String, bool, bool)) -> bool, want: bool| {
154 let mut found = catalog
155 .iter()
156 .filter(|(name, ..)| name.eq_ignore_ascii_case(column))
157 .peekable();
158 found.peek().is_some() && found.all(|entry| pick(entry) == want)
159 };
160 let numeric = |e: &(String, bool, bool)| e.1;
161 let json = |e: &(String, bool, bool)| e.2;
162 let mut out: Vec<String> = Vec::new();
163 for (columns, pick, want) in [
164 (
165 &self.numeric,
166 numeric as fn(&(String, bool, bool)) -> bool,
167 true,
168 ),
169 (&self.text, numeric, false),
170 (&self.json, json, true),
171 ] {
172 for c in columns {
173 if !met(c, pick, want) && !out.contains(c) {
174 out.push(c.clone());
175 }
176 }
177 }
178 out
179 }
180}
181
182/// The target SQL dialect, for the one construct whose emitted
183/// SQL is not portable: a filter that navigates *into* a JSON
184/// column, which each engine extracts with its own operator.
185/// The rest of a pushdown is dialect-agnostic. A query with no
186/// JSON-column filter emits identical SQL regardless of dialect.
187#[derive(Clone, Copy, PartialEq, Eq, Debug)]
188pub enum Dialect {
189 Postgres,
190 MySql,
191 Sqlite,
192 Mssql,
193 Oracle,
194}
195
196/// Attempt the pushdown translation: `Some` only when every
197/// construct in the query is in the verified-safe set. Anything
198/// else — including everything `export` would merely annotate with
199/// a divergence note — returns `None`, and the caller scans.
200///
201/// `dialect` enables JSON-column-path pushdown for that engine
202/// (fixed-path string equality only); `None` keeps such filters
203/// on the client-side graft.
204pub fn pushdown(quarb: &str, dialect: Option<Dialect>) -> Option<Pushdown> {
205 pushdown_explained(quarb, dialect).ok()
206}
207
208/// [`pushdown`], keeping the refusal: the error names the first
209/// construct that kept the query on the scan path.
210pub fn pushdown_explained(quarb: &str, dialect: Option<Dialect>) -> Result<Pushdown, SqlError> {
211 refuse_marker(quarb)?;
212 let arbor =
213 QueryArbor::parse(quarb).map_err(|e| SqlError::Syntax(format!("parsing Quarb: {e}")))?;
214 refuse_groups(&arbor)?;
215 let mut ex = Exporter {
216 arbor,
217 notes: Vec::new(),
218 strict: true,
219 dialect,
220 from_table: String::new(),
221 join_on_cols: Vec::new(),
222 join_table: None,
223 join_every: false,
224 column_types: ColumnTypes::default(),
225 from_sql: String::new(),
226 join_sql: None,
227 in_on: false,
228 aggregate: false,
229 keyed_hops: false,
230 from_marks: Vec::new(),
231 join_marks: Vec::new(),
232 };
233 let sql = ex.query()?;
234 let order_table = if ex.aggregate {
235 None
236 } else {
237 // Rows come back in the driver's document order — the FROM
238 // table's (driver-first correlation).
239 Some(ex.from_table.clone())
240 };
241 // an every-witness JOIN multiplies rows by design: no uniqueness
242 // to verify, the joined table's order to keep instead
243 let join_left = if ex.join_every {
244 None
245 } else {
246 ex.join_table.clone().map(|t| (t, ex.join_on_cols.clone()))
247 };
248 let order_then = if ex.join_every && !ex.aggregate {
249 ex.join_table.clone()
250 } else {
251 None
252 };
253 let mut tables = vec![ex.from_table.clone()];
254 tables.extend(ex.join_table.clone());
255 Ok(Pushdown {
256 sql,
257 order_table,
258 join_left,
259 order_then,
260 column_types: ex.column_types.clone(),
261 tables,
262 })
263}
264
265/// The dialect-specific SQL that extracts a JSON scalar at a
266/// fixed object path, unquoted to text. `path` holds plain
267/// object keys (identifier-safe, per `json_path`), so no
268/// per-dialect path-escaping is needed. Each engine's operator
269/// returns the value as text and yields NULL for an absent path
270/// or a non-scalar — matching the graft, which excludes those
271/// rows too.
272fn json_extract(dialect: Dialect, qual: Option<&str>, col: &str, path: &[String]) -> String {
273 let qcol = match qual {
274 Some(q) => format!("{q}.{col}"),
275 None => col.to_string(),
276 };
277 match dialect {
278 // `#>>` takes a text-array path and returns text; the
279 // `::jsonb` cast lets it work on json, jsonb, and
280 // text-holding-JSON columns alike (an invalid-JSON row
281 // errors, and the driver falls back to the scan).
282 Dialect::Postgres => format!("({qcol}::jsonb #>> '{{{}}}')", path.join(",")),
283 // JSON_UNQUOTE(JSON_EXTRACT(...)) is the `->>` shorthand
284 // spelled out — portable across MySQL and MariaDB, where
285 // the `->>` operator itself is not.
286 Dialect::MySql => {
287 format!("JSON_UNQUOTE(JSON_EXTRACT({qcol}, '$.{}'))", path.join("."))
288 }
289 Dialect::Sqlite => format!("json_extract({qcol}, '$.{}')", path.join(".")),
290 // JSON_VALUE returns a scalar as text (lax mode: NULL on a
291 // missing path or a non-scalar, no error).
292 Dialect::Mssql | Dialect::Oracle => format!("JSON_VALUE({qcol}, '$.{}')", path.join(".")),
293 }
294}
295
296/// Wrap a JSON-path condition in the dialect's validity guard,
297/// where a cheap one exists. SQLite and MySQL error the whole
298/// statement on one malformed-JSON row — which turned every
299/// pushdown over a dirty table into a silent fallback scan — and
300/// the graft excludes such rows anyway (no parse, no subtree), so
301/// the guard is observationally identical. SQL Server gets ISJSON;
302/// Oracle's JSON_VALUE is lax already; PostgreSQL has no guard
303/// short of the ::jsonb cast itself (an invalid row errors and the
304/// caller falls back to the scan).
305fn json_valid_guard(dialect: Dialect, qual: Option<&str>, col: &str, cond: String) -> String {
306 let qcol = match qual {
307 Some(q) => format!("{q}.{col}"),
308 None => col.to_string(),
309 };
310 match dialect {
311 Dialect::Sqlite => format!("(json_valid({qcol}) AND {cond})"),
312 Dialect::MySql => format!("(JSON_VALID({qcol}) AND {cond})"),
313 Dialect::Mssql => format!("(ISJSON({qcol}) = 1 AND {cond})"),
314 Dialect::Postgres | Dialect::Oracle => format!("({cond})"),
315 }
316}
317
318/// The dialect's JSON type probe at a fixed path — non-NULL iff
319/// the path exists. A JSON `null` value reports its type ('null'),
320/// so existence still sees it, matching the graft, where a
321/// null-valued key is a node. Only the dialects with a native
322/// probe participate.
323fn json_type_probe(
324 dialect: Dialect,
325 qual: Option<&str>,
326 col: &str,
327 path: &[String],
328) -> Option<String> {
329 let qcol = match qual {
330 Some(q) => format!("{q}.{col}"),
331 None => col.to_string(),
332 };
333 match dialect {
334 Dialect::Sqlite => Some(format!("json_type({qcol}, '$.{}')", path.join("."))),
335 Dialect::Postgres => Some(format!(
336 "jsonb_typeof({qcol}::jsonb #> '{{{}}}')",
337 path.join(",")
338 )),
339 Dialect::MySql | Dialect::Mssql | Dialect::Oracle => None,
340 }
341}
342
343/// Flip a comparison for a swapped operand order (`lit OP path` →
344/// `path OP' lit`).
345fn flip_op(op: &str) -> String {
346 match op {
347 "<" => ">".into(),
348 "<=" => ">=".into(),
349 ">" => "<".into(),
350 ">=" => "<=".into(),
351 other => other.into(),
352 }
353}
354
355/// SQL keywords that must not appear as a bare identifier or `AS`
356/// alias — quoting them portably differs by dialect, so strict
357/// mode refuses and export mode quotes with double quotes plus a
358/// note.
359const SQL_KEYWORDS: &[&str] = &[
360 "all",
361 "and",
362 "as",
363 "asc",
364 "by",
365 "case",
366 "cross",
367 "desc",
368 "distinct",
369 "else",
370 "end",
371 "except",
372 "exists",
373 "from",
374 "group",
375 "having",
376 "in",
377 "index",
378 "inner",
379 "intersect",
380 "into",
381 "is",
382 "join",
383 "left",
384 "like",
385 "limit",
386 "not",
387 "null",
388 "offset",
389 "on",
390 "or",
391 "order",
392 "outer",
393 "right",
394 "select",
395 "set",
396 "table",
397 "then",
398 "union",
399 "unique",
400 "update",
401 "using",
402 "values",
403 "when",
404 "where",
405];
406
407/// A bare SQL identifier, portable across the target dialects: a
408/// letter or underscore, then letters, digits, and underscores,
409/// and not a reserved word.
410fn is_plain_ident(name: &str) -> bool {
411 !name.is_empty()
412 && name
413 .chars()
414 .next()
415 .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
416 && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
417 && !SQL_KEYWORDS.contains(&name.to_ascii_lowercase().as_str())
418}
419
420/// The SELECT under construction.
421#[derive(Default)]
422struct Select {
423 select: Vec<String>,
424 distinct: bool,
425 from: String,
426 join: Option<(String, String)>, // (table, ON condition)
427 /// The join keeps every FROM row (`<=>?`, the outer
428 /// correlation): a LEFT JOIN.
429 join_outer: bool,
430 wheres: Vec<String>,
431 group_by: Option<String>,
432 having: Option<String>,
433 order_by: Option<(String, bool)>, // (expr, desc)
434 limit: Option<String>,
435}
436
437impl Select {
438 fn render(&self) -> String {
439 let mut out = String::from("SELECT ");
440 if self.distinct {
441 out.push_str("DISTINCT ");
442 }
443 if self.select.is_empty() {
444 out.push('*');
445 } else {
446 out.push_str(&self.select.join(", "));
447 }
448 out.push_str(&format!(" FROM {}", self.from));
449 if let Some((t, on)) = &self.join {
450 let kind = if self.join_outer { "LEFT JOIN" } else { "JOIN" };
451 out.push_str(&format!(" {kind} {t} ON {on}"));
452 }
453 if !self.wheres.is_empty() {
454 out.push_str(&format!(" WHERE {}", self.wheres.join(" AND ")));
455 }
456 if let Some(g) = &self.group_by {
457 out.push_str(&format!(" GROUP BY {g}"));
458 }
459 if let Some(h) = &self.having {
460 out.push_str(&format!(" HAVING {h}"));
461 }
462 if let Some((e, desc)) = &self.order_by {
463 out.push_str(&format!(" ORDER BY {e}"));
464 if *desc {
465 out.push_str(" DESC");
466 }
467 }
468 if let Some(n) = &self.limit {
469 out.push_str(&format!(" LIMIT {n}"));
470 }
471 out
472 }
473}
474
475/// A partial-pushdown plan: the leading row predicates as a WHERE
476/// clause for `table`'s fetch. The caller runs the *original* query
477/// against the filtered adapter — the engine re-applies the pushed
478/// predicates (a no-op on pre-filtered rows), so no rewriting.
479pub struct Partial {
480 pub table: String,
481 pub where_sql: String,
482 /// As [`Pushdown::column_types`]: the prefilter keeps every row
483 /// the scan would only where these assumptions hold.
484 pub column_types: ColumnTypes,
485}
486
487/// Attempt a partial pushdown: `Some` when the query's leading row
488/// predicates translate strictly and the rest of the query provably
489/// cannot observe the filtering. The gates, each with its reason:
490/// a single `/table/*` branch with no correlations (other shapes
491/// address other data); only the *leading* run of expression
492/// predicates pushes (a positional predicate before an expression
493/// one sees unfiltered rows on the scan path); the table's name
494/// appears exactly once among the query's steps (a second reach —
495/// `^`-anchored subcontexts, self-references — would see the
496/// filtered subset); no crosslink or resolution axes anywhere
497/// (backlinks and reverse resolution into the table would too);
498/// and no `:` / `:::` metadata anywhere (a filtered `:::n-rows`
499/// would lie).
500pub fn partial_pushdown(quarb: &str, dialect: Option<Dialect>) -> Option<Partial> {
501 partial_pushdown_explained(quarb, dialect).ok()
502}
503
504/// [`partial_pushdown`], keeping the refusal reason. `dialect`
505/// enables the JSON-column prefilters — the strict fixed-path
506/// string equality, plus the relaxed superset forms (numeric
507/// comparisons, existence) that are safe here and only here,
508/// because the caller re-runs the original query over the
509/// fetched subset.
510pub fn partial_pushdown_explained(
511 quarb: &str,
512 dialect: Option<Dialect>,
513) -> Result<Partial, SqlError> {
514 partial_pushdown_with(quarb, dialect, false)
515}
516
517/// [`partial_pushdown_explained`] for an adapter that reads hops by
518/// key and filters only the table's listing
519/// (`RelationalModel::with_filtered_listing`): crosslinks and
520/// resolutions no longer refuse the prefilter, since a hop into the
521/// filtered table reads its row unfiltered. What still refuses: a
522/// second navigation into the table, and a `<--` or `=>` scope that
523/// could list it.
524pub fn partial_pushdown_keyed(quarb: &str, dialect: Option<Dialect>) -> Result<Partial, SqlError> {
525 partial_pushdown_with(quarb, dialect, true)
526}
527
528fn partial_pushdown_with(
529 quarb: &str,
530 dialect: Option<Dialect>,
531 keyed_hops: bool,
532) -> Result<Partial, SqlError> {
533 refuse_marker(quarb)?;
534 let arbor =
535 QueryArbor::parse(quarb).map_err(|e| SqlError::Syntax(format!("parsing Quarb: {e}")))?;
536 refuse_groups(&arbor)?;
537 let mut ex = Exporter {
538 arbor,
539 notes: Vec::new(),
540 strict: true,
541 dialect,
542 from_table: String::new(),
543 join_on_cols: Vec::new(),
544 join_table: None,
545 join_every: false,
546 column_types: ColumnTypes::default(),
547 from_sql: String::new(),
548 join_sql: None,
549 in_on: false,
550 aggregate: false,
551 keyed_hops,
552 from_marks: Vec::new(),
553 join_marks: Vec::new(),
554 };
555 ex.partial()
556}
557
558/// Refuse a query carrying path-pattern groups: neither the SQL
559/// translation nor the pushdown safe set covers them, and the shape
560/// checks below count only `step` children — an unguarded group
561/// would silently vanish from the translation. Refused queries fall
562/// back to the scan path, which evaluates groups correctly.
563fn refuse_groups(arbor: &QueryArbor) -> Result<(), SqlError> {
564 let mut stack = vec![arbor.root()];
565 while let Some(n) = stack.pop() {
566 if arbor.name(n).as_deref() == Some("group") {
567 return Err(SqlError::Unsupported(
568 "path patterns (groups and quantifiers)".into(),
569 ));
570 }
571 stack.extend(arbor.children(n));
572 }
573 Ok(())
574}
575
576struct Exporter {
577 arbor: QueryArbor,
578 notes: Vec<String>,
579 /// Pushdown mode: refuse every construct whose SQL semantics
580 /// are not provably identical to Quarb's (LIKE case folding,
581 /// truthiness, group/distinct/sort ordering).
582 strict: bool,
583 /// The target dialect for JSON-column-path pushdown; `None`
584 /// leaves such filters on the client-side graft.
585 dialect: Option<Dialect>,
586 from_table: String,
587 join_on_cols: Vec<String>,
588 join_table: Option<String>,
589 /// The correlation is `<=>*`: every witness, the SQL JOIN itself.
590 join_every: bool,
591 /// What the comparisons assume of column types (see
592 /// [`Pushdown::column_types`]).
593 column_types: ColumnTypes,
594 from_sql: String,
595 join_sql: Option<String>,
596 in_on: bool,
597 aggregate: bool,
598 /// The adapter reads hops by key (the pushed-down WHERE filters
599 /// the table's listing only), so crosslinks and resolutions are
600 /// safe beside the prefilter.
601 keyed_hops: bool,
602 /// The names the driver's rows are marked under (`/tracks/* .t`)
603 /// and the names the joined expression files its witness under
604 /// (`<=> /albums/*[…] .al`): `$$.t::col` is the FROM table's
605 /// column, `$$.al::col` the joined table's.
606 from_marks: Vec<String>,
607 join_marks: Vec<String>,
608}
609
610impl Exporter {
611 fn kids(&self, n: NodeId, kind: &str) -> Vec<NodeId> {
612 self.arbor
613 .children(n)
614 .into_iter()
615 .filter(|&c| self.arbor.name(c).as_deref() == Some(kind))
616 .collect()
617 }
618
619 fn kid(&self, n: NodeId, kind: &str) -> Option<NodeId> {
620 self.kids(n, kind).into_iter().next()
621 }
622
623 fn prop(&self, n: NodeId, key: &str) -> Option<Value> {
624 self.arbor.property(n, key)
625 }
626
627 fn prop_s(&self, n: NodeId, key: &str) -> String {
628 self.prop(n, key).map(|v| v.to_string()).unwrap_or_default()
629 }
630
631 fn kind(&self, n: NodeId) -> String {
632 self.arbor.name(n).unwrap_or_default()
633 }
634
635 /// Whether `n` is a bare `null` literal operand.
636 fn is_null_literal(&self, n: NodeId) -> bool {
637 self.kind(n) == "literal" && self.prop_s(n, "type") == "null"
638 }
639
640 /// The partial-pushdown analysis (see [`partial_pushdown`]).
641 fn partial(&mut self) -> Result<Partial, SqlError> {
642 let root = self.arbor.root();
643 let q = self
644 .kid(root, "query")
645 .ok_or_else(|| SqlError::Unsupported("empty query".into()))?;
646 // A correlation does not forbid the prefilter: the driver's
647 // own predicates restrict the driver's rows whatever the join
648 // then binds. What must not happen is the join (or anything
649 // else) reaching the filtered table a second time — a
650 // self-join would see only the filtered rows — and the
651 // whole-query gates below refuse exactly that: they walk the
652 // correlation entries too.
653 let branches = self.kids(q, "branch");
654 if branches.len() != 1 {
655 return Err(SqlError::Unsupported("a branch union".into()));
656 }
657 let (table, preds) = self.table_branch_lead(branches[0], self.keyed_hops)?;
658
659 // Whole-query gates.
660 let all = self.walk_all(root);
661 let mut table_mentions = 0;
662 for n in &all {
663 match self.kind(*n).as_str() {
664 "step" => {
665 let axis = self.prop_s(*n, "axis");
666 // A crosslink, a resolution or a value match may
667 // land in (or search) the filtered table and would
668 // see only its filtered rows: `=>` and the scoped
669 // `<--` carry their scope as text, so the table
670 // count below cannot see them.
671 if matches!(axis.as_str(), "->" | "<-" | "--" | "-->" | "<--" | "=>") {
672 // Where hops are read by key they are exact
673 // beside the prefilter. A scope is a listing,
674 // though: it is safe only when it plainly
675 // lists another table (`/other/…`), and an
676 // unscoped `=>` walks every table.
677 let scope = self.prop_s(*n, "scope");
678 let lists_other_table = scope
679 .strip_prefix('/')
680 .and_then(|rest| rest.split(['/', '[', '<']).next())
681 .is_some_and(|first| {
682 !first.is_empty()
683 && first != table
684 && first.chars().all(|c| c.is_alphanumeric() || c == '_')
685 });
686 let safe = self.keyed_hops
687 && if scope.is_empty() {
688 axis != "=>"
689 } else {
690 lists_other_table
691 };
692 if !safe {
693 return Err(SqlError::Unsupported(
694 "crosslink/resolution axes could reach \
695 the filtered table"
696 .into(),
697 ));
698 }
699 }
700 if self.prop_s(*n, "matcher") == table {
701 table_mentions += 1;
702 }
703 }
704 "projection" if self.prop_s(*n, "kind") != "property" => {
705 return Err(SqlError::Unsupported(
706 "metadata would observe the filtering \
707 (:::n-rows, :index)"
708 .into(),
709 ));
710 }
711 _ => {}
712 }
713 }
714 if table_mentions != 1 {
715 return Err(SqlError::Unsupported(
716 "the table is reached more than once".into(),
717 ));
718 }
719
720 // The leading run of expression predicates. Strict
721 // translation first; a predicate the strict translator
722 // refuses tries the relaxed prefilter ladder — superset
723 // semantics: the fetched set may hold extra rows, because
724 // the caller re-runs the ORIGINAL query, which re-applies
725 // every predicate; it must never lose a matching row. An
726 // untranslatable predicate is skipped, not fatal — a
727 // shorter conjunction is still a superset filter. A
728 // positional predicate (index/range) ends the run:
729 // predicates after it filter a positionally-selected
730 // subsequence.
731 let mut conds = Vec::new();
732 for p in preds {
733 if self.prop_s(p, "kind") != "expr" {
734 break;
735 }
736 match self.predicate_cond(p, None) {
737 Ok(c) => conds.push(c),
738 Err(_) => {
739 if let Some(c) = self.prefilter_cond(p) {
740 conds.push(c);
741 }
742 }
743 }
744 }
745 if conds.is_empty() {
746 return Err(SqlError::Unsupported(
747 "no leading expression predicates to push".into(),
748 ));
749 }
750 Ok(Partial {
751 table,
752 where_sql: conds.join(" AND "),
753 column_types: self.column_types.clone(),
754 })
755 }
756
757 /// The relaxed prefilter for one refused expression predicate:
758 /// the AND of whatever conjuncts translate, each a superset of
759 /// the rows its Quarb counterpart keeps. None when nothing
760 /// does — the predicate stays entirely on the engine.
761 fn prefilter_cond(&mut self, p: NodeId) -> Option<String> {
762 let parts: Vec<String> = self
763 .arbor
764 .children(p)
765 .into_iter()
766 .filter_map(|c| {
767 self.pred_expr(c, None)
768 .ok()
769 .or_else(|| self.prefilter_expr(c))
770 })
771 .collect();
772 if parts.is_empty() {
773 None
774 } else {
775 Some(parts.join(" AND "))
776 }
777 }
778
779 /// One conjunct's superset prefilter — fixed-path JSON shapes
780 /// only, per dialect. Every form here is proven to keep every
781 /// row the graft would match (extras are fine; the engine
782 /// re-checks). The proofs lean on three graft facts: absent
783 /// paths match no comparison; `value_eq`/`value_cmp` coerce
784 /// numeric-looking strings numerically; and Str-to-Str
785 /// ordering is bytewise.
786 fn prefilter_expr(&mut self, e: NodeId) -> Option<String> {
787 let dialect = self.dialect?;
788 match self.kind(e).as_str() {
789 // A bare truthy path: existence (with `::`, value
790 // truthiness — existence is its superset). The type
791 // probe sees JSON null too, as the graft does.
792 "path" => {
793 let (col, path) = self.json_path_loose(e)?;
794 self.note_json_column(e, &col);
795 let probe = json_type_probe(dialect, None, &col, &path)?;
796 Some(json_valid_guard(
797 dialect,
798 None,
799 &col,
800 format!("{probe} IS NOT NULL"),
801 ))
802 }
803 "compare" => {
804 let op = self.prop_s(e, "op");
805 let kids = self.arbor.children(e);
806 if kids.len() != 2 {
807 return None;
808 }
809 for (pi, li) in [(0usize, 1usize), (1, 0)] {
810 let Some((col, path)) = self.json_path(kids[pi]) else {
811 continue;
812 };
813 if self.kind(kids[li]) != "literal" {
814 continue;
815 }
816 let ty = self.prop_s(kids[li], "type");
817 if ty == "null" {
818 return None;
819 }
820 let raw = self
821 .prop(kids[li], "value")
822 .map(|v| v.to_string())
823 .unwrap_or_default();
824 let op = if pi == 0 { op.clone() } else { flip_op(&op) };
825 self.note_json_column(kids[pi], &col);
826 return self.json_prefilter(dialect, &col, &path, &op, &ty, &raw);
827 }
828 None
829 }
830 _ => None,
831 }
832 }
833
834 /// Build the dialect's superset prefilter for
835 /// `json_path OP literal`.
836 fn json_prefilter(
837 &self,
838 d: Dialect,
839 col: &str,
840 path: &[String],
841 op: &str,
842 lit_ty: &str,
843 raw: &str,
844 ) -> Option<String> {
845 if !matches!(op, "=" | "!=" | "<" | "<=" | ">" | ">=") {
846 return None;
847 }
848 // `!=` matches every present path whose value isn't the
849 // literal — including JSON null and cross-typed values —
850 // so its floor is existence.
851 if op == "!=" {
852 let probe = json_type_probe(d, None, col, path)?;
853 return Some(json_valid_guard(
854 d,
855 None,
856 col,
857 format!("{probe} IS NOT NULL"),
858 ));
859 }
860 let numeric_lit = raw.trim().parse::<f64>().is_ok_and(|f| f.is_finite())
861 && (lit_ty != "text" || !raw.trim().is_empty());
862 if numeric_lit {
863 let num: f64 = raw.trim().parse().ok()?;
864 // Past 2^53 the engines' exact integers and the
865 // graft's f64 part ways at the boundary.
866 if num.abs() >= 9_007_199_254_740_992.0 {
867 return None;
868 }
869 let lit = raw.trim();
870 match d {
871 // Typed extract: JSON numbers compare numerically
872 // (both sides parse the same source text to f64);
873 // string values escape through the type probe —
874 // the graft may coerce them, the server must not
875 // drop them.
876 Dialect::Sqlite => {
877 let ex = json_extract(d, None, col, path);
878 let ty = json_type_probe(d, None, col, path)?;
879 Some(json_valid_guard(
880 d,
881 None,
882 col,
883 format!("({ex} {op} {lit} OR {ty} = 'text')"),
884 ))
885 }
886 // float8 is the graft's f64; jsonb numbers print
887 // exactly, so the cast parses the same decimal.
888 // Strings escape; everything else can't match.
889 Dialect::Postgres => {
890 let text = json_extract(d, None, col, path);
891 let ty = json_type_probe(d, None, col, path)?;
892 Some(format!(
893 "(CASE WHEN {ty} = 'number' THEN ({text})::float8 {op} {lit} \
894 WHEN {ty} = 'string' THEN true ELSE false END)"
895 ))
896 }
897 Dialect::MySql | Dialect::Mssql | Dialect::Oracle => None,
898 }
899 } else if lit_ty == "text" {
900 if raw.contains('\'') || raw.contains('\\') {
901 return None;
902 }
903 match d {
904 // Typed extract again: string values order bytewise
905 // on both sides; numbers and booleans sit below
906 // text in SQLite's cross-type order, so `<` keeps
907 // them (extras, re-checked) and `>` drops them
908 // (the graft refuses to order Str against them).
909 Dialect::Sqlite => {
910 let ex = json_extract(d, None, col, path);
911 Some(json_valid_guard(d, None, col, format!("{ex} {op} '{raw}'")))
912 }
913 // Text ordering elsewhere runs into collation; the
914 // engine keeps those.
915 _ => None,
916 }
917 } else {
918 None
919 }
920 }
921
922 /// [`json_path`], loosened for existence: the projection may
923 /// be absent (a bare structural path) as well as the bare
924 /// `::`.
925 /// Whether a JSON path under a column reads the column as JSON
926 /// on the strength of its declaration alone: the column hop
927 /// (the first step) carries no `<json>` trait. Such a column is
928 /// an assumption of the plan ([`ColumnTypes::json`]); with the
929 /// trait the graft is declared on the hop and holds on both
930 /// roads.
931 fn note_json_column(&mut self, o: NodeId, col: &str) {
932 let declared_on_hop = self.kids(o, "step").first().is_some_and(|s| {
933 self.kids(*s, "trait").iter().any(|t| {
934 matches!(self.prop(*t, "alts"), Some(Value::List(alts))
935 if alts.iter().any(|a| matches!(a, Value::Str(x) if x == "json")))
936 })
937 });
938 if !declared_on_hop && !self.column_types.json.iter().any(|c| c == col) {
939 self.column_types.json.push(col.to_string());
940 }
941 }
942
943 fn json_path_loose(&self, o: NodeId) -> Option<(String, Vec<String>)> {
944 if self.json_path(o).is_some() {
945 return self.json_path(o);
946 }
947 if self.kind(o) != "path" || self.kid(o, "projection").is_some() {
948 return None;
949 }
950 let steps = self.kids(o, "step");
951 if steps.len() < 2 {
952 return None;
953 }
954 let mut names = Vec::with_capacity(steps.len());
955 for s in &steps {
956 if self.prop_s(*s, "axis") != "/"
957 || self.prop_s(*s, "matcher-kind") != "name"
958 || self.kid(*s, "predicate").is_some()
959 {
960 return None;
961 }
962 let name = self.prop_s(*s, "matcher");
963 let plain = !name.is_empty()
964 && name
965 .chars()
966 .next()
967 .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
968 && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
969 if !plain {
970 return None;
971 }
972 names.push(name);
973 }
974 let col = names.remove(0);
975 Some((col, names))
976 }
977
978 fn walk_all(&self, n: NodeId) -> Vec<NodeId> {
979 let mut out = vec![n];
980 let mut i = 0;
981 while i < out.len() {
982 out.extend(self.arbor.children(out[i]));
983 i += 1;
984 }
985 out
986 }
987
988 fn query(&mut self) -> Result<String, SqlError> {
989 let root = self.arbor.root();
990 let q = self
991 .kid(root, "query")
992 .ok_or_else(|| SqlError::Unsupported("empty query".into()))?;
993 let mut sel = Select::default();
994
995 // Correlations: exactly one becomes the JOIN's left table.
996 let corrs = self.kids(q, "query");
997 let branches = self.kids(q, "branch");
998 if branches.len() != 1 {
999 return Err(SqlError::Unsupported(
1000 "a branch union (SQL has UNION, but result shapes differ; export one branch)"
1001 .into(),
1002 ));
1003 }
1004
1005 if corrs.len() > 1 {
1006 return Err(SqlError::Unsupported(
1007 "more than one correlation context".into(),
1008 ));
1009 }
1010 if let Some(corr) = corrs.first() {
1011 // Driver-first: the query's own branch is the FROM
1012 // table (the driver); the correlation entry is the
1013 // joined table, whose `$$` equalities form the ON.
1014 let (ltable, lpreds) = self.table_branch(branches[0])?;
1015 let (rtable, rpreds) = self.table_branch(self.kids(*corr, "branch")[0])?;
1016 self.from_marks = self.row_marks(branches[0])?;
1017 self.join_marks = self.row_marks(self.kids(*corr, "branch")[0])?;
1018 // a joined expression with a pipeline of its own binds
1019 // what that pipeline leaves: not a row of its table
1020 if self.kid(*corr, "pipeline").is_some() {
1021 return Err(SqlError::Unsupported(
1022 "a joined expression with a pipeline of its own".into(),
1023 ));
1024 }
1025 // The SQL renderings of the two table names (validated
1026 // or quoted); the raw names stay in the plan metadata,
1027 // which the driver matches against its catalog.
1028 let lsql = self.sql_ident(<able, "table name")?;
1029 let rsql = self.sql_ident(&rtable, "table name")?;
1030 self.from_sql = lsql.clone();
1031 self.join_sql = Some(rsql.clone());
1032 // The driver's own predicates are plain WHERE.
1033 let driver_conds: Vec<NodeId> = lpreds;
1034 // Split the joined expression's predicates: `$$`
1035 // equalities form the ON, the rest the WHERE.
1036 let mut on = Vec::new();
1037 let mut wheres = Vec::new();
1038 for p in rpreds {
1039 self.split_join_pred(p, &rsql, &mut on, &mut wheres)?;
1040 }
1041 // `<=>?` — the outer correlation keeps a driver row no
1042 // joined row admits, its witness null: a LEFT JOIN. The
1043 // joined expression's own predicates then select the
1044 // witness, so they belong to the ON; in a WHERE they
1045 // would discard the unmatched rows again.
1046 let outer = matches!(self.prop(*corr, "outer"), Some(Value::Bool(true)));
1047 if outer {
1048 on.append(&mut wheres);
1049 }
1050 sel.join_outer = outer;
1051 if on.is_empty() {
1052 return Err(SqlError::Unsupported(
1053 "a correlation without a '$$' equality (no JOIN condition)".into(),
1054 ));
1055 }
1056 for p in driver_conds {
1057 let cond = self.predicate_cond(p, Some(&lsql.clone()))?;
1058 wheres.push(cond);
1059 }
1060 // `<=>*` — every witness: the JOIN as SQL means it, one
1061 // row per matching pair; the plain `<=>` binds one.
1062 self.join_every = matches!(self.prop(*corr, "every"), Some(Value::Bool(true)));
1063 if !self.join_every {
1064 self.notes.push(
1065 "JOIN: Quarb's binding is existential (one row per FROM row, \
1066 bound to its first witness); SQL multiplies rows when \
1067 several joined rows match"
1068 .to_string(),
1069 );
1070 }
1071 sel.from = lsql.clone();
1072 self.from_table = ltable;
1073 self.join_table = Some(rtable);
1074 sel.join = Some((rsql.clone(), on.join(" AND ")));
1075 sel.wheres = wheres;
1076 // A terminal projection on the driving branch is a
1077 // one-column select of the FROM table.
1078 if let Some(proj) = self.kid(branches[0], "projection") {
1079 let col = self.projection_col(proj)?;
1080 let col = self.sql_ident(&col, "column name")?;
1081 sel.select.push(format!("{lsql}.{col}"));
1082 }
1083 if self
1084 .kid(self.kids(*corr, "branch")[0], "projection")
1085 .is_some()
1086 {
1087 return Err(SqlError::Unsupported(
1088 "a projection on the joined expression (project the witness \
1089 in the pipeline: '$$1::col')"
1090 .into(),
1091 ));
1092 }
1093 self.pipeline(q, &mut sel, Some((&lsql, &rsql)))?;
1094 } else {
1095 let (table, preds) = self.table_branch(branches[0])?;
1096 self.from_marks = self.row_marks(branches[0])?;
1097 sel.from = self.sql_ident(&table, "table name")?;
1098 self.from_table = table;
1099 for p in preds {
1100 let cond = self.predicate_cond(p, None)?;
1101 sel.wheres.push(cond);
1102 }
1103 // A terminal projection is a one-column select.
1104 if let Some(proj) = self.kid(branches[0], "projection") {
1105 let col = self.projection_col(proj)?;
1106 sel.select.push(self.sql_ident(&col, "column name")?);
1107 }
1108 self.pipeline(q, &mut sel, None)?;
1109 }
1110 Ok(sel.render())
1111 }
1112
1113 /// A `/table/*[preds]` branch: the table name and the row-step
1114 /// predicate nodes.
1115 fn table_branch(&mut self, b: NodeId) -> Result<(String, Vec<NodeId>), SqlError> {
1116 self.table_branch_lead(b, false)
1117 }
1118
1119 /// [`table_branch`]; with `more`, the branch may go on after
1120 /// `/table/*[…]` (a hop, a cell): the prefilter concerns its
1121 /// first two steps only, and the steps after them are held to
1122 /// the whole-query gates.
1123 fn table_branch_lead(
1124 &mut self,
1125 b: NodeId,
1126 more: bool,
1127 ) -> Result<(String, Vec<NodeId>), SqlError> {
1128 let steps = self.kids(b, "step");
1129 if steps.len() < 2 || (steps.len() > 2 && !more) {
1130 return Err(SqlError::Unsupported(
1131 "navigation beyond /table/* (SQL sees tables and rows)".into(),
1132 ));
1133 }
1134 let (t, rows) = (steps[0], steps[1]);
1135 if self.prop_s(t, "axis") != "/"
1136 || self.prop_s(t, "matcher-kind") != "name"
1137 || self.prop_s(rows, "axis") != "/"
1138 || self.prop_s(rows, "matcher-kind") != "any"
1139 {
1140 return Err(SqlError::Unsupported(
1141 "navigation beyond /table/* (SQL sees tables and rows)".into(),
1142 ));
1143 }
1144 if self.kid(t, "predicate").is_some() {
1145 return Err(SqlError::Unsupported("a predicate on the table hop".into()));
1146 }
1147 Ok((self.prop_s(t, "matcher"), self.kids(rows, "predicate")))
1148 }
1149
1150 /// The names a `/table/*` branch marks its rows under: the marks
1151 /// standing after the row step. A mark anywhere else names a
1152 /// node SQL has no row for (the table) and is not translated.
1153 fn row_marks(&self, b: NodeId) -> Result<Vec<String>, SqlError> {
1154 let kids = self.arbor.children(b);
1155 let rows = self.kids(b, "step").get(1).copied();
1156 let after = rows
1157 .and_then(|r| kids.iter().position(|k| *k == r))
1158 .unwrap_or(kids.len());
1159 let mut names = Vec::new();
1160 for (i, k) in kids.iter().enumerate() {
1161 if self.kind(*k) != "mark" {
1162 continue;
1163 }
1164 if i < after {
1165 return Err(SqlError::Unsupported(
1166 "a mark before the rows (SQL sees tables and rows)".into(),
1167 ));
1168 }
1169 // (a mark with no name is read by position alone, and
1170 // a read by position is not translated)
1171 if let Some(Value::Str(n)) = self.prop(*k, "name") {
1172 names.push(n);
1173 }
1174 }
1175 Ok(names)
1176 }
1177
1178 /// A path operand read through the capsa's node side (`$$.al`,
1179 /// `$$.2`, `((@))`): the mark's name where the anchor is one
1180 /// mark by name, and whether it is any mark anchor at all.
1181 fn mark_anchor(&self, o: NodeId) -> (Option<String>, bool) {
1182 let named = match self.prop(o, "mark") {
1183 Some(Value::Str(n)) => Some(n),
1184 _ => None,
1185 };
1186 let any = named.is_some()
1187 || [
1188 "mark-index",
1189 "mark-top",
1190 "mark-back",
1191 "marks-all",
1192 "marks-name",
1193 "edge-end",
1194 "node-id",
1195 ]
1196 .iter()
1197 .any(|k| self.prop(o, k).is_some());
1198 (named, any)
1199 }
1200
1201 /// One row predicate as a WHERE condition (qualify columns with
1202 /// `qualifier` when joining).
1203 fn predicate_cond(&mut self, p: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
1204 if self.prop_s(p, "kind") != "expr" {
1205 return Err(SqlError::Unsupported(
1206 "a positional predicate on rows (SQL rows are unordered; ORDER BY + LIMIT)".into(),
1207 ));
1208 }
1209 let parts: Vec<String> = self
1210 .arbor
1211 .children(p)
1212 .into_iter()
1213 .map(|c| self.pred_expr(c, qual))
1214 .collect::<Result<_, _>>()?;
1215 Ok(parts.join(" AND "))
1216 }
1217
1218 fn pred_expr(&mut self, e: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
1219 match self.kind(e).as_str() {
1220 "and" | "or" => {
1221 let op = self.kind(e).to_uppercase();
1222 let kids: Vec<String> = self
1223 .arbor
1224 .children(e)
1225 .into_iter()
1226 .map(|c| self.pred_expr(c, qual))
1227 .collect::<Result<_, _>>()?;
1228 Ok(format!("({})", kids.join(&format!(" {op} "))))
1229 }
1230 "not" => {
1231 // SQL's `NOT` propagates UNKNOWN: `NOT (x = 5)` is
1232 // UNKNOWN for a NULL `x` and drops the row, but Quarb's
1233 // negation keeps it (the inner `value_eq` is false, so
1234 // its negation is true). Not provably identical without
1235 // the schema — the pushdown paths refuse it and scan.
1236 if self.strict {
1237 return Err(SqlError::Semantics(
1238 "SQL NOT propagates UNKNOWN, dropping the NULL rows \
1239 Quarb keeps"
1240 .into(),
1241 ));
1242 }
1243 let inner: Vec<String> = self
1244 .arbor
1245 .children(e)
1246 .into_iter()
1247 .map(|c| self.pred_expr(c, qual))
1248 .collect::<Result<_, _>>()?;
1249 Ok(format!("NOT ({})", inner.join(" AND ")))
1250 }
1251 "parens" => {
1252 let inner: Vec<String> = self
1253 .arbor
1254 .children(e)
1255 .into_iter()
1256 .map(|c| self.pred_expr(c, qual))
1257 .collect::<Result<_, _>>()?;
1258 Ok(format!("({})", inner.join(" AND ")))
1259 }
1260 "compare" => {
1261 let op = self.prop_s(e, "op");
1262 let kids = self.arbor.children(e);
1263 // A comparison against a bare `null` literal. Quarb's
1264 // `value_eq` treats NULL as an ordinary value
1265 // (`value_eq(NULL, NULL)` is true, `value_eq(NULL, x)`
1266 // false), so `= null` keeps exactly the NULL rows and
1267 // `!= null` the non-NULL rows. SQL's `= NULL` / `<>
1268 // NULL` are always UNKNOWN and drop every row; the
1269 // `IS [NOT] NULL` forms are provably identical (and
1270 // portable across every target dialect).
1271 if matches!(op.as_str(), "=" | "!=")
1272 && (self.is_null_literal(kids[0]) || self.is_null_literal(kids[1]))
1273 {
1274 let other = if self.is_null_literal(kids[0]) {
1275 kids[1]
1276 } else {
1277 kids[0]
1278 };
1279 let col = self.operand(other, qual)?;
1280 return Ok(if op == "=" {
1281 format!("{col} IS NULL")
1282 } else {
1283 format!("{col} IS NOT NULL")
1284 });
1285 }
1286 // JSON-column-path pushdown: `[/col/a/b:: = 'lit']`
1287 // navigates into a JSON column and compares a fixed
1288 // path to a string literal. Only this exact shape —
1289 // fixed object path, string equality, and a literal
1290 // that does NOT look numeric — is provably identical
1291 // to the client-side graft (each engine's scalar
1292 // extractor unquotes to text, and an absent path or
1293 // non-string value excludes the row on both sides,
1294 // matching Quarb's `value_eq` on non-numeric text).
1295 // Numeric casts, `!=`, wildcards, and deeper
1296 // predicates fall through to the ordinary operand
1297 // logic below, which refuses the navigation; the
1298 // partial-pushdown prefilter ladder picks those up
1299 // with superset semantics. Enabled only when a
1300 // dialect is set.
1301 if op == "="
1302 && let Some(dialect) = self.dialect
1303 {
1304 for (pi, li) in [(0usize, 1usize), (1, 0)] {
1305 if self.is_text_literal(kids[li])
1306 && let Some((col, path)) = self.json_path(kids[pi])
1307 {
1308 self.note_json_column(kids[pi], &col);
1309 // Quarb's value_eq compares numeric-looking
1310 // strings numerically — '150' matches the
1311 // JSON number 150, and the string "150.0".
1312 // No engine's text extractor coerces that
1313 // way, so the pushed compare would drop
1314 // rows the graft keeps. Refuse; the
1315 // prefilter ladder handles it as a
1316 // superset.
1317 let raw = self
1318 .prop(kids[li], "value")
1319 .map(|v| v.to_string())
1320 .unwrap_or_default();
1321 if raw.trim().parse::<f64>().is_ok() {
1322 return Err(SqlError::Semantics(
1323 "a numeric-looking text literal against a \
1324 JSON path compares numerically in Quarb \
1325 (value coercion); no SQL extractor \
1326 matches that"
1327 .into(),
1328 ));
1329 }
1330 let lit = self.operand(kids[li], qual)?;
1331 let extract = json_extract(dialect, qual, &col, &path);
1332 return Ok(json_valid_guard(
1333 dialect,
1334 qual,
1335 &col,
1336 format!("{extract} = {lit}"),
1337 ));
1338 }
1339 }
1340 }
1341 // Any other JSON-path comparison: name the real
1342 // reason, not the generic flat-rows refusal — only
1343 // fixed-path string equality is provably identical
1344 // (Quarb coerces numeric-looking values; no
1345 // engine's extractor matches that). The partial
1346 // prefilter ladder covers these shapes.
1347 if self.dialect.is_some() {
1348 for side in [kids[0], kids[1]] {
1349 if self.json_path(side).is_some() || self.json_path_loose(side).is_some() {
1350 return Err(SqlError::Semantics(
1351 "a JSON-path comparison pushes whole only as \
1352 fixed-path string equality (Quarb coerces \
1353 numeric-looking values; no extractor matches \
1354 that); this shape rides the partial prefilter"
1355 .into(),
1356 ));
1357 }
1358 }
1359 }
1360 // Quarb compares by value; SQL by the column's type.
1361 // A column against a numeric literal is the scan's
1362 // comparison only on a numeric-typed column, and
1363 // against a text literal only on a column that is
1364 // not (MySQL reads `n = 'abc'` as `n = 0`): the
1365 // catalog decides, so both are recorded for the
1366 // caller. A numeric-looking TEXT literal meets
1367 // numbers as a number in Quarb and compares as text
1368 // in SQL, on every engine, so it does not push.
1369 if self.strict {
1370 for (ci, li) in [(0usize, 1usize), (1, 0)] {
1371 let Some(column) = self.column_operand(kids[ci]) else {
1372 continue;
1373 };
1374 if self.kind(kids[li]) != "literal" {
1375 continue;
1376 }
1377 let numeric = self
1378 .prop(kids[li], "value")
1379 .is_some_and(|v| Value::Str(v.to_string()).numeric_reading().is_some());
1380 let list = match (self.prop_s(kids[li], "type").as_str(), numeric) {
1381 ("null", _) => continue,
1382 ("text", true) => {
1383 return Err(SqlError::Semantics(
1384 "a numeric-looking text literal compares \
1385 numerically in Quarb (value coercion); SQL \
1386 compares it as text"
1387 .into(),
1388 ));
1389 }
1390 ("text", false) => &mut self.column_types.text,
1391 (_, true) => &mut self.column_types.numeric,
1392 (_, false) => continue,
1393 };
1394 if !list.contains(&column) {
1395 list.push(column);
1396 }
1397 }
1398 }
1399 let l = self.operand(kids[0], qual)?;
1400 // Ruling #33: a pattern literal on `=` pushes as
1401 // LIKE — a `%` per star, each literal segment
1402 // escaped, in order. Anchoring matches exactly:
1403 // LIKE anchors both ends, a flanking star lifts
1404 // one. The case-folding caveat is `*=`'s; `!=`
1405 // with a pattern rides the scan (NOT LIKE drops
1406 // the NULL rows Quarb keeps).
1407 if self.kind(kids[1]) == "pattern" {
1408 if op.as_str() != "=" {
1409 return Err(SqlError::Unsupported(format!(
1410 "a pattern literal on '{op}' (only '=' pushes)"
1411 )));
1412 }
1413 // PostgreSQL's LIKE is case-sensitive under its
1414 // deterministic collations — provably what the
1415 // pattern test does — so the strict push is
1416 // sound there (and a prefix pattern is
1417 // index-sargable server-side). Everywhere else
1418 // case folding is ambient state (SQLite pragma,
1419 // MySQL/MSSQL collation), so strict refuses.
1420 if self.strict && self.dialect != Some(Dialect::Postgres) {
1421 return Err(SqlError::Semantics(
1422 "LIKE case folding differs per engine \
1423 (provably case-sensitive only on PostgreSQL)"
1424 .into(),
1425 ));
1426 }
1427 if !self.strict {
1428 self.notes.push(
1429 "pattern → LIKE: Quarb's pattern test is \
1430 case-sensitive; LIKE folds case on \
1431 SQLite/MySQL but not PostgreSQL"
1432 .to_string(),
1433 );
1434 }
1435 let mut like = String::new();
1436 for kid in self.arbor.children(kids[1]) {
1437 match self.kind(kid).as_str() {
1438 "star" => like.push('%'),
1439 _ => {
1440 let raw = self
1441 .prop(kid, "value")
1442 .map(|v| v.to_string())
1443 .unwrap_or_default();
1444 like.push_str(
1445 &raw.replace('\\', "\\\\")
1446 .replace('%', "\\%")
1447 .replace('_', "\\_")
1448 .replace('\'', "''"),
1449 );
1450 }
1451 }
1452 }
1453 return Ok(format!("{l} LIKE '{like}' ESCAPE '\\'"));
1454 }
1455 let r = self.operand(kids[1], qual)?;
1456 Ok(match op.as_str() {
1457 "=" => format!("{l} = {r}"),
1458 "!=" => {
1459 // Quarb keeps rows whose operand is NULL (its
1460 // `value_eq` is false there, so `!=` is true);
1461 // SQL's `<>` is UNKNOWN for a NULL operand and
1462 // drops those rows. Not provably identical
1463 // without the schema, so pushdown refuses it;
1464 // the display translation keeps `<>` and notes
1465 // the divergence.
1466 if self.strict {
1467 return Err(SqlError::Semantics(
1468 "'!=' drops the NULL rows Quarb keeps \
1469 (SQL '<>' is UNKNOWN for NULL; use '!= null' \
1470 for IS NOT NULL)"
1471 .into(),
1472 ));
1473 }
1474 self.notes.push(
1475 "'!=' → '<>': Quarb keeps rows whose column is NULL; \
1476 SQL's '<>' drops them (use '!= null' for IS NOT NULL)"
1477 .to_string(),
1478 );
1479 format!("{l} <> {r}")
1480 }
1481 "<" | "<=" | ">" | ">=" => format!("{l} {op} {r}"),
1482 "*=" => {
1483 // The same PostgreSQL rung as the pattern
1484 // literal above: LIKE is provably
1485 // case-sensitive there, so `*=` pushes
1486 // strict too.
1487 if self.strict && self.dialect != Some(Dialect::Postgres) {
1488 return Err(SqlError::Semantics(
1489 "LIKE case folding differs per engine \
1490 (provably case-sensitive only on PostgreSQL)"
1491 .into(),
1492 ));
1493 }
1494 // The pattern must be a text literal: a
1495 // column or computed operand holds a value,
1496 // not a pattern, and SQL LIKE cannot express
1497 // "contains that value" portably.
1498 if !self.is_text_literal(kids[1]) {
1499 return Err(SqlError::Unsupported(
1500 "'*=' with a non-literal pattern".into(),
1501 ));
1502 }
1503 self.notes.push(
1504 "*= → LIKE: Quarb's substring test is case-sensitive; LIKE \
1505 folds case on SQLite/MySQL but not PostgreSQL"
1506 .to_string(),
1507 );
1508 // Escape LIKE's metacharacters, then quote.
1509 // The explicit ESCAPE makes '\' the escape
1510 // everywhere — SQLite, MSSQL, and Oracle
1511 // have no default escape character.
1512 let raw = self
1513 .prop(kids[1], "value")
1514 .map(|v| v.to_string())
1515 .unwrap_or_default();
1516 let pat = raw
1517 .replace('\\', "\\\\")
1518 .replace('%', "\\%")
1519 .replace('_', "\\_")
1520 .replace('\'', "''");
1521 format!("{l} LIKE '%{pat}%' ESCAPE '\\'")
1522 }
1523 "==" | "!==" | "=~" | "!~" => {
1524 return Err(SqlError::Semantics(
1525 "regex matching means a different REGEXP engine per \
1526 backend; regexes run engine-side"
1527 .into(),
1528 ));
1529 }
1530 other => {
1531 return Err(SqlError::Unsupported(format!("the '{other}' comparison")));
1532 }
1533 })
1534 }
1535 // A bare truthy operand.
1536 _ => {
1537 if self.strict {
1538 return Err(SqlError::Semantics(
1539 "truthiness diverges (0 and '' are falsy in Quarb)".into(),
1540 ));
1541 }
1542 self.notes.push(
1543 "truthiness: '[::c]' exports as IS NOT NULL, but Quarb also treats \
1544 0 and '' as falsy"
1545 .to_string(),
1546 );
1547 Ok(format!("{} IS NOT NULL", self.operand(e, qual)?))
1548 }
1549 }
1550 }
1551
1552 fn operand(&mut self, o: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
1553 match self.kind(o).as_str() {
1554 "literal" => {
1555 let v = self.prop(o, "value").unwrap_or(Value::Null);
1556 match self.prop_s(o, "type").as_str() {
1557 "text" => {
1558 let s = v.to_string();
1559 // No single escaping is portable across the
1560 // pushdown's target dialects: MySQL (default
1561 // sql_mode) and BigQuery read `\` as an escape
1562 // while SQLite/PostgreSQL/DuckDB take it
1563 // literally, and BigQuery rejects the `''`
1564 // quote-doubling the others require. A literal
1565 // carrying either character cannot be pushed as
1566 // provably identical SQL, so refuse it and let
1567 // the caller scan. (The display translation
1568 // keeps its best-effort `''`-doubling.)
1569 if self.strict && (s.contains('\'') || s.contains('\\')) {
1570 return Err(SqlError::Semantics(
1571 "a text literal with a quote or backslash \
1572 has no escaping portable across SQL dialects"
1573 .into(),
1574 ));
1575 }
1576 Ok(format!("'{}'", s.replace('\'', "''")))
1577 }
1578 "null" => Ok("NULL".to_string()),
1579 _ => Ok(v.to_string()),
1580 }
1581 }
1582 "path" => {
1583 if self.kid(o, "step").is_some() {
1584 // A step here is either navigation (refused) or
1585 // a resolution chain (refused with the reason).
1586 let s = self.kids(o, "step")[0];
1587 if self.prop_s(s, "axis") == "-->" {
1588 return Err(SqlError::Unsupported(
1589 "a '-->' resolution chain: the foreign-key targets live in \
1590 the schema, not the query — spell the join with '<=>' to \
1591 export it"
1592 .into(),
1593 ));
1594 }
1595 return Err(SqlError::Unsupported(
1596 "navigation inside a predicate (SQL rows are flat)".into(),
1597 ));
1598 }
1599 let p = self
1600 .kid(o, "projection")
1601 .ok_or_else(|| SqlError::Unsupported("an empty path operand".into()))?;
1602 let col = self.projection_col(p)?;
1603 let col = self.sql_ident(&col, "column name")?;
1604 // a read through a mark: the row the mark names
1605 let (named, any) = self.mark_anchor(o);
1606 if any {
1607 let Some(name) = named else {
1608 return Err(SqlError::Unsupported(
1609 "a mark read by position, or of several marks".into(),
1610 ));
1611 };
1612 if self.join_marks.contains(&name) {
1613 // `$$.al::col`: the witness, as `$$1::col`
1614 if self.in_on {
1615 return Err(SqlError::Unsupported(
1616 "the joined expression's own mark inside its ON".into(),
1617 ));
1618 }
1619 let Some(join) = self.join_sql.clone() else {
1620 return Err(SqlError::Unsupported(
1621 "a join mark outside a correlation join".into(),
1622 ));
1623 };
1624 return Ok(format!("{join}.{col}"));
1625 }
1626 if self.from_marks.contains(&name) {
1627 // `$$.t::col`: the driver's row, as `$$0::col`
1628 // in the ON
1629 return Ok(if self.join_sql.is_some() {
1630 format!("{}.{col}", self.from_sql.clone())
1631 } else {
1632 match qual {
1633 Some(q) => format!("{q}.{col}"),
1634 None => col,
1635 }
1636 });
1637 }
1638 return Err(SqlError::Unsupported(format!(
1639 "a read of the mark '.{name}' (not a row of the query's tables)"
1640 )));
1641 }
1642 Ok(match qual {
1643 Some(q) => format!("{q}.{col}"),
1644 None => col,
1645 })
1646 }
1647 "context" => {
1648 // `$$1::col` — the joined expression's witness, in
1649 // pipeline position: the joined table's column.
1650 // Anything else is outside the verified-safe set.
1651 let p = self
1652 .kid(o, "projection")
1653 .ok_or_else(|| SqlError::Unsupported("a bare '$$N' reference".into()))?;
1654 let col = self.projection_col(p)?;
1655 let col = self.sql_ident(&col, "column name")?;
1656 if matches!(self.prop(o, "index"), Some(Value::Int(0))) {
1657 // `$$0::col` — the driver, legal only inside the
1658 // joined expression's ON bracket (the parser
1659 // refuses it anywhere else).
1660 if !self.in_on {
1661 return Err(SqlError::Unsupported(
1662 "a '$$0' reference outside the join's ON".into(),
1663 ));
1664 }
1665 if self.kid(o, "step").is_some() {
1666 return Err(SqlError::Unsupported(
1667 "a '$$0' reference beyond a plain column ($$0::col)".into(),
1668 ));
1669 }
1670 return Ok(format!("{}.{col}", self.from_sql.clone()));
1671 }
1672 if self.in_on {
1673 return Err(SqlError::Unsupported(
1674 "a '$$N' reference inside the ON (the driver is '$$0')".into(),
1675 ));
1676 }
1677 let Some(join) = self.join_sql.clone() else {
1678 return Err(SqlError::Unsupported(
1679 "a '$$N' reference outside a correlation join".into(),
1680 ));
1681 };
1682 match self.prop(o, "index") {
1683 Some(Value::Int(1)) => Ok(format!("{join}.{col}")),
1684 None => Err(SqlError::Unsupported("a bare '$$N' reference".into())),
1685 Some(v) => Err(SqlError::Unsupported(format!(
1686 "pushdown: $${v} beyond a two-branch correlation"
1687 ))),
1688 }
1689 }
1690 "invoking" => {
1691 // `$$__::col` — the invoking position of an enclosing
1692 // query body, never the driver (that is `$$0`, a
1693 // context of index 0, since draft 153). SQL has no
1694 // enclosing body to read.
1695 Err(SqlError::Unsupported(
1696 "a '$$__' reference (the driver inside the ON is '$$0')".into(),
1697 ))
1698 }
1699 "arith" => {
1700 let op = self.prop_s(o, "op");
1701 let kids = self.arbor.children(o);
1702 let l = self.operand(kids[0], qual)?;
1703 let r = self.operand(kids[1], qual)?;
1704 Ok(match op.as_str() {
1705 "+" | "-" | "*" => format!("({l} {op} {r})"),
1706 "div" => format!("({l} / {r})"),
1707 "mod" => format!("({l} % {r})"),
1708 other => return Err(SqlError::Unsupported(format!("'{other}' arithmetic"))),
1709 })
1710 }
1711 other => Err(SqlError::Unsupported(format!(
1712 "the '{other}' operand (registers, topics, and captures are Quarb-side state)"
1713 ))),
1714 }
1715 }
1716
1717 fn projection_col(&mut self, p: NodeId) -> Result<String, SqlError> {
1718 match self.prop_s(p, "kind").as_str() {
1719 "property" => match self.prop(p, "key") {
1720 Some(k) => Ok(k.to_string()),
1721 None => Err(SqlError::Unsupported(
1722 "the bare '::' projection (name the column)".into(),
1723 )),
1724 },
1725 other => Err(SqlError::Unsupported(format!(
1726 "the {other} metadata projection"
1727 ))),
1728 }
1729 }
1730
1731 /// The column a plain column operand names (`::col`, `$*1::col`):
1732 /// a path without a step, or a context reference, projecting a
1733 /// named property.
1734 /// A numeric reducer (`sum`, `mean`, `min`, `max`) pushed over a
1735 /// column is the scan's only on a numeric-typed column: the
1736 /// scan lifts unit text (`'18 parasang'` under a declared unit)
1737 /// to quantities and orders texts as texts, where SQL sums a
1738 /// text column by its leading digits and orders it by
1739 /// collation. Recorded for the caller's catalog as a
1740 /// comparison's assumption is.
1741 fn assume_numeric(&mut self, column: Option<String>) {
1742 if !self.strict {
1743 return;
1744 }
1745 if let Some(c) = column
1746 && !self.column_types.numeric.contains(&c)
1747 {
1748 self.column_types.numeric.push(c);
1749 }
1750 }
1751
1752 fn column_operand(&self, o: NodeId) -> Option<String> {
1753 match self.kind(o).as_str() {
1754 "path" if self.kid(o, "step").is_none() => {}
1755 "context" => {}
1756 _ => return None,
1757 }
1758 let p = self.kid(o, "projection")?;
1759 if self.prop_s(p, "kind") != "property" {
1760 return None;
1761 }
1762 self.prop(p, "key").map(|k| k.to_string())
1763 }
1764
1765 /// Whether `o` is a text string literal (`'London'`).
1766 fn is_text_literal(&self, o: NodeId) -> bool {
1767 self.kind(o) == "literal" && self.prop_s(o, "type") == "text"
1768 }
1769
1770 /// If `o` is the one JSON-column-path shape pushdown handles —
1771 /// `/col/seg/seg…::`, a plain-navigation path (every hop `/`
1772 /// and a plain-identifier object key, no wildcards, no nested
1773 /// predicate), at least one segment past the column, ending in
1774 /// the bare `::` projection — return `(column, [json segments])`.
1775 /// Anything else is `None` (and falls back to the graft).
1776 fn json_path(&self, o: NodeId) -> Option<(String, Vec<String>)> {
1777 if self.kind(o) != "path" {
1778 return None;
1779 }
1780 let steps = self.kids(o, "step");
1781 if steps.len() < 2 {
1782 return None;
1783 }
1784 // The projection must be the bare `::` (default value of
1785 // the JSON leaf), not `::key` or a `:::`/`:` metadata form.
1786 let proj = self.kid(o, "projection")?;
1787 if self.prop_s(proj, "kind") != "property" || self.prop(proj, "key").is_some() {
1788 return None;
1789 }
1790 let mut names = Vec::with_capacity(steps.len());
1791 for s in &steps {
1792 if self.prop_s(*s, "axis") != "/"
1793 || self.prop_s(*s, "matcher-kind") != "name"
1794 || self.kid(*s, "predicate").is_some()
1795 {
1796 return None;
1797 }
1798 let name = self.prop_s(*s, "matcher");
1799 // Plain object keys only — no array indices, no
1800 // characters that would need per-dialect path escaping.
1801 let plain = !name.is_empty()
1802 && name
1803 .chars()
1804 .next()
1805 .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
1806 && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
1807 if !plain {
1808 return None;
1809 }
1810 names.push(name);
1811 }
1812 let col = names.remove(0);
1813 Some((col, names))
1814 }
1815
1816 /// A safe `AS` alias: bare when it is a plain identifier and
1817 /// not an SQL keyword; otherwise strict mode refuses (quoting
1818 /// dialects disagree) and export mode double-quotes, noting it.
1819 fn alias(&mut self, name: &str) -> Result<String, SqlError> {
1820 if is_plain_ident(name) {
1821 return Ok(name.to_string());
1822 }
1823 if self.strict {
1824 return Err(SqlError::Unsupported(format!(
1825 "pushdown: field name {name:?} needs SQL quoting \
1826 (dialects disagree); rename the field"
1827 )));
1828 }
1829 self.notes
1830 .push(format!("field name {name:?} double-quoted (ANSI)"));
1831 Ok(format!("\"{}\"", name.replace('"', "\"\"")))
1832 }
1833
1834 /// A table or column name rendered into SQL. Bare when it is a
1835 /// plain identifier; otherwise strict mode refuses — a name
1836 /// like `a OR b` would silently rewrite the emitted SQL's
1837 /// meaning, breaking the provably-identical guarantee (and a
1838 /// portable quoting does not exist) — and export mode
1839 /// double-quotes with a note.
1840 fn sql_ident(&mut self, name: &str, what: &str) -> Result<String, SqlError> {
1841 if is_plain_ident(name) {
1842 return Ok(name.to_string());
1843 }
1844 if self.strict {
1845 return Err(SqlError::Unsupported(format!(
1846 "pushdown: {what} {name:?} is not a plain SQL identifier"
1847 )));
1848 }
1849 self.notes
1850 .push(format!("{what} {name:?} double-quoted (ANSI)"));
1851 Ok(format!("\"{}\"", name.replace('"', "\"\"")))
1852 }
1853
1854 /// Split a joined-side predicate: `col = $*1::col2` equalities
1855 /// become the ON condition; everything else the WHERE.
1856 /// `ltable` and `rtable` are the tables' SQL renderings.
1857 fn split_join_pred(
1858 &mut self,
1859 p: NodeId,
1860 rtable: &str,
1861 on: &mut Vec<String>,
1862 wheres: &mut Vec<String>,
1863 ) -> Result<(), SqlError> {
1864 if self.prop_s(p, "kind") != "expr" {
1865 return Err(SqlError::Unsupported(
1866 "a positional predicate on the joined side".into(),
1867 ));
1868 }
1869 // Flatten top-level ANDs; each conjunct routes to ON or
1870 // WHERE.
1871 fn conjuncts(ex: &Exporter, e: NodeId, out: &mut Vec<NodeId>) {
1872 if ex.kind(e) == "and" {
1873 for c in ex.arbor.children(e) {
1874 conjuncts(ex, c, out);
1875 }
1876 } else {
1877 out.push(e);
1878 }
1879 }
1880 let mut parts = Vec::new();
1881 for c in self.arbor.children(p) {
1882 conjuncts(self, c, &mut parts);
1883 }
1884 for e in parts {
1885 let uses_driver = self.subtree_has_driver(e);
1886 self.in_on = true;
1887 let cond = self.pred_expr(e, Some(rtable));
1888 self.in_on = false;
1889 let cond = cond?;
1890 if uses_driver && self.kind(e) == "compare" && self.prop_s(e, "op") == "=" {
1891 // Record which joined-table columns the ON binds —
1892 // the uniqueness obligation (see
1893 // Pushdown::join_left). Collected from the arbor's
1894 // bare-column operand nodes, never from the
1895 // rendered SQL text, so neither a literal nor an
1896 // unusual column name can corrupt the obligation.
1897 self.collect_join_cols(e)?;
1898 on.push(cond);
1899 } else {
1900 wheres.push(cond);
1901 }
1902 }
1903 Ok(())
1904 }
1905
1906 /// The joined-table columns the ON equality binds: every bare
1907 /// column operand (`::col`) in `e`'s subtree, appended to the
1908 /// join obligation with their raw (catalog) names.
1909 fn collect_join_cols(&mut self, e: NodeId) -> Result<(), SqlError> {
1910 // The `$$0` side is the driver — not part of the joined
1911 // table's obligation.
1912 if self.is_driver(e) {
1913 return Ok(());
1914 }
1915 if self.kind(e) == "path"
1916 && self.kid(e, "step").is_none()
1917 && let Some(p) = self.kid(e, "projection")
1918 {
1919 let col = self.projection_col(p)?;
1920 self.join_on_cols.push(col);
1921 }
1922 for c in self.arbor.children(e) {
1923 self.collect_join_cols(c)?;
1924 }
1925 Ok(())
1926 }
1927
1928 /// `$$0`: a context operand of index 0 (the driver), or a read
1929 /// of the driver's row through its mark (`$$.t::col`).
1930 fn is_driver(&self, n: NodeId) -> bool {
1931 (self.kind(n) == "context" && matches!(self.prop(n, "index"), Some(Value::Int(0))))
1932 || (self.kind(n) == "path"
1933 && matches!(self.mark_anchor(n).0, Some(name) if self.from_marks.contains(&name)))
1934 }
1935
1936 fn subtree_has_driver(&self, n: NodeId) -> bool {
1937 self.is_driver(n)
1938 || self
1939 .arbor
1940 .children(n)
1941 .into_iter()
1942 .any(|c| self.subtree_has_driver(c))
1943 }
1944
1945 /// Consume the pipeline into SELECT clauses.
1946 fn pipeline(
1947 &mut self,
1948 q: NodeId,
1949 sel: &mut Select,
1950 join: Option<(&str, &str)>,
1951 ) -> Result<(), SqlError> {
1952 let Some(pipe) = self.kid(q, "pipeline") else {
1953 return Ok(());
1954 };
1955 let commands: Vec<NodeId> = self.arbor.children(pipe);
1956 let mut i = 0;
1957 // A pending per-row value (`| ::col`) feeding an aggregate,
1958 // and the column it names where it is one.
1959 let mut pending_col: Option<String> = None;
1960 let mut pending_name: Option<String> = None;
1961 // After a grouped reduction: (key, agg_sql, alias).
1962 let mut grouped: Option<(String, String, String)> = None;
1963 // A pushed key awaiting its fold: (the regula's name, key_sql).
1964 let mut pushed_key: Option<(String, String)> = None;
1965
1966 while i < commands.len() {
1967 let s = commands[i];
1968 match self.kind(s).as_str() {
1969 "expr" => {
1970 let kids = self.arbor.children(s);
1971 pending_col = Some(self.operand(kids[0], join.map(|(l, _)| l))?);
1972 pending_name = self.column_operand(kids[0]);
1973 }
1974 "cmd" => {
1975 let name = self.prop_s(s, "name");
1976 match name.as_str() {
1977 "rec" | "record" => {
1978 sel.select = self.record_fields(s, join)?;
1979 }
1980 // A reducing aggregate on the plain pipe:
1981 // the grouped reduction.
1982 "count" | "sum" | "mean" | "avg" | "min" | "max" => {
1983 let (key, _, _) = grouped.as_ref().ok_or_else(|| {
1984 SqlError::Unsupported(format!(
1985 "'| {name}' outside a group (use '@| {name}')"
1986 ))
1987 })?;
1988 // Quarb's count counts every member,
1989 // nulls included: COUNT(*), never the
1990 // NULL-skipping COUNT(col).
1991 let col = if name == "count" {
1992 pending_col = None;
1993 None
1994 } else {
1995 self.assume_numeric(pending_name.take());
1996 pending_col.take()
1997 };
1998 let agg = sql_agg(&name, col)?;
1999 grouped = Some((key.clone(), agg.clone(), agg));
2000 }
2001 other => {
2002 // sort/unique/top and kin are spellable
2003 // in SQL but with the backend's own
2004 // collation and duplicate semantics —
2005 // name the divergence, not a missing
2006 // feature.
2007 if matches!(other, "sort" | "sort_by" | "unique" | "top" | "bottom") {
2008 return Err(SqlError::Semantics(format!(
2009 "'{other}' means the backend's collation and \
2010 duplicate semantics; one engine-side ordering \
2011 keeps it identical everywhere"
2012 )));
2013 }
2014 return Err(SqlError::Unsupported(format!(
2015 "the '{other}' pipeline command"
2016 )));
2017 }
2018 }
2019 }
2020 "push" => {
2021 // An alias for the grouped aggregate.
2022 if let Some((k, agg, _)) = grouped.take() {
2023 let alias = self.prop_s(s, "name");
2024 grouped = Some((k, agg, alias));
2025 } else {
2026 return Err(SqlError::Unsupported(
2027 "a register push (Quarb-side state)".into(),
2028 ));
2029 }
2030 }
2031 // `| .k(::k)` before a fold by `.k`: the GROUP BY key
2032 // (a projection body is a subcontext of one branch).
2033 "expr-push" if grouped.is_none() && pushed_key.is_none() => {
2034 let kids = self.arbor.children(s);
2035 let key = self.operand(kids[0], join.map(|(l, _)| l))?;
2036 pushed_key = Some((self.prop_s(s, "name"), key));
2037 }
2038 "subcontext" if grouped.is_none() && pushed_key.is_none() => {
2039 let key = self.pushed_column(s, join.map(|(l, _)| l))?;
2040 pushed_key = Some((self.prop_s(s, "name"), key));
2041 }
2042 "filter" => {
2043 if grouped.is_some() {
2044 // HAVING: `$_` / the alias refer to the
2045 // aggregate.
2046 let cond = self.having_cond(s)?;
2047 sel.having = Some(cond);
2048 } else {
2049 return Err(SqlError::Unsupported(
2050 "a mid-pipeline filter (put it in the row predicate)".into(),
2051 ));
2052 }
2053 }
2054 "recall" => {
2055 // `| %.` finalizes the grouped record.
2056 if self.prop_s(s, "ref") != "%." {
2057 return Err(SqlError::Unsupported(
2058 "a register recall (Quarb-side state)".into(),
2059 ));
2060 }
2061 let (key, agg, alias) = grouped.clone().ok_or_else(|| {
2062 SqlError::Unsupported("'%.', with nothing grouped".into())
2063 })?;
2064 let alias = self.alias(&alias)?;
2065 sel.select = vec![key.clone(), format!("{agg} AS {alias}")];
2066 // The HAVING condition compared the aggregate
2067 // through $_ — substitute the real expression.
2068 if let Some(h) = sel.having.take() {
2069 sel.having = Some(h.replace("__AGG__", &agg));
2070 }
2071 }
2072 "agg" if self.prop(s, "group").is_some() => {
2073 // `@|{.k} agg`: the fold by the pushed key is the
2074 // grouped reduction, GROUP BY key.
2075 let name = self.prop_s(s, "name");
2076 if !matches!(
2077 name.as_str(),
2078 "count" | "sum" | "mean" | "avg" | "min" | "max"
2079 ) {
2080 return Err(SqlError::Unsupported(format!(
2081 "the '{name}' command per group (GROUP BY reduces)"
2082 )));
2083 }
2084 let selector = self.prop_s(s, "group");
2085 if selector.contains(';') {
2086 return Err(SqlError::Unsupported(
2087 "a fold by several regulae (one GROUP BY key translates)".into(),
2088 ));
2089 }
2090 let (reg, key) = pushed_key.take().ok_or_else(|| {
2091 SqlError::Unsupported("a fold by a regula no push of a key made".into())
2092 })?;
2093 if selector != "." && selector != format!(".{reg}") {
2094 return Err(SqlError::Unsupported(format!(
2095 "a fold by '{selector}' (the pushed key is '.{reg}')"
2096 )));
2097 }
2098 if self.strict {
2099 return Err(SqlError::Semantics(
2100 "GROUP BY result order is unordered in SQL".into(),
2101 ));
2102 }
2103 sel.group_by = Some(key.clone());
2104 let col = if name == "count" {
2105 pending_col = None;
2106 None
2107 } else {
2108 self.assume_numeric(pending_name.take());
2109 pending_col.take()
2110 };
2111 let agg = sql_agg(&name, col)?;
2112 grouped = Some((key, agg.clone(), agg));
2113 }
2114 "agg" => {
2115 let name = self.prop_s(s, "name");
2116 match name.as_str() {
2117 "count" | "sum" | "mean" | "avg" | "min" | "max" => {
2118 // Quarb's count counts every row, nulls
2119 // included: COUNT(*) regardless of a
2120 // pending column.
2121 let col = if name == "count" {
2122 pending_col = None;
2123 None
2124 } else {
2125 self.assume_numeric(pending_name.take());
2126 pending_col.take()
2127 };
2128 sel.select = vec![sql_agg(&name, col)?];
2129 self.aggregate = true;
2130 }
2131 "sort_by" => {
2132 if self.strict {
2133 return Err(SqlError::Semantics(
2134 "ORDER BY collations differ per engine".into(),
2135 ));
2136 }
2137 // A sort after a positional selection
2138 // (or a second sort) cannot render: the
2139 // fixed SELECT shape orders before
2140 // LIMIT, and has one ORDER BY.
2141 if sel.limit.is_some() {
2142 return Err(SqlError::Unsupported(
2143 "a sort after a positional selection (SQL orders \
2144 before LIMIT)"
2145 .into(),
2146 ));
2147 }
2148 if sel.order_by.is_some() {
2149 return Err(SqlError::Unsupported(
2150 "a second sort (SQL has a single ORDER BY)".into(),
2151 ));
2152 }
2153 let kids = self.arbor.children(s);
2154 // The options are the command's own:
2155 // `--desc` is the direction, a named
2156 // collation (`--locale=tag`, ruling
2157 // 2026-11-11) is the engine's order and no
2158 // backend's; a second key has no place in
2159 // the one ORDER BY this shape holds.
2160 let mut desc = false;
2161 for &k in &kids[1..] {
2162 if self.kind(k) != "option" {
2163 return Err(SqlError::Unsupported(
2164 "a sort by several keys".into(),
2165 ));
2166 }
2167 match self.prop_s(k, "name").as_str() {
2168 "--desc" | "-d" => desc = true,
2169 "--locale" => {
2170 return Err(SqlError::Semantics(
2171 "sort_by(--locale=…) names the engine's collation; \
2172 a backend's differs"
2173 .into(),
2174 ));
2175 }
2176 // a case order is that
2177 // collation's (ruling 2026-11-12)
2178 "--upper-first" | "-u" | "--lower-first" | "-l"
2179 | "--ignore-case" | "-i" => {
2180 return Err(SqlError::Semantics(
2181 "sort_by's case order is the engine's collation's; \
2182 a backend's differs"
2183 .into(),
2184 ));
2185 }
2186 other => {
2187 return Err(SqlError::Unsupported(format!(
2188 "the '{other}' option of sort_by"
2189 )));
2190 }
2191 }
2192 }
2193 let e = self.operand(kids[0], join.map(|(l, _)| l))?;
2194 sel.order_by = Some((e, desc));
2195 }
2196 "reverse" => match &mut sel.order_by {
2197 Some((_, desc)) => *desc = true,
2198 None => {
2199 return Err(SqlError::Unsupported(
2200 "reverse without an ORDER BY (rows are unordered)".into(),
2201 ));
2202 }
2203 },
2204 "top" => {
2205 if self.strict {
2206 return Err(SqlError::Semantics(
2207 "ORDER BY collations differ per engine".into(),
2208 ));
2209 }
2210 if sel.limit.is_some() {
2211 return Err(SqlError::Unsupported(
2212 "'top' after a positional selection (SQL orders \
2213 before LIMIT)"
2214 .into(),
2215 ));
2216 }
2217 if sel.order_by.is_some() {
2218 return Err(SqlError::Unsupported(
2219 "a second sort (SQL has a single ORDER BY)".into(),
2220 ));
2221 }
2222 let kids = self.arbor.children(s);
2223 // the options name the engine's collation
2224 // and its case order: no backend's (they
2225 // were dropped, and the SQL ordered as the
2226 // backend pleased)
2227 if let Some(&k) = kids
2228 .get(2..)
2229 .and_then(|rest| rest.iter().find(|&&k| self.kind(k) == "option"))
2230 {
2231 return Err(SqlError::Semantics(format!(
2232 "top({}) names the engine's collation; a backend's differs",
2233 self.prop_s(k, "name")
2234 )));
2235 }
2236 let n = self.prop_s(kids[0], "value");
2237 let e = self.operand(kids[1], join.map(|(l, _)| l))?;
2238 sel.order_by = Some((e, true));
2239 sel.limit = Some(n);
2240 }
2241 "unique" => {
2242 if self.strict {
2243 return Err(SqlError::Unsupported(
2244 "pushdown: DISTINCT result order is unordered in SQL".into(),
2245 ));
2246 }
2247 // Quarb dedups the limited rows; SQL
2248 // applies DISTINCT before LIMIT.
2249 if sel.limit.is_some() {
2250 return Err(SqlError::Unsupported(
2251 "'unique' after a positional selection (SQL applies \
2252 DISTINCT before LIMIT)"
2253 .into(),
2254 ));
2255 }
2256 if let Some(c) = pending_col.take() {
2257 sel.select = vec![c];
2258 }
2259 sel.distinct = true;
2260 }
2261 other => {
2262 return Err(SqlError::Unsupported(format!("the '{other}' aggregate")));
2263 }
2264 }
2265 }
2266 "select" => {
2267 if self.strict {
2268 return Err(SqlError::Unsupported(
2269 "pushdown: LIMIT without a guaranteed order".into(),
2270 ));
2271 }
2272 // `@| [..n]` → LIMIT.
2273 if sel.limit.is_some() {
2274 return Err(SqlError::Unsupported(
2275 "a second positional selection".into(),
2276 ));
2277 }
2278 let p = self.arbor.children(s)[0];
2279 match (self.prop_s(p, "kind").as_str(), self.prop(p, "to")) {
2280 ("range", Some(Value::Int(n)))
2281 if self.prop(p, "from").is_none() && n > 0 =>
2282 {
2283 sel.limit = Some(n.to_string());
2284 }
2285 _ => {
2286 return Err(SqlError::Unsupported(
2287 "positional selection beyond '@| [..n]'".into(),
2288 ));
2289 }
2290 }
2291 }
2292 other => {
2293 return Err(SqlError::Unsupported(format!(
2294 "the '{other}' command (windows, subcontexts, and registers are \
2295 Quarb-side state)"
2296 )));
2297 }
2298 }
2299 i += 1;
2300 }
2301 // A pending column with no aggregate is a one-column select.
2302 if let Some(c) = pending_col
2303 && sel.select.is_empty()
2304 {
2305 sel.select = vec![c];
2306 }
2307 // A grouped reduction never recorded (`@|{.k} count` with no
2308 // `| .n | %.`) answers one value per group: the aggregate
2309 // alone, grouped by the key.
2310 if let Some((_, agg, _)) = grouped
2311 && sel.select.is_empty()
2312 {
2313 sel.select = vec![agg];
2314 }
2315 Ok(())
2316 }
2317
2318 /// The column a pushed projection body names — `.k(::k)` is a
2319 /// subcontext whose one branch is the bare projection; any
2320 /// other body is Quarb-side state.
2321 fn pushed_column(&mut self, s: NodeId, qual: Option<&str>) -> Result<String, SqlError> {
2322 let body = || {
2323 let q = self.kid(s, "query")?;
2324 let b = self.kid(q, "branch")?;
2325 let p = self.kid(b, "projection")?;
2326 let bare = self.kids(q, "branch").len() == 1
2327 && self.kids(q, "pipeline").is_empty()
2328 && self.arbor.children(b).len() == 1
2329 && self.prop_s(p, "kind") == "property";
2330 bare.then_some(p)
2331 };
2332 let p = body()
2333 .ok_or_else(|| SqlError::Unsupported("a pushed body (Quarb-side state)".into()))?;
2334 let col = self.projection_col(p)?;
2335 let col = self.sql_ident(&col, "column name")?;
2336 Ok(match qual {
2337 Some(q) => format!("{q}.{col}"),
2338 None => col,
2339 })
2340 }
2341
2342 /// A HAVING filter: `$_` and `$.name` refer to the aggregate.
2343 fn having_cond(&mut self, s: NodeId) -> Result<String, SqlError> {
2344 let kids = self.arbor.children(s);
2345 if kids.len() != 1 || self.kind(kids[0]) != "compare" {
2346 return Err(SqlError::Unsupported(
2347 "HAVING translates for a single comparison".into(),
2348 ));
2349 }
2350 let e = kids[0];
2351 let op = self.prop_s(e, "op");
2352 let cmp_kids = self.arbor.children(e);
2353 let l = match self.kind(cmp_kids[0]).as_str() {
2354 "topic" | "recall" => "__AGG__".to_string(),
2355 _ => {
2356 return Err(SqlError::Unsupported(
2357 "HAVING compares the aggregate ($_ or its register)".into(),
2358 ));
2359 }
2360 };
2361 let r = self.operand(cmp_kids[1], None)?;
2362 Ok(format!("{l} {op} {r}"))
2363 }
2364
2365 /// `rec(...)` fields as a select list.
2366 fn record_fields(
2367 &mut self,
2368 s: NodeId,
2369 join: Option<(&str, &str)>,
2370 ) -> Result<Vec<String>, SqlError> {
2371 let kids = self.arbor.children(s);
2372 let mut fields = Vec::new();
2373 let mut i = 0;
2374 while i < kids.len() {
2375 let k = kids[i];
2376 if self.kind(k) == "literal" {
2377 let name = self.prop_s(k, "value");
2378 let value = self.operand(kids[i + 1], join.map(|(l, _)| l))?;
2379 let name = self.alias(&name)?;
2380 fields.push(format!("{value} AS {name}"));
2381 i += 2;
2382 } else {
2383 let value = self.operand(k, join.map(|(l, _)| l))?;
2384 fields.push(value);
2385 i += 1;
2386 }
2387 }
2388 Ok(fields)
2389 }
2390}
2391
2392fn sql_agg(name: &str, col: Option<String>) -> Result<String, SqlError> {
2393 let f = match name {
2394 "count" => "COUNT",
2395 "sum" => "SUM",
2396 "mean" | "avg" => "AVG",
2397 "min" => "MIN",
2398 "max" => "MAX",
2399 _ => unreachable!("checked by caller"),
2400 };
2401 match col {
2402 Some(c) => Ok(format!("{f}({c})")),
2403 // Only COUNT aggregates bare rows; SUM(*) and friends are
2404 // not SQL.
2405 None if f == "COUNT" => Ok("COUNT(*)".to_string()),
2406 None => Err(SqlError::Unsupported(format!(
2407 "'{name}' over row nodes (project a column first: '| ::col @| {name}')"
2408 ))),
2409 }
2410}
2411
2412#[cfg(test)]
2413mod null_and_literal_tests {
2414 use super::{Dialect, export, partial_pushdown, pushdown};
2415
2416 // Grouped pipeline that never pushes, so `partial_pushdown` hinges
2417 // only on the leading predicate (mirrors the crate's partial gate).
2418 const GROUPED: &str = " | ::x | .g(::x) @|{.g} count | .n | %.";
2419
2420 #[test]
2421 fn pattern_literal_pushes_as_like() {
2422 // Ruling #33: segments in order, a `%` per star, LIKE's
2423 // metacharacters escaped. Strict push only where LIKE is
2424 // provably case-sensitive (PostgreSQL); everywhere else the
2425 // pattern rides the scan.
2426 let q = "/users/*[::name == 'app-'*]::id";
2427 let p = pushdown(q, Some(Dialect::Postgres)).unwrap();
2428 assert_eq!(
2429 p.sql,
2430 "SELECT id FROM users WHERE name LIKE 'app-%' ESCAPE '\\'"
2431 );
2432 assert!(pushdown(q, Some(Dialect::Sqlite)).is_none());
2433 assert!(pushdown(q, Some(Dialect::MySql)).is_none());
2434 // contains and multi-segment shapes
2435 let p = pushdown("/users/*[::name == *'web'*]::id", Some(Dialect::Postgres)).unwrap();
2436 assert!(p.sql.contains("LIKE '%web%'"), "{}", p.sql);
2437 let p = pushdown(
2438 "/users/*[::name == *'a'*'.gz']::id",
2439 Some(Dialect::Postgres),
2440 )
2441 .unwrap();
2442 assert!(p.sql.contains("LIKE '%a%.gz'"), "{}", p.sql);
2443 // LIKE metacharacters in a segment are escaped
2444 let p = pushdown("/users/*[::name == *'50%_x'*]::id", Some(Dialect::Postgres)).unwrap();
2445 assert!(p.sql.contains("LIKE '%50\\%\\_x%'"), "{}", p.sql);
2446 // `!=` with a pattern rides the scan
2447 assert!(pushdown("/users/*[::name !== *'web'*]::id", Some(Dialect::Postgres)).is_none());
2448 // the `*=` alias gains the same PostgreSQL rung
2449 let p = pushdown("/users/*[::name *= 'web']::id", Some(Dialect::Postgres)).unwrap();
2450 assert!(p.sql.contains("LIKE '%web%'"), "{}", p.sql);
2451 assert!(pushdown("/users/*[::name *= 'web']::id", Some(Dialect::Sqlite)).is_none());
2452 }
2453
2454 #[test]
2455 fn json_column_path_pushdown_per_dialect() {
2456 // `[/col/a/b:: = 'lit']` navigates into a JSON column; each
2457 // dialect extracts the fixed path to text and compares.
2458 // Verified live against all five engines to match the graft.
2459 let q = "/orders/*[/data/meta/tier:: = 'gold']::id";
2460 let sql = |d| pushdown(q, Some(d)).unwrap().sql;
2461 assert_eq!(
2462 sql(Dialect::Postgres),
2463 "SELECT id FROM orders WHERE ((data::jsonb #>> '{meta,tier}') = 'gold')"
2464 );
2465 assert_eq!(
2466 sql(Dialect::MySql),
2467 "SELECT id FROM orders WHERE (JSON_VALID(data) AND \
2468 JSON_UNQUOTE(JSON_EXTRACT(data, '$.meta.tier')) = 'gold')"
2469 );
2470 assert_eq!(
2471 sql(Dialect::Sqlite),
2472 "SELECT id FROM orders WHERE (json_valid(data) AND \
2473 json_extract(data, '$.meta.tier') = 'gold')"
2474 );
2475 assert_eq!(
2476 sql(Dialect::Mssql),
2477 "SELECT id FROM orders WHERE (ISJSON(data) = 1 AND \
2478 JSON_VALUE(data, '$.meta.tier') = 'gold')"
2479 );
2480 assert_eq!(
2481 sql(Dialect::Oracle),
2482 "SELECT id FROM orders WHERE (JSON_VALUE(data, '$.meta.tier') = 'gold')"
2483 );
2484 // With no dialect, the JSON navigation is not pushable — it
2485 // falls back to the client-side graft.
2486 assert!(pushdown(q, None).is_none());
2487 }
2488
2489 #[test]
2490 fn json_pushdown_only_string_equality() {
2491 // Numeric comparison, `!=`, and a wildcard hop stay off the
2492 // pushdown path (they are not provably identical to the
2493 // graft), so they refuse and scan even with a dialect set.
2494 let d = Some(Dialect::Sqlite);
2495 assert!(pushdown("/o/*[/data/n:: > 2]::id", d).is_none());
2496 assert!(pushdown("/o/*[/data/tier:: != 'gold']::id", d).is_none());
2497 assert!(pushdown("/o/*[/data/items/*/sku:: = 'A1']::id", d).is_none());
2498 }
2499
2500 #[test]
2501 fn json_pushdown_refuses_numeric_looking_literal() {
2502 // value_eq coerces numeric-looking strings ('150' matches
2503 // the JSON number 150 and the string "150.0"); no engine's
2504 // extractor does, so the push would drop rows.
2505 let q = "/orders/*[/data/total:: = '150']::id";
2506 assert!(pushdown(q, Some(Dialect::Sqlite)).is_none());
2507 assert!(pushdown(q, Some(Dialect::Postgres)).is_none());
2508 }
2509
2510 #[test]
2511 fn partial_json_prefilters_sqlite() {
2512 // Exact string equality rides the strict gate.
2513 let p = partial_pushdown(
2514 "/orders/*[/payload/customer/geo/city:: = 'Lyon']::id",
2515 Some(Dialect::Sqlite),
2516 )
2517 .unwrap();
2518 assert_eq!(p.table, "orders");
2519 assert_eq!(
2520 p.where_sql,
2521 "(json_valid(payload) AND \
2522 json_extract(payload, '$.customer.geo.city') = 'Lyon')"
2523 );
2524 // Numeric comparison: typed compare, text values escape.
2525 let p = partial_pushdown(
2526 "/orders/*[/payload/total:: > 150]::id",
2527 Some(Dialect::Sqlite),
2528 )
2529 .unwrap();
2530 assert_eq!(
2531 p.where_sql,
2532 "(json_valid(payload) AND (json_extract(payload, '$.total') > 150 \
2533 OR json_type(payload, '$.total') = 'text'))"
2534 );
2535 // Bare existence.
2536 let p = partial_pushdown("/orders/*[/payload/gift]::id", Some(Dialect::Sqlite)).unwrap();
2537 assert_eq!(
2538 p.where_sql,
2539 "(json_valid(payload) AND json_type(payload, '$.gift') IS NOT NULL)"
2540 );
2541 // != floors at existence.
2542 let p = partial_pushdown(
2543 "/orders/*[/payload/status:: != 'x']::id",
2544 Some(Dialect::Sqlite),
2545 )
2546 .unwrap();
2547 assert_eq!(
2548 p.where_sql,
2549 "(json_valid(payload) AND json_type(payload, '$.status') IS NOT NULL)"
2550 );
2551 // A flipped literal flips the operator.
2552 let p = partial_pushdown(
2553 "/orders/*[150 < /payload/total::]::id",
2554 Some(Dialect::Sqlite),
2555 )
2556 .unwrap();
2557 assert!(p.where_sql.contains("> 150"), "{}", p.where_sql);
2558 // Without a dialect, JSON predicates stay on the engine.
2559 assert!(partial_pushdown("/orders/*[/payload/gift]::id", None).is_none());
2560 }
2561
2562 #[test]
2563 fn partial_json_prefilters_postgres() {
2564 let p = partial_pushdown(
2565 "/orders/*[/payload/total:: > 150]::id",
2566 Some(Dialect::Postgres),
2567 )
2568 .unwrap();
2569 assert_eq!(
2570 p.where_sql,
2571 "(CASE WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'number' \
2572 THEN ((payload::jsonb #>> '{total}'))::float8 > 150 \
2573 WHEN jsonb_typeof(payload::jsonb #> '{total}') = 'string' \
2574 THEN true ELSE false END)"
2575 );
2576 let p = partial_pushdown("/orders/*[/payload/gift]::id", Some(Dialect::Postgres)).unwrap();
2577 assert_eq!(
2578 p.where_sql,
2579 "(jsonb_typeof(payload::jsonb #> '{gift}') IS NOT NULL)"
2580 );
2581 }
2582
2583 #[test]
2584 fn partial_skips_untranslatable_keeps_prefix() {
2585 // A refused predicate no prefilter covers is skipped — the
2586 // shorter conjunction is still a superset (the engine
2587 // re-applies the original) — rather than aborting the plan.
2588 let p = partial_pushdown(
2589 "/orders/*[::status = 'shipped'][/payload/line_items/*/sku:: = 'X']::id",
2590 Some(Dialect::Sqlite),
2591 )
2592 .unwrap();
2593 assert_eq!(p.where_sql, "status = 'shipped'");
2594 }
2595
2596 #[test]
2597 fn null_literal_compares_use_is_null() {
2598 // `= null` / `!= null` are provably identical to Quarb's
2599 // value_eq(NULL, …) semantics, never the always-UNKNOWN
2600 // `x = NULL`; they translate — and push — in both modes.
2601 assert_eq!(
2602 export("/t/*[::x = null] | ::x").unwrap().query,
2603 "SELECT x FROM t WHERE x IS NULL"
2604 );
2605 assert_eq!(
2606 export("/t/*[::x != null] | ::x").unwrap().query,
2607 "SELECT x FROM t WHERE x IS NOT NULL"
2608 );
2609 assert_eq!(
2610 pushdown("/t/*[::x = null] | ::x", None).unwrap().sql,
2611 "SELECT x FROM t WHERE x IS NULL"
2612 );
2613 assert_eq!(
2614 pushdown("/t/*[::x != null] | ::x", None).unwrap().sql,
2615 "SELECT x FROM t WHERE x IS NOT NULL"
2616 );
2617 }
2618
2619 #[test]
2620 fn ne_and_not_refuse_pushdown_but_display_diverges() {
2621 // `!=` against a non-null value and `not(...)` drop the NULL
2622 // rows Quarb keeps under SQL three-valued logic: the pushdown
2623 // paths refuse (and scan), full and partial alike.
2624 assert!(pushdown("/t/*[::x != 5] | ::x", None).is_none());
2625 assert!(pushdown("/t/*[!::x = 5] | ::x", None).is_none());
2626 assert!(partial_pushdown(&format!("/t/*[::x != 5]{GROUPED}"), None).is_none());
2627 assert!(partial_pushdown(&format!("/t/*[!::x = 5]{GROUPED}"), None).is_none());
2628 // The display translation still emits `<>`, flagged with a note.
2629 let t = export("/t/*[::x != 5] | ::x").unwrap();
2630 assert_eq!(t.query, "SELECT x FROM t WHERE x <> 5");
2631 assert!(t.notes.iter().any(|n| n.contains("NULL")));
2632 }
2633
2634 #[test]
2635 fn unescapable_text_literal_refuses_pushdown() {
2636 // A backslash (MySQL/BigQuery escape) or an apostrophe
2637 // (BigQuery rejects '' doubling) has no portable escaping, so
2638 // pushdown refuses; a clean literal still pushes.
2639 assert!(pushdown("/files/*[::path = \"C:\\temp\"] | ::path", None).is_none());
2640 assert!(pushdown("/t/*[::name = \"it's\"] | ::name", None).is_none());
2641 assert!(partial_pushdown(&format!("/t/*[::name = \"it's\"]{GROUPED}"), None).is_none());
2642 assert_eq!(
2643 pushdown("/t/*[::name = \"rare\"] | ::name", None)
2644 .unwrap()
2645 .sql,
2646 "SELECT name FROM t WHERE name = 'rare'"
2647 );
2648 }
2649}