누적 메트릭

누적 메트릭 (Cumulative metrics)

require_nested_cumulative_type_params 플래그는 누적 타입 메트릭이 type_params.cumulative_type_params 아래에 중첩된 구문을 사용하도록 해요. dbt v1.12부터 기본값이 true로, 중첩되지 않은 구문을 쓰면 경고 대신 오류가 발생해요.

출처: 문서

본문

require_nested_cumulative_type_params dbt v1 Latest dbt v1
Introduced 2024.11 1.9.0
Matured (default → true) 2026.09 1.12.0
Removed — —

누적 타입 메트릭은 dbt v1 Latest 릴리즈 트랙, dbt v1.9 이상에서 cumulative_type_params 필드 아래에 중첩돼요. dbt v1.12부터 이 플래그는 기본값이 true로, 누적 메트릭이 중첩되지 않은 구문을 쓰면 경고 대신 오류를 발생시켜요.

v1.9 이전 구문으로 구성된 다음 메트릭을 예로 들어요:

    type: cumulative
    type_params:
      measure: order_count
      window: 7 days

dbt v1.9 또는 dbt v1 Latest 릴리즈 트랙에서 그 구문으로 dbt parse를 실행하면 다음과 같은 경고를 받게 돼요:

15:36:22  [WARNING]: Cumulative fields `type_params.window` and
`type_params.grain_to_date` has been moved and will soon be deprecated. Please
nest those values under `type_params.cumulative_type_params.window` and
`type_params.cumulative_type_params.grain_to_date`. See documentation on
behavior changes:
https://docs.getdbt.com/reference/global-configs/behavior-changes

require_nested_cumulative_type_params가 기본값 true이므로 dbt parse를 실행하면 다음과 같은 오류가 발생해요:

21:39:18  Cumulative fields `type_params.window` and `type_params.grain_to_date` should be nested under `type_params.cumulative_type_params.window` and `type_params.cumulative_type_params.grain_to_date`. Invalid metrics: orders_last_7_days. See documentation on behavior changes: https://docs.getdbt.com/reference/global-configs/behavior-changes.

메트릭을 업데이트하면 예상대로 동작해요:

    type: cumulative
    type_params:
      measure:
        name: order_count
      cumulative_type_params:
        window: 7 days

영향

중첩되지 않은 구문을 여전히 사용하는 누적 메트릭이 있는 프로젝트는 첫 명령에서 완전히 파싱을 멈춰요. 파싱이 실패하므로 그 오류는 모든 dbt 명령에 영향을 줘요: run, build, test, compile, docs generate, Semantic Layer 등.

권장 조치

dbt parse가 하나 이상의 누적 메트릭을 언급하며 Semantic Manifest validation failed로 실패하면, window와 grain_to_date를 type_params에서 type_params.cumulative_type_params로 옮겨 메트릭을 마이그레이션해요. 또는 type_params를 완전히 제거하는 최신 YAML 스펙으로 마이그레이션할 수도 있어요.

# Legacy
metrics:
  - name: weekly_active_users
    type: cumulative
    type_params:
      measure: distinct_users
      window: 7 days

# Nested
metrics:
  - name: weekly_active_users
    type: cumulative
    type_params:
      measure: distinct_users
      cumulative_type_params:
        window: 7 days

# Latest spec
metrics:
  - name: weekly_active_users
    type: cumulative
    input_metric: distinct_users
    window: 7 days

dbt parse를 다시 실행해 매니페스트가 검증되는지 확인해요.

이 동작을 옵트아웃하려면 플래그를 false로 설정해요:

dbt_project.yml

flags:
  require_nested_cumulative_type_params: false

더 알아보기 (Learn more)