Skip to main content

dbt freshness Beta

The dbt freshness command evaluates whether sources and models with freshness configured meet your warn_after and error_after thresholds, reporting warnings and errors accordingly.

Usage​

dbt freshness [--select SELECTOR] [--resource-type RESOURCE_TYPE] [--exclude-resource-type RESOURCE_TYPE]

Run freshness for all sources and models​

dbt freshness

Include or exclude resource types​

Use the flag to specify which resource type you want to include or exclude when running the command:

# Include sources only
dbt freshness --resource-type source

# Include models only
dbt freshness --resource-type model

# Exclude sources only
dbt freshness --exclude-resource-type source

Select specific model or source​

Use --select to specify which model or source you want to include when running the command:

# Select a specific model 
dbt freshness --select stg_orders

# Select all sources in a namespace
dbt freshness --select "source:jaffle_shop"

# Select a specific source table
dbt freshness --select "source:jaffle_shop.orders"

How freshness is evaluated​

dbt freshness evaluates sources or models that have warn_after or error_after set in their freshness config.

dbt retrieves the latest timestamp using one of the following methods, then compares it with the current timestamp to determine the age of the data.

MethodWhen usedHow dbt retrieves the timestamp
loaded_at_queryWhen configured on the resourceRuns the custom SQL expression to retrieve the latest timestamp.
loaded_at_fieldWhen configured on the resourceQueries MAX(<loaded_at_field>) against the materialized relation.
Adapter metadataWhen neither loaded_at_query nor loaded_at_field is configuredRetrieves the last-modified time from adapter relation metadata. Available for sources, and for models materialized as table, incremental, materialized_view, or dynamic_table, where supported by the adapter. Models materialized as view or external must use either loaded_at_field or loaded_at_query.

You can't configure both loaded_at_query and loaded_at_field on the same resource. Setting both raises a parse error.

Command output​

freshness.json​

After dbt freshness completes, dbt writes results for the evaluated sources and models to target/freshness.json. Each entry includes a resource_type field that identifies whether the resource is a source or a model.

For the full schema, refer to: freshness.json.

{
  "metadata": {
    "generated_at": "2026-08-28T00:00:00.000000Z"
  },
  "results": [
    {
      "unique_id": "model.jaffle_shop.stg_orders",
      "resource_type": "model",
      "max_loaded_at": "2026-08-27T22:00:00+00:00",
      "snapshotted_at": "2026-08-28T00:00:00+00:00",
      "max_loaded_at_time_ago_in_s": 7200,
      "status": "Pass",
      "criteria": {
        "warn_after": {"count": 24, "period": "hour"},
        "error_after": {"count": 48, "period": "hour"}
      }
    },
    {
      "unique_id": "source.jaffle_shop.jaffle_shop.orders",
      "resource_type": "source",
      "max_loaded_at": "2026-08-27T23:30:00+00:00",
      "snapshotted_at": "2026-08-28T00:00:00+00:00",
      "max_loaded_at_time_ago_in_s": 1800,
      "status": "Pass",
      "criteria": {
        "warn_after": {"count": 12, "period": "hour"},
        "error_after": {"count": 24, "period": "hour"}
      }
    }
  ]
}

sources.json (legacy)​

For backward compatibility, whenever sources are included in a dbt freshness run, dbt also writes target/sources.json. It contains sources only, with no resource_type field. If the run includes only models, dbt does not overwrite sources.json.

For the full schema, refer to sources.json.

The legacy dbt source freshness command still works for backward compatibility and produces only sources.json.

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading