dbt freshness 명령어

dbt freshness 명령어는 freshness가 설정된 소스와 모델이 warn_after·error_after 임계값을 충족하는지 평가하고, 그에 따라 경고·오류를 보고해요. 결과는 target/freshness.json에 기록돼요.

출처: 문서

본문

dbt freshness 명령어는 freshness가 설정된 소스와 모델이 warn_after·error_after 임계값을 충족하는지 평가하고, 그에 따라 경고·오류를 보고해요.

사용법

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

모든 소스와 모델의 freshness 실행

dbt freshness

리소스 유형 포함 또는 제외

명령어를 실행할 때 포함하거나 제외할 리소스 유형을 플래그로 지정할 수 있어요:

# 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로 명령어 실행에 포함할 모델·소스를 지정할 수 있어요:

# 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"

freshness가 평가되는 방식

dbt freshness는 freshness config에 warn_after 또는 error_after가 설정된 소스·모델을 평가해요.

dbt는 다음 방법 중 하나로 최신 타임스탬프를 가져온 다음, 현재 타임스탬프와 비교해 데이터의 나이(age)를 결정해요.

방법	사용 시점	dbt가 타임스탬프를 가져오는 방식
`loaded_at_query`	리소스에 설정된 경우	커스텀 SQL 표현식을 실행해 최신 타임스탬프를 가져와요.
`loaded_at_field`	리소스에 설정된 경우	구체화된 관계(relation)에 대해 `MAX(<loaded_at_field>)`를 쿼리해요.
Adapter metadata	`loaded_at_query`도 `loaded_at_field`도 설정되지 않은 경우	어댑터 관계 메타데이터에서 마지막 수정 시간을 가져와요. 소스, 그리고 `table`, `incremental`, `materialized_view`, `dynamic_table`로 구체화된 모델에 사용 가능해요(어댑터 지원 시). `view`나 `external`로 구체화된 모델은 `loaded_at_field` 또는 `loaded_at_query`를 사용해야 해요.

같은 리소스에 loaded_at_query와 loaded_at_field를 둘 다 설정할 수 없어요. 둘 다 설정하면 파싱 오류가 발생해요.

명령어 출력

freshness.json

dbt freshness가 완료되면 dbt는 평가된 소스·모델의 결과를 target/freshness.json에 기록해요. 각 항목에는 리소스가 소스인지 모델인지 식별하는 resource_type 필드가 있어요.

전체 스키마는 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 (레거시)

하위 호환성을 위해 dbt freshness 실행에 소스가 포함될 때마다 dbt는 target/sources.json도 기록해요. 소스만 포함하며 resource_type 필드는 없어요. 실행에 모델만 포함된다면 dbt는 sources.json을 덮어쓰지 않아요.

전체 스키마는 sources.json을 참고하세요.

레거시 dbt source freshness 명령어는 하위 호환성을 위해 여전히 동작하며 sources.json만 생성해요.

dbt freshness 명령어