Source Freshness Check

A source freshness check tests whether an input table has been loaded recently enough to be worth building on. It is the automated version of the question “did the data arrive?”, and it runs before the transformation rather than after someone notices the report has not moved. Mechanics below follow dbt’s documentation, checked in September 2026, which frames freshness checks as telling you whether your data pipelines are in a healthy state and as an input to defining service level agreements.

How it works

The source declares which column records when a row was loaded, plus two thresholds — one that warns and one that fails. The tool then compares the newest value in that column against the current time. dbt builds a query of essentially this shape:

select max(_etl_loaded_at) as max_loaded_at,
       current_timestamp   as calculated_at
from raw.jaffle_shop.orders;

If the gap exceeds the warn threshold, the check warns; past the error threshold, it fails, and the run that depends on it can be stopped before it produces a confident-looking build of yesterday’s numbers. Thresholds can be set per source and overridden per table, and a table that genuinely does not change can opt out.

Choosing the thresholds and the column

• Work backwards from the deadline. If a report is due at 08:00 and the build takes 40 minutes, an input that has not arrived by about 07:00 is already a problem — that gap is the threshold, not a round number chosen by habit.
• Use a load timestamp, not an event timestamp. The column should say when the row landed in the warehouse. A business event time answers a different question and can look fresh while the pipeline is stopped, or look stale on a quiet weekend.
• Separate warn from error deliberately. The warn level is for “someone should look”; the error level is for “do not build on this.” Setting them equal throws away the distinction.

What it does not catch

A freshness check answers exactly one question: how long ago was something loaded. It says nothing about how much was loaded or whether it is correct. A run that delivered one row of a normal ten thousand passes; so does a load of correctly timed garbage. Volume checks, row-level assertions, and reconciliation against the source cover those, and a freshness check is the cheapest of the four rather than a substitute for them.

The underlying property being measured — and how to state a target for it — is covered in data freshness. How the check fits alongside logic tests and output assertions is worked through in Transformation as Code.

References: dbt Documentation, Add sources to your DAG.