Skip to main content

Migrate to the latest YAML spec in the dbt Fusion engine

The latest Semantic Layer specification in the dbt Fusion Engine creates an open standard for defining metrics and dimensions that works across multiple platforms. It simplifies authorship by embedding semantic annotations alongside each model, replacing measures with simple metrics, and promoting frequently used options to top-level keys.

With the new spec, you get simpler configuration without losing flexibility, faster onboarding for new contributors, and a clearer path to consistent, governed metrics across your organization.

Changes in the latest spec​

This section highlights the key updates in the latest metrics spec in Fusion and compares them to the legacy spec.

  • Semantic models — semantic_model is nested directly under each model in models: instead of being a top-level key.
  • Entities and dimensions — Entities and dimensions are defined under columns.
  • Time dimension — Set agg_time_dimension at the model level as the default time dimension for all metrics, with the option to override per metric. time_granularity is deprecated in Fusion. Define granularity at the column level.
  • Simple metrics — Measures are deprecated in Fusion. Use type: simple metrics defined directly within the model instead.
  • Advanced metrics — Top-level key is required for any metric that depends on metrics or dimensions defined in a different semantic model.
  • type_params — The type_params key is deprecated in Fusion.

Semantic models​

The semantic_model key is embedded under models.

models:
  - name: fct_orders
    semantic_model:
      enabled: true # required
      name: fct_orders_semantic_model # optional override; defaults to value of model.name

Entities and dimensions​

Entities and dimensions are defined directly under columns, creating a 1:1 relationship between the physical columns and their semantic definitions.

models:
  - name: orders
    semantic_model:
      enabled: true
    agg_time_dimension: ordered_at
    columns:
      # entities
      - name: order_id
        entity:
          type: primary
          name: order
      - name: customer_id
        entity:
          type: foreign
          name: customer

      # time dimension
      - name: ordered_at
        granularity: day
        dimension:
          type: time

      # categorical dimension
      - name: order_status
        dimension:
          type: categorical

Time dimension​

  • agg_time_dimension: Set once at the model level as the default time dimension for all metrics in that semantic model. You can still override it per metric with agg_time_dimension.
  • time granularity: Deprecated in Fusion. Define the native grain on the time dimension column with granularity (for example, hour, day).
models:
  - name: subscriptions
    semantic_model:
      enabled: true

    # default aggregation time dimension for metrics in this model
    agg_time_dimension: activated_at

    columns:
      - name: activated_at
        granularity: day # native grain on the column
        dimension:
          type: time

      - name: created_at
        granularity: hour # another time column with a different native grain
        dimension:
          type: time

    metrics:
      - name: active_subscriptions
        type: simple
        agg: count
        expr: 1 # inherits agg_time_dimension: activated_at

      - name: signups_by_created_day
        type: simple
        agg: count
        expr: 1
        agg_time_dimension: created_at # override to use created_at as the time dimension

Simple metrics​

Measures are deprecated in Fusion and are replaced with simple metrics.

models:
  - name: customers
    semantic_model:
      enabled: true
    agg_time_dimension: first_ordered_at
    columns:
      - name: customer_id
        entity:
          name: customer
          type: primary
      - name: first_ordered_at
        dimension:
          type: time
        granularity: day
    metrics:
      - name: lifetime_spend_pretax
        type: simple # simple metrics
        agg: sum
        expr: amount_pretax

Advanced metrics​

Define simple metrics inside the model, and create cross‑model metrics under a top‑level metrics block. Top-level key is required for any metric that depends on metrics or dimensions defined in a different semantic model.

# define simple metrics where the data lives
models:
  - name: orders
    ...
    semantic_model:
      enabled: true
    metrics:
      - name: orders
        type: simple
        agg: count
        expr: 1

  - name: website
    semantic_model:
      enabled: true
    metrics:
      - name: sessions
        type: simple
        agg: count
        expr: 1

# advanced metrics under top-level metrics key
metrics:
  - name: orders_per_session
    type: ratio
    numerator: orders
    denominator: sessions

type_params​

The type_params key is deprecated. The following are direct keys on the metric:

  • expr
  • percentile
  • percentile_type
  • non_additive_dimension: { name, window_agg, group_by }
  • join_to_timespine
  • fill_nulls_with
models:
  - name: payments
    semantic_model:
      enabled: true
    metrics:
      - name: revenue_p95
        type: simple
        agg: percentile
        expr: amount
        percentile: 95.0
        percentile_type: discrete

For derived metrics, type_params.metrics is renamed input_metrics.

metrics:
  - name: d7_booking_change
    description: Difference between bookings now and 7 days ago
    type: derived
    label: d7 bookings change
    expr: current_bookings - bookings_7_days_ago
    input_metrics:
      - name: bookings
        alias: current_bookings
      - name: bookings
        offset_window: 7 days
        alias: bookings_7_days_ago

For ratio metrics, numerator and denominator are now direct keys on the metric.

metrics:
  - name: conversion_rate
    type: ratio
    numerator: conversions
    denominator: sessions

For cumulative metrics:

  • type_params.measure is renamed input_metric and must reference a metric.
  • type_params.cumulative_type_params values are direct keys on the metric: window, grain_to_date, and period_agg.
metrics:
  - name: revenue_mtd_cumulative
    type: cumulative
    input_metric: revenue_daily
    window: 30d
    grain_to_date: month
    period_agg: sum

For conversion metrics, the following type_params.conversion_type_params values are direct keys on the metric:

  • entity
  • calculation
  • base_metric (previously base_measure)
  • conversion_metric (previously conversion_measure)
  • constant_properties
metrics:
  - name: paid_signup_conversion
    type: conversion
    entity: user_id
    calculation: conversion_rate
    base_metric: signups
    conversion_metric: paid_signups
    constant_properties:
      plan: pro

Migrating to the latest spec​

Migrate your legacy metrics to the latest YAML spec using the dbt-autofix tool in your CLI, the dbt VS Code extension, or dbt platform's Studio IDE.

note

dbt Copilot doesn't yet support generating semantic models with the latest YAML spec.

Package compatibility​

If your project uses dbt packages (listed in packages.yml) that define metrics or semantic models, the package maintainer must update those packages to use the latest YAML spec in Fusion.

The dbt-autofix tool only updates files in your current dbt project (like models, marts, and so on) and does not update installed packages under dbt_packages/. If an installed package still uses the legacy metrics spec, dbt may raise parsing or validation errors after migration.

To update packages, a package maintainer should:

  1. Run dbt-autofix deprecations --semantic-layer in the package repository.

  2. Validate the changes by running:

    dbt parse
    dbt sl validate  # For dbt platform and Fusion users in IDE / Cloud CLI
    mf validate-configs # For Fusion CLI users not connected to dbt platform and using local MetricFlow

  3. Release a new version of the package with the updated metrics definitions.

After a compatible version is released, update your project to install the new package version. You can then migrate your metrics to the latest spec with the following steps, depending on which tool you're using.

Using the CLI or VS Code extension​

The dbt-autofix tool rewrites legacy metrics YAML into the Fusion format and produces a clear, reviewable diff in version control. Make sure you have installed the latest version of the autofix tool before migrating to the new spec using the CLI or the dbt VS Code extension.

  1. In your CLI or in the VS Code extension, run the following command:

    dbt-autofix deprecations --semantic-layer

  2. Review the diff and resolve all flagged items.

  3. Run parsing and validations:

    dbt parse
    mf validate-configs

Using the Studio IDE​

Convert your metrics in the Studio IDE in the dbt platform without having to install the dbt-autofix tool.

  1. Navigate to the Studio IDE by clicking Studio in the left menu.

  2. Make sure to save and commit your work before proceeding. The autofix command may overwrite any unsaved changes.

  3. In the Studio IDE, run the following command:

    dbt-autofix deprecations --semantic-layer

  4. Click Commit and sync in the top left of the Studio IDE to commit these changes to the project repository.

Was this page helpful?

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

0
Loading