Refresh
Refresh
The refresh command automatically detects and refreshes stale derived assets. It parses each script, identifies datasources marked root (source of truth), compares watermarks to find stale derived assets, and refreshes them.
Usage
trilogy refresh [input] [dialect] [options] [conn_args...]
Arguments
| Argument | Description |
|---|---|
input | Path to a Trilogy script or directory. |
dialect | Database dialect. Optional - falls back to engine.dialect in trilogy.toml. |
conn_args | Connection arguments, as key value pairs or key=value tokens. |
Options
| Option | Description |
|---|---|
--param key=value | Environment parameters. Repeatable. |
-p, --parallelism INTEGER | Maximum parallel workers for directory execution. |
--config PATH | Path to a trilogy.toml configuration file. |
--print-watermarks | Print watermark values for all datasources before refreshing. |
-e, --env TEXT | Set env vars as KEY=VALUE, or pass an env file path. |
-f, --force TEXT | Force rebuild of specific datasources by name, skipping staleness detection. |
-i, --interactive | Show the refresh plan and prompt for approval before applying changes. |
-n, --dry-run | Show the SQL that would be executed without running it. |
Exit Codes
| Code | Meaning |
|---|---|
0 | Assets were refreshed. |
2 | Everything was already up to date. |
1 | An error occurred. |
The distinction between 0 and 2 lets a scheduler tell "did work" apart from "nothing to do" without parsing output.
Full Examples
# Refresh assets in current directory
trilogy refresh . duckdb
# Refresh a specific script
trilogy refresh etl_pipeline.preql postgres host=localhost database=shop username=app password=secret
# Refresh with parallelism
trilogy refresh jobs/ snowflake -p 4 account=myaccount username=app password=secret
# See what would happen first
trilogy refresh . duckdb --dry-run
# Inspect watermarks before deciding
trilogy refresh . duckdb --print-watermarks
# Rebuild one datasource regardless of staleness
trilogy refresh . duckdb --force daily_sales
# Approve the plan interactively
trilogy refresh . duckdb --interactive
What It Does
- Parses each script in the input path
- Identifies datasources marked as
root(source of truth) - Compares watermarks to find stale derived assets
- Refreshes any stale assets by re-running their derivation logic
- Runs any validation statements after refresh
Notes
- Use this to keep derived assets up to date automatically
- Can be used in place of explicit refresh/update scripts
- Only refreshes assets that are actually stale