Define sources in a sources.yml file under a models directory: specify the database, schema, tables, and optionally a loaded_at_field (a timestamp column indicating when each row was loaded) for each source table you want to monitor
Add freshness constraints under each source table: freshness: warn_after: {count: 12, period: hour} and error_after: {count: 24, period: hour}; these thresholds determine when dbt source freshness reports warn or error status
Run dbt source freshness from the CLI: dbt source freshness --select source:<source_name>; dbt queries the max(loaded_at_field) for each table and compares it to the current timestamp, then outputs warn/error/pass status
Integrate into CI by adding dbt source freshness as a step before dbt build in your pipeline YAML; exit on error status so the pipeline fails if sources are stale before model runs begin
For alerting, parse the freshness output file (target/sources.json) in CI and send notifications (Slack, PagerDuty) based on source status; or use dbt Cloud's built-in source freshness alerting if running on dbt Cloud
Known gotchas
The loaded_at_field must be a timestamp column present in the source table; if the source table lacks a reliable ingestion timestamp, you must add one in the ingestion pipeline or choose a proxy column (like a created_at field) that approximates freshness
dbt source freshness queries run against your warehouse and can be expensive if the source tables are very large; ensure the loaded_at_field is indexed or partitioned so the MAX() query is fast
Source freshness checks are separate from dbt tests; failing source freshness does not automatically block dbt run unless you explicitly fail the pipeline on non-zero exit codes — by default dbt source freshness exits 0 even on error-level staleness in some versions, so always check the sources.json output
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp