How to Use dbt Sources

The database and schema keys point at where the raw data actually lives, while name is the alias you use in source(). loaded_at_field tells dbt which column holds the load timestamp so it can measure staleness, and the freshness thresholds decide when that becomes a warning rather than an error.

# models/staging/sources.yml
sources:
  - name: shop
    database: raw
    schema: shop_data
    tables:
      - name: raw_orders
        loaded_at_field: _loaded_at
        freshness:
          warn_after: {count: 12, period: hour}
          error_after: {count: 24, period: hour}

In a model

source() compiles to the fully qualified table name and registers the dependency, so the raw table appears in the DAG and in the docs lineage graph. The convention is to reference each source exactly once, in a staging model, and have everything downstream use ref() against that staging model instead.

SELECT * FROM {{ source('shop', 'raw_orders') }}

Checking freshness

dbt source freshness compares the maximum loaded_at_field value against your thresholds and writes results to target/sources.json. Run it before the main build in CI so a stale upstream load fails fast rather than quietly producing yesterday's numbers. Sources without loaded_at_field are skipped rather than reported.

dbt source freshness