dbt state explain

dbt state explain

dbt state explain은 dbt v2.0 이상에서 dbt State를 활성화하면 사용할 수 있는 CLI 명령어예요. 잡(Job)이 끝난 뒤 이 명령어를 실행하면 dbt State가 각 노드에 대해 왜 그런 결정을 내렸는지, 노드를 실행했는지 건너뛰었는지 아니면 클론했는지를 확인할 수 있어요. State 동작 감사(audit), 예상하지 못한 skip 디버깅, freshness와 query 체크가 예상대로 동작하는지 확인할 때 유용해요.

출처: 문서

본문

(적용 범위: dbt v2.0 이상)

dbt state explain

출력은 마지막 실행의 모든 노드를 보여주며, 각 노드에 대한 State 결정 요약을 포함해요:

SKIP_EXECUTION model.jaffle_shop.customers - model was a no-op because its query is up to date and its upstream data is within freshness tolerance
READY_TO_EXECUTE model.jaffle_shop.orders - model was executed because the view definition is newer than the cached execution
READY_TO_EXECUTE test.jaffle_shop.not_null_customers_customer_id - data test was executed because it has no prior execution or its query changed
UNKNOWN unit_test.jaffle_shop.orders.test_order_items_compute_to_bools_correctly - dbt State explain details unavailable

dbt 플랫폼을 사용한다면 명령어를 실행하지 않고도 같은 정보를 볼 수 있어요. job run details 페이지의 Explain 탭에서 각 노드에 대한 전체 결정 내역(decision breakdown)을 확인하면 돼요.

로그 파일 지정 (Specifying a log file)

(적용 범위: dbt v2.0 이상)

기본적으로 dbt state explain은 가장 최근 실행을 읽어요. 이전 실행을 분석하려면 --log-file(또는 -l)을 사용해서 logs/state/ 디렉터리의 state 파일을 지정할 수 있어요:

dbt state explain --log-file 'logs/state/responses_2026_08_25_11_00_15_667.jsonl'

상세(verbose) 모드 사용 (Using verbose mode)

(적용 범위: dbt v2.0 이상)

--verbose 플래그를 쓰면 각 노드에 대한 전체 단계별 분석과 실행 구성 요약(run configuration summary)이 추가로 보여요. -s로 특정 노드만 필터링할 수도 있어요.

dbt state explain --verbose -s my_node_name

dbt v2에서 --verbose는 가장 위에 실행 구성 요약을 보여주고, 각 노드에 대한 전체 단계별 분석을 표시해요.

Run configuration:
  - started at: 2026-08-17T12:24:15.822733+00:00
  - profile: my_profile
  - target: dev
  - defer to target: prod
  - freshness tolerance: 2700 seconds
  - tolerate nondeterminism: true
  - clone incremental in dev: IF_TABLE_MISSING
  - metadata cache TTL: 0 seconds
  - select: fqn:my_node_name
SKIP_EXECUTION model.jaffle_shop.customers - model was a no-op because its query is up to date and its upstream data is within freshness tolerance
  - table analysis ("ANALYTICS"."MY_SCHEMA"."CUSTOMERS")
    - the model table exists already [SUCCESS, TARGET_TABLE_EXISTS]
  - query analysis
    - the model query has not changed [SUCCESS, NODE_QUERY_UNCHANGED]
    - upstream model queries have not changed [SUCCESS]
  - data freshness analysis
    - upstream dependencies
      - "ANALYTICS"."MY_SCHEMA_RAW"."RAW_CUSTOMERS" [FRESH]
        - no updates since "ANALYTICS"."MY_SCHEMA"."CUSTOMERS" last executed
        - last updated: 5 days ago
    - upstream data is up to date [SUCCESS]

--verbose 플래그는 노드 타입에 따라 다음 분석들을 포함하는 결정 내역(decision breakdown)을 만들어요:

  • Table analysis: 대상 테이블이 이미 스키마에 존재하는지 여부
  • Query analysis: 모델 쿼리나 상위 업스트림 쿼리가 변경됐는지 여부
  • Data freshness analysis: 업스트림 데이터가 신선한지, 설정된 lag_tolerance 안에 있는지 여부

더 알아보기 (Learn more)