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	off	Bundle all local-file Read nodes into the build artifact.
--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 artifacts

See also

• run—execute a build artifact
• uv build—same semantics, inside a uv-managed environment
• catalog add—add a build to a catalog