build
Compile a Xorq expression into a reusable build artifact.
Loads the script, finds the expression variable, and writes serialized artifacts (expression YAML, backend profiles, deferred reads, and metadata) to the builds directory. Execute the artifact later with xorq run, or add it to a catalog with xorq catalog add.
Usage
xorq build SCRIPT_PATH [OPTIONS]Arguments
SCRIPT_PATH—Path to the Python script that defines the expression.
Options
| Option | Default | Description |
|---|---|---|
-e, --expr-name |
expr |
Name of the expression variable in the Python script. |
--builds-dir |
builds |
Directory for all generated artifacts. |
--cache-dir |
$XORQ_CACHE_DIR or ~/.cache/xorq |
Directory for parquet cache files. |
--debug |
off | Output SQL files and other debug artifacts. |
--relocate-reads / --no-relocate-reads |
--relocate-reads |
Bundle local-file Read nodes into the build so it is self-contained and runnable from anywhere. Remote reads (s3://, gs://, …) are already location-independent and left in place. Pass –no-relocate-reads for a lean, machine-local build; this only affects reads not already bundled – relocation discards a read’s original path, so it cannot be undone by a later –no-relocate-reads on an already-relocated input. |
--emit-build-path-to |
none | Write the resulting build directory path to this file. Use when stdout may be polluted (for example by OTel console fallback) and a subprocess consumer needs the path unambiguously. |
Examples
# Build the expression named `expr` (the default)
xorq build pipeline.py
# Build a specific expression into a custom directory
xorq build pipeline.py -e daily_metrics --builds-dir artifactsSee also
run—execute a build artifactuv build—same semantics, inside a uv-managed environmentcatalog add—add a build to a catalog