Кумулятивные метрики
Накопительные метрики агрегируют значения других метрик за заданный период накопления. Если период не указан, метрика накапливает значения за весь доступный временной диапазон.
Используйте накопительные метрики для расчета значений за скользящий период или с начала текущего периода, например количества активных пользователей за неделю или выручки с начала месяца.
- Перед определением накопительных метрик необходимо создать модель временной шкалы, чтобы MetricFlow мог соединять агрегированные по времени данные с временной шкалой.
- Если накопительная метрика зависит от метрик или измерений, определенных в другой семантической модели, задайте накопительные метрики в ключе
metricsверхнего уровня.
Параметры
(Версии dbt: v1.12 и новее)| Параметр | Описание | Обязательный | Тип |
|---|---|---|---|
name | Название метрики. | Обязательный | String |
description | Описание метрики. | Необязательный | String |
type | Тип метрики (cumulative, derived, ratio или simple). | Обязательный | String |
label | Необязательная строка, определяющая отображаемое значение в инструментах, использующих метрику. Допускает обычный текст, пробелы и кавычки (например, orders_total или "orders_total"). | Необязательный | String |
input_metric | Название метрики, на которую ссылаются. Поддерживает следующие вложенные параметры: name, filter и alias. | Обязательный | Dict |
input_metric.name | Название метрики, на которую ссылаются. | Обязательный | String |
input_metric.filter | Фильтр, применяемый к метрике. | Необязательный | String |
input_metric.alias | Псевдоним, применяемый к метрике. | Необязательный | String |
join_to_timespine | Логическое значение, указывающее, следует ли соединять агрегированную метрику с таблицей временной шкалы, чтобы заполнить пропущенные даты. По умолчанию — false. | Необязательный | Boolean |
window | Задаёт окно накопления, например 1 month, 7 days или 1 year. Нельзя использовать вместе с grain_to_date. | Необязательный | String |
grain_to_date | Задаёт гранулярность накопления, например hour, day, week, month, year, при этом накопление начинается заново в начале каждого периода указанной гранулярности. Например, при выборе month метрика агрегируется с начала месяца до текущей даты (month to date). Нельзя использовать вместе с window. | Необязательный | String |
period_agg | Определяет способ повторной агрегации накопительной метрики при запросе с гранулярностью, отличной от заданной по умолчанию: first, last или average. Если period_agg не указан, по умолчанию используется first. | Необязательный | String |
Полная спецификация
Ниже приведена полная спецификация накопительных метрик вместе с примером:
(Версии dbt: v1.12 и новее)metrics:
- name: my_advanced_cumulative_metric # required
description: my_description # optional
label: my_label # optional
type: cumulative # required -- cumulative | ratio | derived | conversion
# if cumulative, optionally can supply window or grain_to_date, but not both
window: 1 week # (interval)
# grain_to_date: hour # hour | day | week | month | year | ...
input_metric: # required, must refer to metric name or metric dict
name: my_metric_name_from_another_semantic_model
filter: "{{ Dimension('entity__dimension_name') }} > 10"
alias: my_metric_name_a_week_ago_in_another_semantic_model
Пример кумулятивных метрик
Кумулятивные метрики измеряют данные за заданный период и считают период бесконечным, если параметр окна не передан, накапливая данные за все время.
Следующий пример показывает, как определить кумулятивные метрики в YAML-файле:
(Версии dbt: v1.12 и новее)-
cumulative_order_total: рассчитывает накопительную сумму заказов за всё время. Параметрinput_metricуказывает простую метрикуorder_total, которую нужно агрегировать. -
cumulative_order_total_l1m: рассчитывает накопительную сумму заказов за последний месяц. Параметрwindowзадаёт окно в один месяц. -
cumulative_order_total_mtd: рассчитывает накопительную сумму заказов с начала месяца. Параметрgrain_to_dateзадаёт периодmonth.
metrics:
- name: cumulative_order_total
label: "Cumulative order total (All-Time)"
description: "The cumulative value of all orders"
type: cumulative
input_metric: order_total
- name: cumulative_order_total_l1m
label: "Cumulative order total (L1M)"
description: "Trailing 1-month cumulative order total"
type: cumulative
window: 1 month
input_metric: order_total
- name: cumulative_order_total_mtd
label: "Cumulative order total (MTD)"
description: "The month-to-date value of all orders"
type: cumulative
grain_to_date: month
input_metric: order_total
Опции гранулярности
(Версии dbt: v1.12 и новее)Используйте параметр period_agg с функциями first, last и average для агрегации накопительных метрик за запрошенный период. Это необходимо, поскольку варианты гранулярности для накопительных метрик отличаются от вариантов для других типов метрик.
- Для других метрик мы используем функцию
date_trunc, чтобы задать гранулярность. - Однако накопительные метрики неаддитивны (их значения нельзя суммировать), поэтому мы не можем использовать функцию
date_truncдля изменения их временной гранулярности. - По умолчанию мы берём первое значение периода. Вы можете изменить это поведение, указав другую функцию с помощью параметра
period_agg.
В следующем примере мы определяем накопительную метрику cumulative_revenue, которая рассчитывает накопительную выручку по всем заказам:
metrics:
- name: cumulative_revenue
description: "Накопительная выручка по всем заказам."
label: "Накопительная выручка (за всё время)"
type: cumulative
input_metric: revenue
period_agg: first # Необязательный параметр. По умолчанию: first. Допустимые значения: first|last|average
В этом примере для period_agg задано значение first, при котором выбирается первое значение в пределах интервала выбранной гранулярности. Чтобы запросить cumulative_revenue по неделям, используйте следующий синтаксис запроса:
dbt sl query --metrics cumulative_revenue --group-by metric_time__week
Параметры окна
Этот раздел содержит примеры, когда следует указывать и не указывать опции окна.
(Версии dbt: v1.12 и новее)- Если указан период, MetricFlow применяет скользящее окно к базовой простой метрике, например для отслеживания активных пользователей за неделю с окном в 7 дней.
- Если период не указан, накопительные метрики накапливают значения за всё время, что полезно для расчёта нарастающих итогов, таких как текущая выручка и количество активных подписок.
Нарастающий итог с начала периода
Вы можете выбрать указание зерна до даты в конфигурации вашей кумулятивной метрики, чтобы накапливать метрику с начала зерна (например, неделя, месяц или год). При использовании окна, например, месяц, MetricFlow вернется на один полный календарный месяц назад. Однако зерно до даты всегда будет начинать накопление с начала зерна, независимо от последней даты данных.
(Версии dbt: v1.12 и новее)Например, рассмотрим базовую простую метрику order_total, определённую в семантической модели:
models:
- name: fct_orders
semantic_model:
enabled: true
# Simple metrics defined within semantic model
metrics:
- name: order_total
description: "Сумма итоговых сумм заказов"
type: simple
agg: sum
expr: order_total
Сравним окно длительностью 1 месяц и накопление с начала текущего месяца (grain to date).
- При использовании окна к накопительной метрике применяется скользящее окно длительностью 1 месяц
- При накоплении с начала текущего месяца значение сбрасывается в начале каждого месяца.
# Top-level metrics key for cumulative metrics
metrics:
- name: cumulative_order_total_mtd
label: "Cumulative order total (MTD)"
description: "The month-to-date value of all orders"
type: cumulative
grain_to_date: month
input_metric: order_total
Кумулятивная метрика с зерном до даты:
(Версии dbt: v1.12 и новее)# Ключ metrics верхнего уровня для накопительных метрик
metrics:
- name: orders_last_month_to_date
label: "Заказы с начала месяца"
description: "Количество заказов с начала месяца"
type: cumulative
grain_to_date: month
input_metric: order_count
Пример реализации SQL
Чтобы вычислить кумулятивное значение метрики за заданный период, мы выполняем соединение по временной шкале с таблицей временной оси, используя основное временное измерение в качестве ключа соединения. Мы используем окно накопления в соединении, чтобы решить, следует ли включать запись в конкретный день. Следующий SQL-код, полученный из примера кумулятивной метрики, предоставлен для справки:
Чтобы реализовать кумулятивные метрики, обратитесь к примеру SQL-кода:
select
count(distinct distinct_users) as weekly_active_users,
metric_time
from (
select
subq_3.distinct_users as distinct_users,
subq_3.metric_time as metric_time
from (
select
subq_2.distinct_users as distinct_users,
subq_1.metric_time as metric_time
from (
select
metric_time
from transform_prod_schema.mf_time_spine subq_1356
where (
metric_time >= cast('2000-01-01' as timestamp)
) and (
metric_time <= cast('2040-12-31' as timestamp)
)
) subq_1
inner join (
select
distinct_users as distinct_users,
date_trunc('day', ds) as metric_time
from demo_schema.transactions transactions_src_426
where (
(date_trunc('day', ds)) >= cast('1999-12-26' as timestamp)
) AND (
(date_trunc('day', ds)) <= cast('2040-12-31' as timestamp)
)
) subq_2
on
(
subq_2.metric_time <= subq_1.metric_time
) and (
subq_2.metric_time > dateadd(day, -7, subq_1.metric_time)
)
) subq_3
)
group by
metric_time,
limit 100;
Ограничения
Если вы указываете window в определении вашей кумулятивной метрики, вы должны включить metric_time в качестве измерения в SQL-запросе. Это связано с тем, что окно накопления основано на времени метрики. Например,
select
count(distinct subq_3.distinct_users) as weekly_active_users,
subq_3.metric_time
from (
select
subq_2.distinct_users as distinct_users,
subq_1.metric_time as metric_time
group by
subq_3.metric_time