Справочник по синтаксису YAML представления метрик

На этой странице описывается полная грамматика YAML для представлений метрик. Определения представления метрик соответствуют стандартному синтаксису нотации YAML.

Минимальные требования к версии среды выполнения и спецификации YAML для каждой функции см. в разделе "Доступность функций представления метрик".

См. документацию YAML Specification 1.2.2, чтобы узнать больше о спецификациях YAML.

Общие сведения о YAML

Определение YAML для представления метрик включает следующие поля верхнего уровня:

Исходный материал

Поле source указывает источник данных для представления метрик. Вы можете использовать табличный ресурс, например таблицы, представления и метрики, или SQL-запрос в качестве источника. Возможность создания применяется в представлениях метрик. При использовании представления метрик в качестве источника можно ссылаться на его измерения и меры в новом представлении метрик. См. статью "Компонуемость".

Источник ресурса, похожий на таблицу

Ссылка на ресурс, похожий на таблицу, с помощью трех частей:

source: catalog.schema.source_table

Источник SQL-запроса

Чтобы использовать SQL-запрос, напишите текст запроса непосредственно в YAML:

source: SELECT * FROM samples.tpch.orders o
  LEFT JOIN samples.tpch.customer c
  ON o.o_custkey = c.c_custkey

Фильтр

Фильтр в определении YAML применяется ко всем запросам, ссылающимся на представление метрик. Записывает фильтры в виде логических выражений SQL.

# Single condition filter
filter: o_orderdate > '2024-01-01'

# Multiple conditions with AND
filter: o_orderdate > '2024-01-01' AND o_orderstatus = 'F'

# Multiple conditions with OR
filter: o_orderpriority = '1-URGENT' OR o_orderpriority = '2-HIGH'

# Complex filter with IN clause
filter: o_orderstatus IN ('F', 'P') AND o_orderdate >= '2024-01-01'

# Filter with NOT
filter: o_orderstatus != 'O' AND o_totalprice > 1000.00

# Filter with LIKE pattern matching
filter: o_comment LIKE '%express%' AND o_orderdate > '2024-01-01'

Присоединения

Соединения в представлениях метрик поддерживают прямые соединения из таблицы фактов с таблицами измерений (схема звезды) и соединениями с несколькими прыжками в нормализованных таблицах измерений (схемы снежинки). Вы также можете присоединиться к SQL-запросу с помощью инструкции SELECT . См. раздел "Использование SQL-запроса в качестве источника".

Каждое определение соединения включает следующие поля:

Соединения схемы "Звезда"

В схеме source звездочки таблица фактов и присоединение к одной или нескольким таблицам измерений с помощью .LEFT OUTER JOIN Представления метрик объединяют таблицы фактов и измерений, необходимые для конкретного запроса, на основе выбранных столбцов.

Укажите столбцы соединения с помощью ON предложения или USING предложения:

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

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

version: 1.1
source: samples.tpch.lineitem

joins:
  - name: orders
    source: samples.tpch.orders
    on: source.l_orderkey = orders.o_orderkey

  - name: part
    source: samples.tpch.part
    on: source.l_partkey = part.p_partkey

dimensions:
  - name: Order Status
    expr: orders.o_orderstatus

  - name: Part Name
    expr: part.p_name

measures:
  - name: Total Revenue
    expr: SUM(l_extendedprice * (1 - l_discount))

  - name: Line Item Count
    expr: COUNT(1)

Соединения схемы Snowflake

Схема snowflake расширяет схему звезд, нормализуя таблицы измерений и подключая их к подмериям. Это создает структуру соединения с несколькими уровнями. См. сведения о доступности функций представления метрик для минимальных требований к среде выполнения.

Чтобы определить схему snowflake, вложенную joins в определение родительского соединения:

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    'on': o_custkey = c_custkey
    joins:
      - name: nation
        source: samples.tpch.nation
        'on': c_nationkey = n_nationkey

dimensions:
  - name: customer_nation
    expr: customer.nation.n_name

Размеры

Измерения — это столбцы, используемые в SELECT, WHERE и GROUP BY предложениях во время запроса. Каждое выражение должно возвращать скалярное значение. Измерения могут ссылаться на столбцы из исходных данных или более ранних измерений в представлении метрик.

Каждое определение измерения включает следующие поля:

Пример:

dimensions:
  # Basic dimension
  - name: order_date
    expr: o_orderdate
    comment: 'Date the order was placed'
    display_name: 'Order Date'

  # Dimension with SQL expression
  - name: order_month
    expr: DATE_TRUNC('MONTH', o_orderdate)
    display_name: 'Order Month'

  # Dimension with synonyms
  - name: order_status
    expr: CASE
      WHEN o_orderstatus = 'O' THEN 'Open'
      WHEN o_orderstatus = 'P' THEN 'Processing'
      WHEN o_orderstatus = 'F' THEN 'Fulfilled'
      END
    display_name: 'Order Status'
    synonyms: ['status', 'fulfillment status']

Меры

Меры — это выражения, которые создают результаты без предварительно определенного уровня агрегирования. Они должны быть выражены с помощью агрегатных функций. Чтобы ссылаться на меру в запросе, используйте функцию MEASURE . Меры могут ссылаться на базовые поля в исходных данных, более ранних измерениях или более ранних мерах.

Каждое определение меры включает следующие поля:

См. раздел "Агрегатные функции " для списка агрегатных функций.

Пример:

measures:
  # Simple count measure
  - name: order_count
    expr: COUNT(1)
    display_name: 'Order Count'

  # Sum aggregation measure with synonyms
  - name: total_revenue
    expr: SUM(o_totalprice)
    comment: 'Gross revenue from all orders'
    display_name: 'Total Revenue'
    synonyms: ['revenue', 'total sales']

  # Distinct count measure
  - name: unique_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: 'Unique Customers'

  # Calculated measure combining multiple aggregations
  - name: avg_order_value
    expr: SUM(o_totalprice) / COUNT(DISTINCT o_orderkey)
    display_name: 'Avg Order Value'
    synonyms: ['AOV', 'average order']

  # Filtered measure with WHERE condition
  - name: open_order_revenue
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'O')
    display_name: 'Open Order Revenue'
    synonyms: ['backlog', 'outstanding revenue']

Размеры окна

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

Каждая спецификация окна включает следующие поля:

Пример меры окна

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

version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate

measures:
  - name: rolling_7day_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: '7-Day Rolling Customers'
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

Материализация

Поле настраивает автоматическое materialization ускорение запросов с помощью материализованных представлений. Подробные сведения о том, как работает материализация, требования и рекомендации, см. в разделе "Материализация" для представлений метрик.

Это materialization поле содержит следующие поля верхнего уровня:

Каждая запись включает materialized_views следующие поля:

Пример материализации

В следующем примере определяется представление метрик с несколькими материализациями:

version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate
  - name: order_status
    expr: o_orderstatus

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
  - name: order_count
    expr: COUNT(1)

materialization:
  schedule: every 6 hours
  mode: relaxed
  materialized_views:
    - name: baseline
      type: unaggregated

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - order_status
      measures:
        - total_revenue
        - order_count

Ссылки на названия столбцов

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

Примеры форматирования

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

Указать имя столбца

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

Использование выражений с двоеточиями

Многострочная индентация

Обновление YAML до версии 1.1

Обновление представления метрик до спецификации YAML версии 1.1 требует заботы, так как комментарии обрабатываются иначе, чем в более ранних версиях.

Типы комментариев

• Примечания YAML (#): встроенные или однострочные комментарии, написанные непосредственно в файле YAML с помощью символа #.
• Комментарии каталога Unity: комментарии, хранящиеся в каталоге Unity для представления метрик или его столбцов (измерения и меры). Это отдельно от комментариев YAML.

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

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

Вариант 1. Сохранение комментариев YAML с помощью записных книжек или редактора SQL

Если представление метрик содержит примечания YAML (#), которые вы хотите сохранить, выполните следующие действия.

1. ALTER VIEW Используйте команду в записной книжке или редакторе SQL.
2. Скопируйте исходное определение YAML в $$..$$ раздел после AS. Измените значение атрибута version на 1.1.
3. Сохраните представление метрик.

ALTER VIEW metric_view_name AS
$$
# The notebook preserves inline comments
version: 1.1
source: samples.tpch.orders
dimensions:
- name: order_date # The notebook preserves inline comments
  expr: o_orderdate
measures:
# The notebook preserves commented out definitions
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

Вариант 2. Сохранение комментариев каталога Unity

1. Скопируйте все комментарии каталога Unity в соответствующие comment поля в определении YAML. Измените значение атрибута version на 1.1.
2. Сохраните представление метрик.

ALTER VIEW metric_view_name AS
$$
version: 1.1
source: samples.tpch.orders
comment: "Metric view of order (Updated comment)"

dimensions:
- name: order_date
  expr: o_orderdate
  comment: "Date of order - Copied from Unity Catalog"

measures:
- name: total_revenue
  expr: SUM(o_totalprice)
  comment: "Total revenue"
$$

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