Home / Documentation / Python prototype

Python prototype

The Python package (unsequel 0.1.0) runs the canonical .unsequel language through a ported front-end, analyzer, and code generator — on a built-in in-memory engine or DuckDB. The ordered .usql and pipeline .pusql dialects are legacy prototypes retained for comparison and are being retired; new users should start with the compiler.

Install and run

git clone https://github.com/absterjr/UNSeQueL.git
cd UNSeQueL
python -m pip install -e .
python -m unsequel run examples/revenue.usql --data orders=examples/orders.csv

Requires Python 3.10+. In a virtual environment or pipx the console script is unsequel-python; python -m unsequel is the portable form used in the docs.

Ordered surface (`.usql`)

Clause names from SQL, written in execution order. FROM and SELECT are required and the clause order is enforced.

FROM orders
WHERE quantity > 0
GROUP BY country
HAVING COUNT(*) > 1
SELECT country, SUM(quantity * unit_price) AS revenue
ORDER BY revenue DESC
LIMIT 10

The ordered core covers CTEs, nested sources, joins (inner/left/right/full/cross), UNION/INTERSECT/EXCEPT, and a SQLite input adapter, and it is deliberately dependency-free. It has no native window stage; use the sql hatch for window functions in this surface.

Pipeline surface (`.pusql`)

One stage per line; where is position-sensitive (row vs group) and group combines keys with aggregates.

from orders
derive total = quantity * unit_price
group country (revenue = SUM(total), orders = COUNT(*))
sort -revenue

python -m unsequel run examples/pipeline/revenue.pusql --pipeline \
  --data orders=examples/orders.csv

With a schema file, the pipeline can be validated, compiled to DuckDB SQL (one CTE per stage), and stepped through stage by stage with check, compile, and preview.

Differences from the compiler

Area	Prototype	Compiler (`.unsequel`)
Row / group filters	Position-sensitive `where`	Explicit `filter` and `having`
Grouping	`group keys (aggs)` combined	Split `group by` + `aggregate`
Windows	`sql` hatch	Native `window` stage, including `over ()`
Set operators	In the ordered surface; `union` etc. in `.pusql` backlog	`union`/`union all`/`intersect`/`except` stages
Engine	In-memory executor or optional DuckDB	DuckDB only
Identifiers	Unquoted or SQLite-style	Unquoted or backtick-quoted

Do not copy examples between the surfaces; the dialects differ (see the repository README's map of the three surfaces).

CSV options and engines

python -m unsequel run customer.usql \
  --data customers=customers.csv --delimiter ';' \
  --column-type customers.postal_code=text

The prototype applies the same whole-column inference rules as the compiler (leading-zero identifiers stay text, literal null/none/nan stay strings) and supports --delimiter and --column-type. run --engine duckdb executes the generated SQL against DuckDB when the duckdb extra is installed; the default memory engine is dependency-free. Semantics and known engine differences are documented in the repository's docs/semantics.md.