catalog run-cached

Compose and execute catalog entries with a parquet cache wrapper.

Same semantics as xorq catalog run, but wraps the resulting expression with a cache so subsequent invocations short-circuit when inputs haven’t changed (ParquetCache by default; snapshot and TTL variants via --cache-type and --ttl—see xorq run-cached for the strategies).

Usage

xorq catalog run-cached [ENTRIES]... [OPTIONS]

Arguments

  • ENTRIES—One or more entry names or aliases.

Options

Option Default Description
-c, --code none Inline Ibis code expression applied to source.
-o, --output-path /dev/null (discard) Path to write output. Use ‘-’ for stdout.
-f, --format parquet Output format.
--limit unlimited Maximum number of rows to output.
-i, --instream stdin Stream to read Arrow IPC record batches from.
--fuse / --no-fuse --fuse Enable catalog source fusion.
--rename-params none Rename a parameter on a specific entry: entry,old_name,new_name (repeatable).
-p, --params none Override an expression parameter as key=value (repeatable, for example –params threshold=0.5).
--cache-dir $XORQ_CACHE_DIR or ~/.cache/xorq Directory for parquet cache files.
--cache-type modification-time Cache strategy: ‘modification-time’ (ParquetCache) or ‘snapshot’ (ParquetSnapshotCache).
--ttl none TTL in seconds for snapshot cache (uses ParquetTTLSnapshotCache when set).
--use-this-venv / --no-use-this-venv --no-use-this-venv Execute in the current Python environment instead of spawning uv tool run on the entry’s pinned env. Faster (no subprocess + uv venv lookup) but only correct when the calling venv already has every package the expression needs (Xorq itself plus any UDFs from the entries’ wheels). Default is the isolated uv tool run path.

Examples

# Default modification-time cache
xorq catalog run-cached src trn --cache-dir ./cache -o results.parquet
# Snapshot cache with a 1-hour TTL
xorq catalog run-cached pipeline --cache-type snapshot --ttl 3600 -o results.parquet

See also