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 aNOTis 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 andHAVINGa 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 JOINisLEFTwith the tables’ places exchanged;CROSS JOINis every pair. The ON is any condition.UNION ALLof single columns of different tables → a branch union,/t/*::a || /u/*::b;UNIONthe same and@| unique.ORDER BY→@| sort_by(…)(DESCvia@| 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.
LIKEtranslates to a case-insensitive regex (matching MySQL’s and SQLite’s default folding; PostgreSQL’sLIKEis case-sensitive).ORDER BYputs a NULL key last, first underDESC, as PostgreSQL does; SQLite and MySQL put it first.
Structs§
- Column
Types - The column types a pushed plan assumes (see
Pushdown::column_types). - Float
Sum - A pushdown plan: SQL whose execution is provably identical to
the Quarb query’s — plus the table whose primary key must order
the rows (
Nonefor a single aggregate row, where order is moot). The driver appends theORDER BY, since the key lives in its catalog. A sum or a mean over a column, as a plan’s statement writes it (text:SUM(unit_price)). The engine adds a float column by the careful sum, in key order; SQLite adds the same way, and its SUM is the engine’s to the last digit. PostgreSQL and DuckDB add plainly and across workers, in no fixed order, so a float sum there moves in its last digits from one run to the next: their doors ask the catalog whether the column is a float and rewrite the sum in the dialect’s ordered form (sum(x ORDER BY key)), which is the same number every run. The plan says which sums it holds; the door does the rest. - 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
- 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 (
SortisSORT_NOT_PUSHED; ruling 2026-11-17, one word per reason whereNOT_PUSHEDwas 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
SELECTstatement. - partial_
pushdown - Attempt a partial pushdown:
Somewhen 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-rowswould lie). - partial_
pushdown_ explained partial_pushdown, keeping the refusal reason.dialectenables 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_explainedfor 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:
Someonly when every construct in the query is in the verified-safe set. Anything else — including everythingexportwould merely annotate with a divergence note — returnsNone, 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
SELECTstatement to a Quarb query.
Type Aliases§
- Column
Fact - One column of a source’s catalog, as a plan’s assumptions are
held against it: its name; whether its type is numeric; whether
it is declared json; and whether the database compares its text
exactly, by characters, case and trailing spaces included (false
for a
char(n)of PostgreSQL, which ignores the padding it answers with, and for a column of SQLite declared under a collation).