Перейти к основному содержимому

Создание метрик

После создания семантических моделей можно приступать к добавлению метрик. На этой странице описаны поддерживаемые типы метрик, которые можно добавить в ваш проект dbt.

(Версии dbt: v1.12 и новее)

Метрики можно определять в двух местах в YAML-файлах models:

  • Внутри семантических моделей (в models -> semantic_model -> metrics) — для метрик, использующих измерения из одной семантической модели. Рекомендуется для простых метрик.
  • На верхнем уровне (в отдельном ключе metrics) — для расширенных метрик (накопительных, метрик отношения, производных метрик и метрик конверсии), которые ссылаются на метрики из разных семантических моделей. Простые метрики нельзя определять на верхнем уровне.

Определяйте метрики в YAML-файлах вашего проекта dbt, а не в блоке config модели.

Параметры​

Ключи параметров метрик:

(Версии dbt: v1.12 и новее)
ПараметрОписаниеОбязательностьТип
nameУкажите имя для ссылки на метрику. Это имя должно быть уникальным среди метрик и может состоять из строчных латинских букв, цифр и символов подчёркивания.ОбязательныйString
descriptionДобавьте описание метрики.НеобязательныйString
typeЗадайте тип метрики: conversion, cumulative, derived, ratio или simple.ОбязательныйString
labelОпределяет отображаемое значение в инструментах, использующих метрику. Допускает обычный текст, пробелы и кавычки (например, orders_total или "orders_total").НеобязательныйString
configИспользуйте свойство config, чтобы задать настройки метрики. Поддерживаются настройки meta, group, tags и enabled.НеобязательныйDict
filterК метрике любого типа можно добавить строку фильтра, чтобы применять фильтры к измерениям, сущностям, временным измерениям или другим метрикам при вычислении метрики. Рассматривайте её как условие WHERE.НеобязательныйString

Параметры, зависящие от типа метрики​

Для каждого типа метрики предусмотрены дополнительные параметры:

  • Простые метрики: agg (обязательный), expr, percentile, percentile_type, non_additive_dimension, agg_time_dimension, join_to_timespine, fill_nulls_with
  • Накопительные метрики: input_metric (обязательный), window, grain_to_date, period_agg
  • Производные метрики: expr (обязательный), input_metrics (обязательный)
  • Метрики-отношения: numerator (обязательный), denominator (обязательный)
  • Метрики конверсии: entity (обязательный), calculation (обязательный), base_metric (обязательный), conversion_metric (обязательный), window, constant_properties

Подробную информацию о параметрах, зависящих от типа метрики, см. в следующих разделах, посвящённых каждому типу метрик.

Пример​

Ниже приведён полный пример конфигурации спецификации метрик:

(Версии dbt: v1.12 и новее)
models/file_name.yml
models:
- name: my_model
semantic_model:
enabled: true
name: my_semantic_model

# Define columns, dimensions, entities...
columns:
- name: my_column
# column config...

# Metrics defined within the semantic model
metrics:
- name: my_simple_metric
description: A metric description
type: simple
label: My Simple Metric
agg: sum
expr: revenue_column # Optional, defaults to metric name
config:
meta:
owner: "@analytics_team"

# Advanced metrics that reference metrics from different semantic models
metrics:
- name: my_advanced_cumulative_metric
type: cumulative
window: 1 week
input_metric:
name: my_metric_name_from_another_semantic_model
filter: my_filter
alias: my_metric_name_a_week_ago_in_another_semantic_model
📹 Узнайте о семантическом слое dbt с помощью видеокурсов по запросу!

Изучите наш курс по семантическому слою dbt, чтобы узнать, как определять и запрашивать метрики в вашем проекте dbt.

Кроме того, погрузитесь в мини-курсы по запросам к семантическому слою dbt в ваших любимых инструментах: Tableau, Excel, Hex и Mode.

Гранулярность по умолчанию для метрик​

(Версии dbt: v1.12 и новее)

Задайте исходную детализацию столбца временного измерения и выбирайте детализацию агрегирования при выполнении запроса.

  • Определите детализацию данных в столбце временного измерения с помощью granularity (например, час, день, месяц).
  • Метрики наследуют временное измерение для агрегирования по умолчанию, заданное на уровне модели. При необходимости его можно переопределить для отдельной метрики с помощью agg_time_dimension.
  • При выполнении запроса выбирайте детализацию агрегирования (день/неделя/месяц/год) в BI-инструменте или через API семантического слоя. Агрегировать данные можно только до уровня детализации, равного исходному уровню столбца или более крупного.

Пример​

  • order_time хранится с почасовой детализацией.
  • Метрика orders использует это временное измерение; вы агрегируете её по месяцам при выполнении запроса (а не в спецификации метрики).
  • Вторая метрика показывает, как указать другое временное измерение с помощью agg_time_dimension.
models/file_name.yml
models:
- name: orders
semantic_model:
enabled: true

# Временное измерение для агрегирования по умолчанию на уровне модели (необязательно)
agg_time_dimension: order_time

columns:
- name: order_time
granularity: hour # Исходная детализация столбца
dimension:
type: time

- name: created_at
granularity: day
dimension:
type: time

metrics:
- name: orders
type: simple
agg: count
expr: 1
# Здесь нет time_granularity. Агрегируйте по месяцам при выполнении запроса.

- name: orders_by_created_day
type: simple
agg: count
expr: 1
agg_time_dimension: created_at # Используйте другое временное измерение для этой метрики

Метрики конверсии​

Метрики конверсии помогают отслеживать, когда для сущности происходит базовое событие и последующее событие конверсии в рамках заданного временного окна.

(Версии dbt: v1.12 и новее)
models/file_name.yml
models:
- name: my_model
semantic_model:
enabled: true

# Define columns, dimensions, entities...

metrics:
- name: my_conversion_metric
description: Conversion metric description
type: conversion
label: My conversion metric
entity: my_primary_entity # Required
calculation: conversion_rate # conversion_rate | conversions
base_metric: simple_metric # Required, must refer to metric name or metric dict
conversion_metric: my_simple_metric_that_uses_the_other_time_dimension # Required, must refer to metric name or metric dict
window: 1 week # Optional time window
constant_properties: # Optional
- base_property: dimension_or_entity_name # Dimension or entity from base metric's semantic model
conversion_property: dimension_or_entity_name # Dimension or entity from conversion metric's semantic model

# For conversion metrics referencing metrics from different semantic models
metrics:
- name: my_advanced_conversion_metric
config:
group: example_group
tags:
- example_tag
- another_tag
meta:
owner: "@docs-team"
type: conversion
entity: my_primary_entity # required for conversion metrics
calculation: conversion_rate # conversion_rate | conversions # required for conversion metrics
base_metric: my_simple_metric # str | metric dict (if filters are needed)
conversion_metric: my_other_metric_from_another_semantic_model # str | metric dict (if filters are needed)
window: 1 week # optional, as above
constant_properties: # optional - DIMENSION OR ENTITY
- base_property: my_primary_entity # Required. A reference to a dimension/entity of the semantic model linked to the base_metric
conversion_property: another_semantic_model_categorical_dimension

Накопительные метрики​

(Версии dbt: v1.12 и новее)

Кумулятивные метрики агрегируют простую метрику за заданный период. Если период не указан, окно будет накапливать простую метрику за весь период, за который имеются данные. Обратите внимание: перед добавлением кумулятивных метрик необходимо создать модель временной шкалы.

models/file_name.yml
models:
- name: my_model
semantic_model:
enabled: true

# Define columns, dimensions, entities...

metrics:
- name: active_users
type: simple
agg: count_distinct
expr: user_id

- name: wau_rolling_7
type: cumulative
label: Weekly active users
description: Rolling 7 day window of active users
input_metric: active_users # Required - must refer to metric name or dict
window: 7 days # Optional - omit for infinite window (all time)
join_to_timespine: true # Optional
fill_nulls_with: 0 # Optional

# For cumulative metrics using metrics from different semantic models
metrics:
- name: my_advanced_cumulative_metric
type: cumulative
label: Advanced cumulative metric
input_metric:
name: metric_from_another_model
filter: "{{ Dimension('entity__dimension') }} > 0"
alias: filtered_metric
window: 1 week # Optional: can specify window OR grain_to_date, not both
# grain_to_date: month # Alternative to window
# period_agg: first # Optional: first | last | average

Производные метрики​

Производные метрики позволяют выполнять вычисления с использованием других метрик. Например, можно вычислить gross_profit, вычтя метрику cost из метрики revenue, или рассчитать рост, сравнив метрику с её значением за предыдущий период.

(Версии dbt: v1.12 и новее)
models/file_name.yml
models:
- name: my_model
semantic_model:
enabled: true

# Define columns, dimensions, entities...

metrics:
- name: order_total
type: simple
agg: sum
expr: order_amount

- name: order_cost
type: simple
agg: sum
expr: cost_amount

- name: order_gross_profit
description: Gross profit from each order
type: derived
label: Order gross profit
expr: revenue - cost # Required for derived metrics
input_metrics: # Required for derived metrics
- name: order_total
alias: revenue
- name: order_cost
alias: cost

# For derived metrics using metrics from different semantic models
metrics:
- name: my_advanced_derived_metric
type: derived
label: Advanced derived metric
expr: metric_a - metric_b_offset + metric_c # Required
input_metrics: # Required - list of metric names or dicts
- name: metric_a
filter: "{{ Dimension('entity__dimension') }} > 10"
- name: metric_b
alias: metric_b_offset
offset_window: 1 week # Only allowed for derived metrics
- name: metric_c
offset_to_grain: month # Only allowed for derived metrics

Метрики отношения​

Метрики отношения включают метрику числителя и метрику знаменателя. Строку filter можно применить как к числителю и знаменателю одновременно, так и отдельно к числителю или знаменателю.

(Версии dbt: v1.12 и новее)
models/file_name.yml
models:
- name: my_model
semantic_model:
enabled: true

# Определите столбцы, измерения, сущности...

metrics:
- name: cancellations
type: simple
agg: sum

- name: transaction_amount
description: Сумма транзакций
label: Сумма транзакций
type: simple
agg: sum

- name: cancellation_rate
type: ratio
label: Доля отмен
numerator: cancellations # Может быть строкой или словарём
denominator: transaction_amount # Может быть строкой или словарём
filter: | # Необязательно — применяется к числителю и знаменателю
"{{ Dimension('customer__country') }} = 'MX'"

- name: enterprise_cancellation_rate
type: ratio
label: Доля отмен для корпоративных клиентов
numerator:
name: cancellations
filter: "{{ Dimension('company__tier') }} = 'enterprise'" # Необязательно
alias: enterprise_cancellations # Необязательно
denominator: transaction_amount
filter: | # Необязательно — применяется к числителю и знаменателю
{{ Dimension('customer__country') }} = 'MX'

# Для метрик отношения, использующих метрики из разных семантических моделей
metrics:
- name: my_advanced_ratio_metric
type: ratio
label: Расширенная метрика отношения
numerator:
name: metric_from_model_a
filter: "{{ Dimension('entity__dimension') }} > 10"
alias: filtered_numerator
denominator:
name: metric_from_model_b
filter: "{{ Dimension('entity__dimension') }} < 100"

Простые метрики​

(Версии dbt: v1.12 и новее)

Простые метрики напрямую ссылаются на выражение для одного столбца в семантической модели. Простую метрику можно рассматривать как базовый строительный блок для других метрик. Она выполняет агрегацию (например, sum, count, average и т. д.) по одному полю вашей модели.

models/file_name.yml
models:
- name: my_model
semantic_model:
enabled: true

# Define columns, dimensions, entities...

metrics:
- name: cancellations
description: The number of cancellations
type: simple
label: Cancellations
agg: sum # Required: sum | max | min | average | median | count_distinct | percentile | count | sum_boolean
expr: cancellations_usd # Optional, defaults to metric name
join_to_timespine: true # Optional
fill_nulls_with: 0 # Optional
filter: | # Optional
{{ Dimension('order__value') }} > 100 and "{{ Dimension('user__acquisition') }} is not null

# Example with percentile aggregation
- name: order_percentile
type: simple
label: Order 95th Percentile
agg: percentile
expr: order_value
percentile: 95.0 # Required if agg is percentile
percentile_type: discrete # Required: discrete | continuous

# Example with non-additive dimension
- name: account_balance
type: simple
label: Account balance
agg: sum
expr: balance_amount
non_additive_dimension:
name: snapshot_date # Must be a dimension
window_agg: max # min | max
group_by: # Optional - list of entity names
- account_id

# Example with config
- name: revenue
type: simple
label: Total revenue
agg: sum
expr: revenue_amount
config:
meta:
owner: "@finance_team"
team: "Revenue analytics"

Фильтры​

Настройте фильтр с помощью шаблонов 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') }}

Связанная документация​

Нашли ошибку?

0
Loading