DocsChonk TypesMetric Chonks

DocsChonk TypesMetric Chonks

Chonk Types7 min readAdvancedUpdated Jan 2026

Metric Chonks

Metric chonks define semantic layer metrics that provide a single source of truth for business calculations. No more 'which revenue number is right?' conversations.

What They Generate

Metric definitions create consistent, reusable business metrics that can be queried through dbt's semantic layer or MetricFlow.

semantic_models/

Semantic model definition linking to fact tables

metrics/

Metric definitions with aggregations and filters

Dimensions

Attributes for slicing metrics

Metric Types

Simple Metrics

Direct aggregations on a single measure. The building blocks for more complex metrics.

Examples: sum(revenue), count(orders), avg(order_value)

Derived Metrics

Calculations based on other metrics. Use these for ratios and compound calculations.

Examples: conversion_rate (orders/sessions), AOV (revenue/orders)

Cumulative Metrics

Running totals and period-over-period comparisons. Great for growth tracking.

Examples: cumulative_revenue, month_over_month_growth

Example Output

Here's a semantic model with multiple metric types for revenue analysis.

models/semantic/orders_semantic.yml

semantic_models:
  - name: orders
    description: Order transactions for revenue analysis
    model: ref('fct_orders')
    
    defaults:
      agg_time_dimension: order_date
    
    entities:
      - name: order
        type: primary
        expr: order_id
      - name: customer
        type: foreign
        expr: customer_id
    
    dimensions:
      - name: order_date
        type: time
        type_params:
          time_granularity: day
      - name: order_status
        type: categorical
      - name: has_discount
        type: categorical
    
    measures:
      - name: order_count
        agg: count
        expr: order_id
      - name: total_revenue
        agg: sum
        expr: net_amount
      - name: total_discount
        agg: sum
        expr: discount_amount
      - name: avg_order_value
        agg: average
        expr: net_amount

metrics:
  - name: revenue
    description: Total revenue from completed orders
    type: simple
    type_params:
      measure: total_revenue
    filter: |
      {{ Dimension('order_status') }} = 'completed'
      
  - name: aov
    description: Average order value
    type: simple
    type_params:
      measure: avg_order_value
      
  - name: discount_rate
    description: Percentage of revenue given as discounts
    type: derived
    type_params:
      expr: total_discount / total_revenue
      metrics:
        - total_discount
        - total_revenue

Filtered Metrics

Use the filter property to create variations of the same metric. For example: completed_revenuevs pending_revenue.

Best Practices

Clear naming — metrics should be self-explanatory (revenue, not rev_v2_final)
Document filters — explain what's included/excluded in metric descriptions
Use derived metrics — don't duplicate calculation logic across metrics
Define all dimensions — allow flexible analysis without code changes
Test metric values — add assertions for expected ranges and relationships

Avoid Confusion

Never have two metrics that could be confused for each other. If you haverevenue andtotal_revenue, people will use the wrong one.

Configuration Options

Property	Type	Default	Description
metric_type	simple \| derived \| cumulative	simple	Type of metric calculation
time_grains	array	[day, week, month]	Supported time granularities
include_filters	boolean	true	Generate filtered metric variants
create_yoy	boolean	false	Generate year-over-year comparison metrics
format	string	auto	Display format (currency, percent, number)

Metric Chonks

Metric chonks define semantic layer metrics that provide a single source of truth for business calculations. No more 'which revenue number is right?' conversations.

What They Generate

Metric definitions create consistent, reusable business metrics that can be queried through dbt's semantic layer or MetricFlow.

semantic_models/

Semantic model definition linking to fact tables

metrics/

Metric definitions with aggregations and filters

Dimensions

Attributes for slicing metrics

Metric Types

Simple Metrics

Direct aggregations on a single measure. The building blocks for more complex metrics.

Examples: sum(revenue), count(orders), avg(order_value)

Derived Metrics

Calculations based on other metrics. Use these for ratios and compound calculations.

Examples: conversion_rate (orders/sessions), AOV (revenue/orders)

Cumulative Metrics

Running totals and period-over-period comparisons. Great for growth tracking.

Examples: cumulative_revenue, month_over_month_growth

Example Output

Here's a semantic model with multiple metric types for revenue analysis.

models/semantic/orders_semantic.yml

semantic_models:
  - name: orders
    description: Order transactions for revenue analysis
    model: ref('fct_orders')
    
    defaults:
      agg_time_dimension: order_date
    
    entities:
      - name: order
        type: primary
        expr: order_id
      - name: customer
        type: foreign
        expr: customer_id
    
    dimensions:
      - name: order_date
        type: time
        type_params:
          time_granularity: day
      - name: order_status
        type: categorical
      - name: has_discount
        type: categorical
    
    measures:
      - name: order_count
        agg: count
        expr: order_id
      - name: total_revenue
        agg: sum
        expr: net_amount
      - name: total_discount
        agg: sum
        expr: discount_amount
      - name: avg_order_value
        agg: average
        expr: net_amount

metrics:
  - name: revenue
    description: Total revenue from completed orders
    type: simple
    type_params:
      measure: total_revenue
    filter: |
      {{ Dimension('order_status') }} = 'completed'
      
  - name: aov
    description: Average order value
    type: simple
    type_params:
      measure: avg_order_value
      
  - name: discount_rate
    description: Percentage of revenue given as discounts
    type: derived
    type_params:
      expr: total_discount / total_revenue
      metrics:
        - total_discount
        - total_revenue

Filtered Metrics

Use the filter property to create variations of the same metric. For example: completed_revenuevs pending_revenue.

Best Practices

Clear naming — metrics should be self-explanatory (revenue, not rev_v2_final)
Document filters — explain what's included/excluded in metric descriptions
Use derived metrics — don't duplicate calculation logic across metrics
Define all dimensions — allow flexible analysis without code changes
Test metric values — add assertions for expected ranges and relationships

Avoid Confusion

Never have two metrics that could be confused for each other. If you haverevenue andtotal_revenue, people will use the wrong one.

Configuration Options

Property	Type	Default	Description
metric_type	simple \| derived \| cumulative	simple	Type of metric calculation
time_grains	array	[day, week, month]	Supported time granularities
include_filters	boolean	true	Generate filtered metric variants
create_yoy	boolean	false	Generate year-over-year comparison metrics
format	string	auto	Display format (currency, percent, number)

Metric Chonks

What They Generate

semantic_models/

metrics/

Dimensions

Metric Types

Simple Metrics

Derived Metrics

Cumulative Metrics

Example Output

Best Practices

Configuration Options

Related Documentation

Fact Chonks

Semantic Layer

Metric Chonks

What They Generate

semantic_models/

metrics/

Dimensions

Metric Types

Simple Metrics

Derived Metrics

Cumulative Metrics

Example Output

Best Practices

Configuration Options

Related Documentation

Fact Chonks

Semantic Layer