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