Cumulative metrics

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	—	—

Cumulative-type metrics are nested under the cumulative_type_params field in the dbt v1 Latest release track, dbt v1.9 and newer. Starting in dbt v1.12, this flag defaults to true, which causes dbt to raise an error instead of a warning when cumulative metrics use the un-nested syntax.

Use the following metric configured with the syntax before v1.9 as an example:

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

If you run dbt parse with that syntax on dbt v1.9 or the dbt v1 Latest release track, you will receive a warning like:

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

Because require_nested_cumulative_type_params defaults to true, running dbt parse produces an error like:

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.

Once the metric is updated, it will work as expected:

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

Impact

Any project with a cumulative metric still using the un-nested syntax stops parsing entirely on the first command. Because parsing fails, the error affects every dbt command: run, build, test, compile, docs generate, the Semantic Layer, and more.

 Recommended actions

If dbt parse fails with Semantic Manifest validation failed referencing one or more cumulative metrics, migrate the metrics by moving window and grain_to_date from type_params into type_params.cumulative_type_params. Alternatively, you can migrate to the latest YAML spec, which removes type_params entirely.

# 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

Re-run dbt parse to confirm the manifest validates.

To opt out of this behavior, set the flag to false:

dbt_project.yml

flags:
  require_nested_cumulative_type_params: false

Was this page helpful?

Privacy policyCreate a GitHub issue

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