Manual
Programming guide
Using Relix from Java — building queries, inspecting what the engine makes of them, and running them — and from the shell, with the relix command.
Using Relix from Java: building queries, inspecting what the engine makes of them, and running them. Every Java example in this guide is compiled against the shipped API and run on each build, and the block underneath it holds what it actually printed. An example that stops compiling, or stops printing what its page claims, fails the build — so a page here cannot quietly fall behind the code it describes. Imports are elided where they are noise and shown where they are the point. This guide is about the Java API. The language itself — every operator, predicate and function, with worked examples — is the subject of the other manual, the Relix language reference. The two share one vocabulary: each combinator on a relation is named exactly as the reference names the operator, so a question about what an operator means is answered there.
Introduction
Where to start: how to get the library onto a classpath, then one page that opens a session, gets data in, writes a query both ways, runs it, and looks at what the engine did with it.
| Page | What it covers |
|---|---|
| Getting the library | The artifact and its coordinate; Java 21; adding a JDBC driver; checking what a session found |
| Getting started | The session and the relation; Java data in; the two authoring surfaces; the row terminals; the optimizer and the plan; errors |
| The session | Declaring, running a script, reading a session back, diagnostics, what a session can be given, closing |
Building a query
One method per operator, named as the language reference names it — and the language itself wherever an expression reads better as text.
| Page | What it covers |
|---|---|
| Composing a query | The two authoring surfaces; parameters; the unary operators; joins; set operations; universal quantification; building an AST directly |
| Aggregation and analytics | Grouping and reducing; NULL rules; ranking, running totals and offsets; top n per group; pivot |
| Recursion and graphs | Reachability, components, paths, cheapest routes, general recursion, and the safety valve |
| Time | Temporal types; binding a moment; the AS-OF join and its boundaries; interval joins; SESSIONIZE; DOWNSAMPLE |
| Goal-seek and optimisation | SOLVE; subset selection and allocation with OPTIMIZE; solved, infeasible and undetermined; checking for a solver |
| Nested data | Struct and array construction; COLLECT and UNNEST as inverses; TREE; declaring a nested schema and what it types |
Getting data in
| Page | What it covers |
|---|---|
| Bringing your own data and code | Rows held, rows produced per scan, a connector of your own, a function library of your own |
| Generating data | Generator relations and their bounds; COVER and all-pairs suites; seeded sampling and what a seed buys |
| Against a database | Binding a DataSource, introspection, what is pushed down and what is not, joining your data to theirs, connection lifecycle, and what a federated query does not promise |
| Secrets in declarations | ${NAME} placeholders resolved when a query runs, so a token never enters the model; a missing value; declarations built in Java |
| Sandboxing a session | A closed sandbox for untrusted text: internal declarations only, external ones the sandbox permits, output and input limits, the configuration file |
| Working without a database | What composes offline; unresolved names; capturing a catalog snapshot and replaying it |
Getting answers out
| Page | What it covers |
|---|---|
| Reading results | The terminals and who closes what; typed row accessors; nested values; streaming; running the tree as written; what a drained read teaches the engine |
| Looking at what the engine did | Rendering, the rewrite and why it fired, the physical plan and its estimates, the session's own report |
| The engine describes itself | The relix.* catalogs as relations: what is installed, what the session knows, dependencies, functions, and the last run's feed |
| Provenance: where a row came from | Lineage as a column; annotating a relation over a semiring; which to reach for |
Building tools
| Page | What it covers |
|---|---|
| Building tools on Relix | Parsing a script and loading imports; tokens for syntax highlighting; learning the joins a user writes and resolving them; the language reference; connectors and drivers |
The command line
Installing it, and the shape every command shares; then data in, rows out.
| Page | What it covers |
|---|---|
| The relix command | Installing; a first query; where the script comes from; the commands; diagnostics and exit status |
| Binding inputs | -i and its formats; standard input; inferred and given headings; inputs that never end; shadowing the catalog; query parameters with -a |
| Output formats | table, tsv, csv, ndjson, json and markdown; NULLs and headers; scripts with several queries; --fail-empty and --fail-rows; messages; closed pipes and interrupts |
Projects on the command line
What a directory gives the commands run in it.
| Page | What it covers |
|---|---|
| The catalog | .relix/ directories and how they are found; trusting a project; a nearer declaration wins; inspecting the catalog; --catalog; relixrc |
| Secrets and profiles | ${NAME} placeholders; profiles.json and -P; the environment and -D; private profile files; what is never printed |
Command-line recipes
| Page | What it covers |
|---|---|
| Pipelines | With jq, awk, sort and head; another program's output as a table; one relix into another; tee; with find, xargs and shell loops; scripts in here-documents; data checks in CI, comparing snapshots, and a GitHub Actions workflow; optimising a script and reviewing the change |
Command reference
One page per command: what it does, its usage, arguments and options, its exit status, and examples.
| Page | What it covers |
|---|---|
relix | The global options every command takes; the exit statuses; the environment variables and files |
relix run | Runs scripts and writes their queries' rows |
relix check | Analyses scripts without running them, and reports their problems |
relix explain | Prints each query's physical plan |
relix optimize | Prints the script with each query rewritten by the optimiser |
relix trace | Runs each query and prints what the engine rewrote, planned and ran |
relix bundle | Prints each script's JSON bundle of diagnostics, plans and events |
relix ir | Prints the symbols, views and queries the analyser made of a script |
relix provenance | Runs each query and annotates each row with where it came from |
relix fmt | Prints scripts canonically, keeping their comments |
relix catalog | Lists the catalog's files, relations, columns and declarations; trusts a project |
relix drivers | Lists and installs JDBC drivers |
relix connectors | Lists and installs connector plugins |
relix doc | Shows a page of the language reference |
relix help | Prints a command's usage |
relix version | Prints the versions of the command and of the engine |
relix completion | Prints a completion script for bash, zsh, fish or PowerShell |