Передовые методы представления метрик

Расширенные методы для представлений метрик позволяют выразить сложную бизнес-логику и повторно использовать определения в семантическом слое. На этой странице объясняется два таких метода:

• Оконные меры: для расчётов по временным рядам, таких как скользящие средние, нарастающие итоги и изменения по сравнению с предыдущим периодом.
• Составность: для создания сложных мер путем ссылки на другие меры, а не перезаписи их логики.

На этой странице предполагается знакомство с основными понятиями моделирования представлений метрик. См. представления метрик модели.

Размеры окна

Измерения с окнами позволяют определять меры с оконной, накопительной или полуаддитивной агрегацией в представлениях метрик. Они поддерживают такие вычисления, как скользящие средние, изменения по сравнению с предыдущим периодом и накопительные итоги.

Можно добавить меру окна в редакторе обозревателя каталогов или в YAML.

Добавьте оконную меру в редакторе

На вкладке пользовательского интерфейса редактора представления метрик нажмите кнопку +Окно при редактировании меры. + Окно доступно как в режиме Builder, так и в режиме Custom. Параметры окна в редакторе соответствуют полям YAML, описанным в разделе "Определение меры окна".

Дополнительные сведения о создании и редактировании мер см. в разделе "Создание представления метрик".

Задать меру окна

Мера окна включает следующие обязательные поля:

• порядок: поле, определяющее порядок окна.

• диапазон: определяет степень окна. Поддерживаются следующие значения: current, cumulative, trailing, leading и all. Полный синтаксис и описания см. в разделе "Поддерживаемые range значения". Подробнее о модификаторах inclusive и exclusive для trailing и leading см. в разделе Включение или исключение строки привязки.

• semiadditive: указывает, как агрегировать меру, если поле заказа не входит в запрос GROUP BY. Возможные значения: first и last.

Мера окна также поддерживает следующее необязательное поле:

• смещение: сдвигает оконную рамку назад или вперед вдоль поля order на фиксированный интервал. Используйте это для показателей, сравнивающих один период с другим, например месяц к месяцу или год к году. Сведения о синтаксисе, поддерживаемых единицах и ограничениях см. в разделе "Меры окна".

Вы также можете ссылаться на целочисленный параметр как на значение меры range окна или offset, чтобы вызывающий передавал размер окна во время запроса. См. параметр «Передай размер окна».

Как offset сдвигает рамку окна

См. сведения о доступности функции представления метрик для ознакомления с минимальными требованиями к вычислительным ресурсам и версии спецификации YAML.

Поле range определяет форму окна относительно строки привязки, а offset сдвигает эту рамку на указанный интервал вдоль order. В следующей таблице показан кадр для каждого значения range при наличии и отсутствии offset со значением k относительно опорной строки t:

offset не зависит от semiadditive. Выбор first или last по-прежнему определяет, как сворачивается мера, когда order отсутствует в GROUP BY запроса.

Для наилучших результатов совместите offset с естественной текстурой order. Для ежемесячных данных предпочтительнее использовать offset: -12 month, а не offset: -365 day, поскольку арифметика по месяцам и годам учитывает разную длину месяцев и високосные годы, тогда как арифметика day этого не учитывает.

Включение или исключение строки привязки

См. сведения о доступности функции представления метрик для ознакомления с минимальными требованиями к вычислительным ресурсам и версии спецификации YAML.

В диапазонах trailing и leading необязательное ключевое слово inclusive или exclusive определяет, является ли значение окна опорной строки (например, сегодня) частью скользящего окна:

В следующем примере показано, как inclusive и exclusive влияют на скользящее окно для опорной даты 2025-01-05 с trailing 3 day.

Предположим, что базовые данные имеют одну строку в день со следующими значениями:

Каждый модификатор выбирает строки за три дня относительно опорной точки и суммирует их значения:

leading диапазоны следуют той же логике в противоположном направлении.

Пример окна измерения: "скользящее", "подвижное" или "ведущее"

В следующем примере вычисляется скользящее 7-дневное количество клиентов, которые разместили заказы. Эта метрика отслеживает тенденции взаимодействия клиентов с течением времени, показывая, сколько отдельных клиентов сделали покупки за неделю до каждой даты.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate

measures:
  - name: t7d_customers
    expr: COUNT(DISTINCT o_custkey)
    window:
      - order: date
        range: trailing 7 day
        semiadditive: last

В этом примере применяется следующая конфигурация:

• order: date указывает, что date поле упорядочивает окно.
• range: trailing 7 day определяет окно как 7 дней до каждой даты, за исключением самой даты.
• semiadditive: last возвращает последнее значение в 7-дневном окне, если date не является столбцом группировки.

CREATE OR REPLACE VIEW catalog.schema.rolling_customers WITH METRICS LANGUAGE YAML AS
$$
  version: 1.1

  source: samples.tpch.orders
  filter: o_orderdate > DATE'1998-01-01'

  fields:
    - name: date
      expr: o_orderdate

  measures:
    - name: t7d_customers
      expr: COUNT(DISTINCT o_custkey)
      window:
        - order: date
          range: trailing 7 day
          semiadditive: last
$$

Пример измерения с периодическим окном

В следующем примере вычисляется рост продаж по дням, сравнивая текущий доход (сумма всех цен на заказ) со вчерашним доходом. Эта метрика определяет тенденции ежедневных продаж и показывает процентное изменение доходов.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate
measures:
  - name: previous_day_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: trailing 1 day
        semiadditive: last
  - name: current_day_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: current
        semiadditive: last
  - name: day_over_day_growth
    expr: (MEASURE(current_day_sales) - MEASURE(previous_day_sales)) / MEASURE(previous_day_sales) * 100

В этом примере применяется следующая конфигурация:

• В примере используются две оконные меры: одна — для вычисления суммарного объема продаж за предыдущий день, а другая — за текущий день.
• Третья мера вычисляет процентное изменение (рост) между текущими и предыдущими днями.

Пример оконной меры «год к году» с помощью offset

Модификатор offset — это базовый элемент для показателей «период к периоду». Определите смещенную копию базовой метрики, а затем объедините обе, чтобы выразить разницы, отношения или темпы роста непосредственно в представлении метрик.

В следующем примере вычисляется рост продаж за год, сравнивая продажи каждого месяца с тем же месяцем за предыдущий год. Смещённая мера использует offset: -12 month, чтобы отсчитывать 12 месяцев назад по полю month.

version: 1.1
source: main.default.monthly_sales

fields:
  - name: month
    expr: month
  - name: category
    expr: category

measures:
  - name: monthly_sales
    expr: SUM(sales)
    window:
      - order: month
        range: current
        semiadditive: last

  - name: monthly_sales_py
    expr: SUM(sales)
    window:
      - order: month
        range: current
        semiadditive: last
        offset: -12 month

  - name: yoy_growth
    expr: MEASURE(monthly_sales) - MEASURE(monthly_sales_py)

  - name: yoy_growth_pct
    expr: (MEASURE(monthly_sales) - MEASURE(monthly_sales_py))
      / NULLIF(MEASURE(monthly_sales_py), 0)

В этом примере применяется следующая конфигурация:

• monthly_sales — базовая мера, суммирование продаж за текущий месяц.
• monthly_sales_py — это та же мера, смещенная назад на 12 месяцев с использованием offset: -12 month. В январе 2025 г. возвращается значение за январь 2024 г.
• yoy_growth и yoy_growth_pct составляют два показателя для выражения абсолютного и процентного изменения. Использование NULLIF позволяет избежать ошибок деления на ноль, если значение за предыдущий год равно нулю.

Пример совокупного (накопительного) итогового показателя

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

version: 1.1
source: samples.tpch.orders

filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate
  - name: customer
    expr: o_custkey

measures:
  - name: running_total_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: cumulative
        semiadditive: last

В этом примере применяется следующая конфигурация:

• order: date упорядочивает окно в хронологическом порядке.
• range: cumulative определяет окно как все данные с начала набора данных до каждой даты.
• semiadditive: last возвращает последнее накопленное значение, если date не включён в GROUP BY запроса, а не сумму по всем датам.

Пример показателя с начала периода по текущую дату

В следующем примере вычисляется годовой доход от продаж (YTD). Эта мера показывает совокупный доход, полученный с 1 января каждого года до текущей даты, при этом обнуляясь в начале каждого нового года.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1997-01-01'

fields:
  - name: date
    expr: o_orderdate
  - name: month
    expr: DATE_TRUNC('MONTH', date)
  - name: year
    expr: DATE_TRUNC('year', date)
measures:
  - name: ytd_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: cumulative
        semiadditive: last
      - order: year
        range: current
        semiadditive: last

В этом примере применяется следующая конфигурация:

• В примере используются две спецификации окна: одна для совокупной суммы по date полю, а другая — для ограничения суммы current до года.
• Поле year ограничивает накопленную сумму так, что она сбрасывается в начале каждого нового года.
• Поля month и year образуют иерархию дат для поля заказа date: каждое из них определяется в поле date по имени, а не в базовом столбце o_orderdate, поэтому запросы могут группировать этот показатель по этим полям. См. Группировка по полю иерархии дат.

Пример полуаддитивной меры

В следующем примере вычисляются балансы счетов, которые не должны быть суммированы по датам (вы не можете добавить баланс понедельника в баланс вторника, чтобы получить общий баланс). Вместо этого при агрегации в несколько дней мера возвращает последний баланс. Однако мера по-прежнему может быть суммирована по всем клиентам, чтобы показать общий баланс по всем счетам в течение определенного дня.

version: 1.1

fields:
  - name: date
    expr: date
  - name: customer
    expr: customer_id

measures:
  - name: semiadditive_balance
    expr: SUM(balance)
    window:
      - order: date
        range: current
        semiadditive: last

В этом примере применяется следующая конфигурация:

• order: date упорядочивает окно в хронологическом порядке.
• range: current ограничивает окно одним днем без агрегирования в течение нескольких дней.
• semiadditive: last возвращает последний баланс при агрегации в течение нескольких дней.

Запрос метрики окна

Вы можете запросить представление метрик с помощью меры окна, как и любое другое представление метрик. Оконная мера вычисляется по полю order, поэтому запрос, который разбивает результаты по времени, должен ссылаться на это поле либо напрямую, либо через определённое для него поле иерархии дат. Если запрос не ссылается на поле order, ключевое слово semiadditive определяет, какое значение будет возвращено, как описано в Пример полуаддитивной меры.

В следующем примере показано, как выполняется группировка оконной меры state по выражению месяца и по полю заказа date:

SELECT
   state,
   DATE_TRUNC('month', date),
   MEASURE(t7d_customers) as m
FROM my_metric_view
WHERE date >= DATE'2024-06-01'
GROUP BY ALL

Группировать по полю иерархии дат

Иерархия дат развертывает поле заказа до грубого зерна, например недели, месяца или года. Определите каждый уровень как поле над полем порядка, заданным по имени, а не над базовым столбцом источника:

fields:
  - name: date
    expr: o_orderdate
  # Date hierarchy: each level is defined on the order field `date`,
  # not on the underlying o_orderdate column.
  - name: month
    expr: DATE_TRUNC('MONTH', date)
  - name: year
    expr: DATE_TRUNC('year', date)

Группирование меры окна по уровню иерархии возвращает меру на этом уровне. Предположим, что пример периода до текущей даты создаётся как ytd_metric_view, как это показано в примере меры "Период до текущей даты"; следующий запрос возвращает значение YTD по состоянию на последнюю дату каждого месяца:

SELECT month, MEASURE(ytd_sales) AS ytd_sales
FROM ytd_metric_view
GROUP BY month
ORDER BY month;

Компонентность

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

Композиционность работает на двух уровнях: в рамках одного представления метрик и между представлениями метрик, когда одно представление метрик используется в качестве источника для другого.

Composability поддерживает следующие эталонные шаблоны:

• Предыдущие поля в новых полях.
• Поля и ранее созданные показатели в новых показателях.
• Поля из представлений метрик, используемые как источник для новых полей.
• Поля и показатели из представлений показателей, используемые в качестве источника для новых показателей.

Определить меры с композируемостью

measures В разделе можно ссылаться на меры из исходного представления метрик или мер, определенных ранее в том же представлении метрик. Такой подход повышает согласованность, удобство аудита и обслуживание семантического слоя.

Пример: среднее значение заказа (AOV)

В следующем примере определяется среднее значение заказа (AOV) с помощью двух атомарных мер: total_revenue (сумма цен заказов) и order_count (количество заказов). Мера avg_order_value ссылается на обе атомарные меры.

version: 1.1

source: samples.tpch.orders

measures:
  # Total Revenue
  - name: total_revenue
    expr: SUM(o_totalprice)

  # Order Count
  - name: order_count
    expr: COUNT(1)

  # Composed Measure: Average Order Value (AOV)
  - name: avg_order_value
    # Defines AOV as Total Revenue divided by Order Count
    expr: MEASURE(total_revenue) / MEASURE(order_count)

total_revenue Если определение изменяется (например, чтобы исключить налог), avg_order_value автоматически использует обновленное определение.

Сочетаемость с условной логикой

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

Пример: частота выполнения

В следующем примере вычисляется скорость выполнения: процент заказов с состоянием 'F' (выполненным). Мера делит выполненные заказы на общий объем заказов.

version: 1.1

source: samples.tpch.orders

measures:
  # Total Orders (denominator)
  - name: total_orders
    expr: COUNT(1)

  # Fulfilled Orders (numerator)
  - name: fulfilled_orders
    expr: COUNT(1) FILTER (WHERE o_orderstatus = 'F')

  # Composed Measure: Fulfillment Rate (Ratio)
  - name: fulfillment_rate
    expr: MEASURE(fulfilled_orders) / MEASURE(total_orders)
    format:
      type: percentage

Рекомендации по компоновке

1. Сначала определите атомарные меры: установите основные меры (SUM, COUNT, ) AVGперед определением мер, ссылающихся на них.
2. Используйте MEASURE() для ссылок: используйте функцию MEASURE() при ссылке на другую меру в expr. Не повторяйте логику агрегирования вручную. Например, избегайте SUM(a) / COUNT(b), если меры для обоих значений уже существуют.
3. Приоритет удобочитаемости: создание мер с использованием четких математических формул. Например, MEASURE(gross_profit) / MEASURE(total_revenue) более понятно, чем одно сложное выражение SQL.
4. Добавление семантических метаданных. Используйте семантические метаданные для форматирования составных мер (например, процентных или валютных) для подчиненных инструментов. См. метаданные агента в представлениях метрик.

Дополнительные ресурсы

• Представления метрик модели
• Метаданные агента в представлениях метрик
• Материализация для представлений метрик
• Справочник по синтаксису YAML представления метрик