dbt Semantic Layer 详细教程-6 ：指标(metrics)配置规范及示例

前面几篇博文介绍了语义模型及实体、维度和度量规范及示例，一旦创建了语义模型，就该开始添加度量了。可以在与语义模型相同的YAML文件中定义度量，也可以将度量拆分为单独的YAML文件，放入任何其他子目录中（前提是这些子目录也位于相同的dbt项目repo中）。本文介绍指标配置规范，并针对5类不同指标给简要举例说明，针对每类指标如何配置，后续文章继续分析。

本文解释可以添加到dbt项目，以及支持不同的度量类型。包括简单指标、累积指标、派生指标、比率指标以及转换指标。

指标定义规范

指标定义主要属性包括：

以下是指标规范配置的完整示例：

• models/metrics/file_name.yml

metrics:
  - name: metric name                     ## Required
    description: description               ## Optional
    type: the type of the metric          ## Required
    type_params:                          ## Required
      - specific properties for the metric type
    config:                               ## Optional
      meta:
        my_meta_config:  'config'         ## Optional
    label: The display name for your metric. This value will be shown in downstream tools. ## Required
    filter: |                             ## Optional            
      {{  Dimension('entity__name') }} > 0 and {{ Dimension(' entity__another_name') }} is not
      null and {{ Metric('metric_name', group_by=['entity_name']) }} > 5

• 指标缺省粒度

如果你的时间维度具有非常细的粒度（如秒或小时），则度量标准的默认时间粒度非常有用，但是通常以更粗的粒度查询度量标准。指标的默认时间粒度现在dbt Core v1.9+中可用。

转换指标(Conversion metrics )

转换指标可帮助跟踪实体在设定的时间段内发生基本事件和后续转换事件的时间。请看转换指标示例：models/metrics/file_name.yml

metrics:
  - name: The metric name 
    description: The metric description 
    type: conversion 
    label: YOUR_LABEL 
    type_params: #
      conversion_type_params: 
        entity: ENTITY
        calculation: CALCULATION_TYPE 
        base_measure: 
          name: The name of the measure 
          fill_nulls_with: Set the value in your metric definition instead of null (such as zero) 
          join_to_timespine: true/false
        conversion_measure:
          name: The name of the measure 
          fill_nulls_with: Set the value in your metric definition instead of null (such as zero) 
          join_to_timespine: true/false
        window: TIME_WINDOW
        constant_properties:
          - base_property: DIMENSION or ENTITY 
            conversion_property: DIMENSION or ENTITY 

累积指标(Cumulative metrics )

累积指标将给定窗口上的度量集合起来。如果没有指定窗口，则该窗口将在所有记录的时间段内累积度量。注意，在添加累积指标之前，你需要创建时间维度模型。下面是累积指标配置示例：models/metrics/file_name.yml

# Cumulative metrics aggregate a measure over a given window. The window is considered infinite if no window parameter is passed (accumulate the measure over all of time)
metrics:
  - name: wau_rolling_7
    type: cumulative
    label: Weekly active users
    type_params:
      measure:
        name: active_users
        fill_nulls_with: 0
        join_to_timespine: true
      cumulative_type_params:
        window: 7 days

派生指标(Derived metrics)

派生指标被定义为其他指标的表达式。派生指标允许你在指标之上进行计算。下面是派生指标示例：models/metrics/file_name.yml

metrics:
  - name: order_gross_profit
    description: Gross profit from each order.
    type: derived
    label: Order gross profit
    type_params:
      expr: revenue - cost
      metrics:
        - name: order_total
          alias: revenue
        - name: order_cost
          alias: cost

比率指标(Ratio metrics )

比率指标包括分子指标和分母指标。filter属性可以同时应用于分子和分母，也可以单独应用于分子或分母。比率指标配置示例：models/metrics/file_name.yml

metrics:
  - name: cancellation_rate
    type: ratio
    label: Cancellation rate
    type_params:
      numerator: cancellations
      denominator: transaction_amount
    filter: |   
      {{ Dimension('customer__country') }} = 'MX'
  - name: enterprise_cancellation_rate
    type: ratio
    type_params:
      numerator:
        name: cancellations
        filter: {{ Dimension('company__tier') }} = 'enterprise'  
      denominator: transaction_amount
    filter: | 
      {{ Dimension('customer__country') }} = 'MX' 

简单指标(Simple metrics )

简单指标直接指向度量。你可以把它想象成只接受一个度量作为输入的函数。

name—使用该参数定义度量的引用名称。名称在指标中必须是唯一的，并且可以包含小写字母、数字和下划线。你可以使用这个名称从dbt语义层API调用度量。

注意：如果在定义了度量已经使用create_metric: True参数，则不需要创建简单的度量。但是，如果希望在度量的顶部包含约束，则需要创建一个简单的类型度量。

# models/metrics/file_name.yml
metrics:
  - name: cancellations
    description: The number of cancellations
    type: simple
    label: Cancellations
    type_params:
      measure:
        name: cancellations_usd  # Specify the measure you are creating a proxy for.
        fill_nulls_with: 0
        join_to_timespine: true
    filter: |
      {{ Dimension('order__value')}} > 100 and {{Dimension('user__acquisition')}} is not null

过滤条件配置

过滤条件使用Jinja模板进行配置。可以在实体、维度、时间维度或指标配置中用以下语法引用过滤条件配置。

有关如何将指标作为维度与度量过滤条件一起使用，请参阅指标作为维度：

## models/metrics/file_name.yml
filter: | 
  {{ Entity('entity_name') }}

filter: |  
  {{ Dimension('primary_entity__dimension_name') }}

filter: |  
  {{ TimeDimension('time_dimension', 'granularity') }}

filter: |  
 {{ Metric('metric_name', group_by=['entity_name']) }}  

举例，如果要筛选按月分组的订单日期维度，请使用以下语法：

filter: |  
  {{ TimeDimension('order_date', 'month') }}

你可以为指标设置更多元数据，这些元数据以后可以被其他工具使用。使用元数据的方式将根据特定的集成平台而有所不同。