Skip to main content

Crate quarb_sql

Crate quarb_sql 

Source
Expand description

SQL importer for Quarb.

Translates a SQL SELECT statement into an equivalent Quarb query, following the mapping in the SQL cookbook — in reverse. The translatable subset covers the single-statement query core; everything else is refused with an SqlError::Unsupported naming the construct, never silently approximated.

  • SELECT cols FROM t → /t/* | %(::col; …); SELECT * → the row nodes; SELECT DISTINCT col → /t/*::col @| unique, and over several columns the records, | %(…) @| unique.
  • WHERE → a predicate that holds exactly where SQL finds the condition TRUE. SQL’s logic has a third value for a comparison with a NULL, so <> is guarded (::x != null && ::x != "GB") and a NOT is carried inward to the comparisons; IS [NOT] NULL → = null / != null; [NOT] IN (…) → a chain of equalities; [NOT] LIKE → a regex, % a run of characters and _ one.
  • Aggregates (COUNT(*), SUM/AVG/MIN/MAX) → @| reductions over the piped column, COUNT(col) → count(--values); GROUP BY k → | .k(::k) @|{.k} with the aggregate folding by the pushed key and HAVING a filter after it.
  • JOIN t2 ON … → the every-witness correlation, one thread for every pair as SQL has one row: /t1/* <=>* /t2/*[::b = $$0::a], the FROM table driving, the ON in the joined expression’s bracket, the joined side’s columns read through the witness ($$1::col). LEFT JOIN → <=>*?, which keeps a driver with no pair, its WHERE a filter after the join; RIGHT JOIN is LEFT with the tables’ places exchanged; CROSS JOIN is every pair. The ON is any condition.
  • UNION ALL of single columns of different tables → a branch union, /t/*::a || /u/*::b; UNION the same and @| unique.
  • ORDER BY → @| sort_by(…) (DESC via @| reverse); LIMIT n → @| [..n].

Refused: subqueries, window functions, CASE, a FULL join, multi-join chains (one JOIN translates), SELECT * over a join, UNION ALL over one table twice (a branch union keeps one thread for a node two branches reach), a comparison with a NULL literal, HAVING without GROUP BY, aggregate arithmetic (SUM(a) + 1), and any non-SELECT statement.

Each translation is held against SQLite’s own answer over one database (the differential rig of tests/sql.rs). What differs between SQL engines themselves is reported as a Translation::notes line rather than refused:

  • Quarb streams records (JSONL), not a result table.
  • LIKE translates to a case-insensitive regex (matching MySQL’s and SQLite’s default folding; PostgreSQL’s LIKE is case-sensitive).
  • ORDER BY puts a NULL key last, first under DESC, as PostgreSQL does; SQLite and MySQL put it first.

Structs§

ColumnTypes
The column types a pushed plan assumes (see Pushdown::column_types).
Partial
A partial-pushdown plan: the leading row predicates as a WHERE clause for table’s fetch. The caller runs the original query against the filtered adapter — the engine re-applies the pushed predicates (a no-op on pre-filtered rows), so no rewriting.
Pushdown
A pushdown plan: SQL whose execution is provably identical to the Quarb query’s — plus the table whose primary key must order the rows (None for a single aggregate row, where order is moot). The driver appends the ORDER BY, since the key lives in its catalog.
Translation
A successful translation: the Quarb query, plus notes on known semantic divergences that apply to it.

Enums§

Dialect
The target SQL dialect, for the one construct whose emitted SQL is not portable: a filter that navigates into a JSON column, which each engine extracts with its own operator. The rest of a pushdown is dialect-agnostic. A query with no JSON-column filter emits identical SQL regardless of dialect.
Refusal
Why the exporter leaves a part of a Quarb query to the engine: the first word of the diagnostic code a planner’s refusal is told under (Sort is SORT_NOT_PUSHED; ruling 2026-11-17, one word per reason where NOT_PUSHED was the one kind). The word names what the user wrote; the inventory (langspec/diagnostics.tsv) files each under its remedy.
SqlError
An error translating a SQL statement.

Functions§

export
Translate a Quarb query to a SQL SELECT statement.
partial_pushdown
Attempt a partial pushdown: Some when the query’s leading row predicates translate strictly and the rest of the query provably cannot observe the filtering. The gates, each with its reason: a single /table/* branch with no correlations (other shapes address other data); only the leading run of expression predicates pushes (a positional predicate before an expression one sees unfiltered rows on the scan path); the table’s name appears exactly once among the query’s steps (a second reach — ^-anchored subcontexts, self-references — would see the filtered subset); no crosslink or resolution axes anywhere (backlinks and reverse resolution into the table would too); and no : / ::: metadata anywhere (a filtered :::n-rows would lie).
partial_pushdown_explained
partial_pushdown, keeping the refusal reason. dialect enables the JSON-column prefilters — the strict fixed-path string equality, plus the relaxed superset forms (numeric comparisons, existence) that are safe here and only here, because the caller re-runs the original query over the fetched subset.
partial_pushdown_keyed
partial_pushdown_explained for an adapter that reads steps by key and filters only the table’s listing (RelationalModel::with_filtered_listing): crosslinks and resolutions no longer refuse the prefilter, since a step into the filtered table reads its row unfiltered. What still refuses: a second navigation into the table, and a <-- or => scope that could list it.
pushdown
Attempt the pushdown translation: Some only when every construct in the query is in the verified-safe set. Anything else — including everything export would merely annotate with a divergence note — returns None, and the caller scans.
pushdown_explained
pushdown, keeping the refusal: the error names the first construct that kept the query on the scan path.
translate
Translate one SQL SELECT statement to a Quarb query.