#SEL and SQL — reference

The SQL layer translates a compiled SEL program for a database. It is a second reader of the same syntax tree the evaluator runs — nothing about how a program evaluates changes. This page is the reference; SQL conditions and SQL pipelines are the guided tour, and the design document is the full contract.

• What it produces
• Dialects
• Entry points
• Fragments
• Bindings
• Kinds, guards and strict mode
• Refusals
• Caveats
• Your own functions
• Extending the map
• Loading the SQL layer

#What it produces

Four properties hold throughout:

1. The map is data. Every SQL spelling is authored once, in sql/dialects/*.json, and generated into every host. No host has an opinion of its own about what UPPER becomes.
2. Refusal is a result. What cannot be expressed faithfully is refused whole, before any SQL is written, with a code saying why.
3. Output is deterministic. The same program, dialect and bindings give the same bytes in every host — sql/cases/*.sqlt asserts the exact strings.
4. Variables become schema. The application says where each name lives, not what it holds.

#Dialects

A base cannot be translated for (E_SQL_DIALECT); it exists to be inherited. Lookups walk the chain key by key. Sql.dialects() lists the targets, including any the application registered.

#Entry points

p is a compiled program, d a dialect name, b the bindings. An optional fourth argument carries options: strict (below) in every host, and in the three dynamic hosts the logical optimiser's fuseFilters and foldConstants, which the planner forwards. The planner is the only entry point that optimises; translate and translate_statement render the program as written.

A plan exposes pure_sql, pure_memory and is_hybrid (each host spells them its way), the sql_statement fragment, the continuation_program that runs in memory over _INPUT, and source_tables — the physical tables the SQL side reads.

#Fragments

What translate and translate_statement return.

mode is inline (literals written into the SQL, escaped for the dialect — for reading and for statements built once) or params (every text and binary literal a placeholder, numbers inlined — what a driver should get). The placeholder is ? in every shipped dialect; a derived dialect can number them (Extending the map).

#Bindings

Built by constructors, in code — never decoded from a document, so a malformed binding is impossible to construct rather than something to detect. Each host spells them its own way (Binding.column / Binding::column / sel.sql:binding-column); the arguments are the same.

A column or raw binding takes flags that describe the column honestly and make the SQL tighter:

The choice between columns and relation is the most consequential one: the same ALL(V, _ > 0) becomes an AND over three columns of the current row, or a NOT EXISTS over another table. Only the application knows which the schema has.

#Kinds, guards and strict mode

The translator infers a kind for every node. A declared type is what it starts from; UNKNOWN costs something in each position:

• where a boolean is required (AND, NOT, an IF condition, a condition fragment), an UNKNOWN operand is refused — no dialect can be asked whether a column is boolean;
• as an arithmetic or comparison operand, it is wrapped in the dialect's numeric guard, so a value SEL would refuse becomes NULL rather than a number the server invented (CASE WHEN col REGEXP '…' THEN CAST(col AS DECIMAL) END on MariaDB). SQLite cannot test whether text is a number, so there the rule is refused;
• text comparisons are always rendered under a binary collation (COLLATE "C", utf8mb4_nopad_bin, COLLATE BINARY), because SEL compares bytes — unless the binding says exact.

strict: true refuses every translation that would carry a caveat, for the applications that want exact or nothing.

#Refusals

A refusal is an exception of the SQL error class with a code, a message and the position of the SEL node responsible; try_* returns nothing instead.

sql/errors.md is the normative list. A registration mistake — a malformed dialect or entry — is the host's own start-up error, never an SQL error, so try_translate cannot swallow it.

#Caveats

A caveat marks a spelling that is mapped but not exact. The vocabulary is closed, so an application can branch on it:

An empty caveats list is the layer's promise that the fragment means exactly what the program means — a promise tools/check-sql-oracle.sh tests against real servers.

#Your own functions

A function the application registered (spec §8.1) has no SQL until the application gives it a spelling for a dialect — a call to a database function, a stored function, or an inline expression — with the same define that respells a builtin. Your own functions, in SQL is a worked example with PostgreSQL stored functions in all five languages; sql/MAP.md §4.7 is the contract.

args — one per position, ANY past the end:

The application promises that the spelling computes what its function computes; nothing else can. Run the rules both ways over real data and compare — the examples do, on every run.

#Extending the map

At run time, an application can register a dialect of its own that extends a shipped one — for a driver that wants numbered placeholders, a server version with a missing function, an extension that adds one — and can respell, withdraw or add a builder for any of SEL's own functions. Only the difference is written; everything else is inherited. Extending SEL shows it in all five languages. A permanent addition to a shipped dialect is a change to sql/dialects/*.json, followed by node tools/gen-sql-map.mjs; the format is sql/MAP.md.

#Loading the SQL layer

The SQL layer is opt-in, so an application that only evaluates does not load a dialect map: from sel.sql import … in Python, sel-lang/sql in JavaScript, php/src/Sql/bootstrap.php in PHP, sel_sql.hpp and sel_sql*.cpp in C++, and the sel-lang/sql system in Lisp.