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. |
--skip-validation TEXT | Skip assertions for named datasources for this refresh. Repeatable; accepts comma-separated names. |
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
- Builds stale assets, evaluates their datasource assertions, and publishes successful builds
- 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
Build Assertions
Datasource assert clauses can check absolute row counts or compare a build with the previous asset using prior(...). A failing check prevents the checked build from replacing the published asset. --dry-run lists the assertions without evaluating them.
For a deliberate population change, skip the named datasource's assertions for one refresh:
trilogy refresh reporting.preql --force daily_sales --skip-validation daily_sales
The override is logged and recorded in the run report. An unknown datasource, or one with no assertions, is rejected. This skips assertion checks, not all parsing or validation; the next refresh uses the newly published baseline.