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

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

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

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

Изменение YAML в редакторе представления метрик

Вы можете написать и изменить YAML, описанный на этой странице, непосредственно в редакторе представления метрик. В обозревателе каталогов откройте представление метрик и нажмите <> кнопку, чтобы изменить определение. Чтобы создать YAML из описания естественного языка, откройте Genie Code из редактора. Полное пошаговое руководство по редактору см. в разделе "Создание представления метрик".

Поля 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

Параметры

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

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

В следующем примере определяется discount параметр и ссылается на него в выражении меры:

version: 1.1
source: main.default.sales

parameters:
  - name: discount
    data_type: double
    default: 0

fields:
  - name: product
    expr: product

measures:
  - name: discountedSales
    expr: SUM((1 - discount) * amount)

Filter

Фильтр в определении 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'

Joins

Соединения в представлениях метрик поддерживают прямые объединения из таблицы фактов с таблицами измерений (схема звезды) и многошаговые объединения через нормализованные таблицы измерений (схемы снежинки). Вы также можете присоединиться к 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

fields:
  - 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, вложенную 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

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

Соединения "один ко многим"

Поле cardinality задает связь между источником и присоединенной таблицей. Значение по умолчанию many_to_oneобрабатывает присоединенную таблицу как подстановку измерения. Установите cardinality: one_to_many для обработки присоединенной таблицы как источника фактов, который подсистема агрегирует независимо в исходном зерне, что позволяет одной исходной строке совпадать с несколькими строками в присоединенной таблице. Для соединений с одним ко многим требуется Databricks Runtime 18.1 или более поздней версии и спецификация YAML версии 1.1. См. сведения о доступности функций представления метрик.

Следующие правила применяются к соединениям "один ко многим":

• Столбец "один ко многим" нельзя использовать в fields определении, так как поле должно разрешаться в одно значение для каждой исходной строки.
• Одна функция агрегирования должна ссылаться на столбцы из одного источника. Вы можете применить арифметику в результатах отдельных агрегатов, например count(orders.order_id) / count(*).
• Все потомки соединения "один ко многим" также должны быть one_to_many. Соединения с братьями верхнего уровня могут смешивать кратности.
• Ссылка на столбец в вложенном соединении со своим полным точечным путем через имена соединения, например orders.order_items.item_id.

В следующем примере выполняется присоединение orders к источнику customers таким cardinality: one_to_many образом, чтобы меры заказа меры агрегированы без дублирования строк клиента:

version: 1.1
source: main.sales.customers

joins:
  - name: orders
    source: main.sales.orders
    on: orders.customer_id = source.customer_id
    cardinality: one_to_many

fields:
  - name: customer_name
    expr: customer_name

measures:
  - name: customer_count
    expr: count(*)
  - name: order_count
    expr: count(orders.order_id)
  - name: total_order_revenue
    expr: sum(orders.amount)

Общие сведения и примеры соединения с вложенными элементами см. в разделе "Кратность соединения".

Оптимизация соединений с помощью rely

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

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

В следующем примере включено at_most_one_match соединение "многие к одному".orderscustomer Запросы, которые фильтруют или группировать по атрибутам клиента, наиболее эффективно:

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    rely:
      at_most_one_match: true

fields:
  - name: Customer name
    expr: customer.c_name
  - name: Customer market segment
    expr: customer.c_mktsegment

measures:
  - name: Total revenue
    expr: SUM(o_totalprice)

Поля

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

Поле может быть следующим:

• Категориальный столбец или столбец группировки, например регион, состояние или отдел.
• Неуверенный числовый столбец, например возраст, цена или количество. Числовые поля можно агрегировать во время запроса с помощью таких функций SQL, как SUM или AVG.

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

Example:

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

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

  # Field 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 . Показатели могут ссылаться на базовые столбцы в исходных данных, ранее определённые поля или ранее определённые показатели.

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

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

Example:

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']

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

Применимо к: Databricks Runtime 18.2 и более поздних версий с спецификацией YAML 1.1

fields В определении measures можно использовать подстановочный знак (*) в expr поле для импорта всех столбцов из источника или присоединенной таблицы без перечисления каждой из них. Это полезно, если требуется представление метрик для предоставления каждого столбца из вышестоящего ресурса, аналогичного SELECT * стандартному представлению. Azure Databricks расширяет подстановочный знак к конкретным столбцам при создании или замене представления метрик и наследует каждое имя столбца из имени исходного столбца.

Как и явные определения столбцов, выражения подстановочных знаков расширяются при создании представления метрик. Чтобы получить столбцы, добавленные в источник позже, повторно создайте представление метрик с CREATE OR REPLACE или ALTER.

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

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

• Опустите name поле. Azure Databricks наследует имена столбцов из источника, поэтому name не допускается для выражения подстановочного знака.
• Семантические метаданные не допускаются в выражении подстановочного знака. Не устанавливайте commentподстановочный display_nameformatзнак, или synonyms подстановочный знак. Чтобы добавить метаданные в определенный столбец, исключите его из подстановочного знака EXCEPT и явно определите его.
• measures В определении подстановочный знак импортирует меры только из источника представления метрик. Базовые таблицы не имеют мер, поэтому подстановочный знак не расширяется до никаких мер, когда источник является базовой таблицей.
• Вы не можете ссылаться на подстановочный знак импортируемого столбца по его производном имени в дальнейшем fields или measures выражении. Вместо этого указать исходный столбец с полным путем.

Устранение конфликтов имен

При импорте столбцов из нескольких источников с подстановочным знаком столбцы, которые совместно используют имя (например id , или date) и вызывают ошибку при сохранении определения. Чтобы устранить столкновение, исключите столбец из каждого подстановочного знака EXCEPT, а затем определите его явным образом с уникальным именем:

fields:
  - expr: source.* EXCEPT (id)
  - expr: customer.* EXCEPT (id)
  - name: source_id
    expr: source.id
  - name: customer_id
    expr: customer.id

Пример подстановочного знака

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

version: 1.1
source: samples.tpch.orders

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

fields:
  # Import all columns from the source
  - expr: source.*

  # Import all columns from a joined table, excluding two
  - expr: customer.nation.* EXCEPT (n_name, n_comment)

  # Define a specific column explicitly to add metadata
  - name: nation_name
    expr: customer.nation.n_name
    comment: "Customer's nation"
    display_name: 'Nation Name'

Размеры окна

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

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

(1) Указанное поле должно быть детерминированным. Недетерминированные выражения, такие как rand(), uuid()или current_timestamp() непредсказуемое упорядочивание окон и могут привести к неправильным результатам агрегирования.

Поддерживаемые значения range

• current: строки, в которых значение порядка окна равно значению строки привязки.
• cumulative: все строки, в которых значение порядка окна меньше или равно значению строки привязки.
• trailing <value> <unit> [inclusive | exclusive]: строки из строки привязки, идут назад по указанным единицам времени, например trailing 7 day. Необязательный inclusive или exclusive модификатор требует Databricks Runtime 18.1 и спецификации YAML версии 1.1 или более поздней, а также определяет, включена ли строка привязки в окно. Значение по умолчанию — exclusive. См. раздел "Включить или исключить строку привязки".
• leading <value> <unit> [inclusive | exclusive]: строки из строки привязки, исходя из указанной единицы времени, например leading 3 month. Необязательный inclusive или exclusive модификатор требует Databricks Runtime 18.1 и спецификации YAML версии 1.1 или более поздней, а также определяет, включена ли строка привязки в окно. Значение по умолчанию — exclusive. См. раздел "Включить или исключить строку привязки".
• all: все строки независимо от значения упорядочения окна.

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

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

version: 1.1
source: samples.tpch.orders

fields:
  - 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

Передайте параметр размера окна

Вместо того чтобы жёстко кодировать числовое значение в a trailing или leadingrange или в offset, вы можете ссылаться на параметр, поэтому вызывающий передаёт размер окна при запросе к метрическому представлению. Для этого требуется SQL-хранилище или другой вычислительный ресурс с Databricks Runtime 18.2 и выше.

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

• Параметры data_type должны быть интегралными, такими intкак , smallint, или bigint.
• Значение должно быть чистым именем параметра, а не выражением. Например, используйте trailing window_size day, а не trailing window_size + 1 day. Также нельзя записать знак перед именем параметра, например -window_size , в offset. Чтобы пройти отрицательный смещение, поместите знак внутрь значения параметра.
• Параметр нельзя называть по ключевому слову окна, например, по типу диапазона (trailing, leading), периоду (day, month, year), ключевому слову инклюзивности (inclusive, exclusive) или offset.
• Единица остаётся буквальной. Вы можете параметризировать только числовую величину, а не период.

Следующий пример определяет window_size параметр и ссылается на него в определённом trailing диапазоне, поэтому каждый звонящий выбирает количество дней в скользящем окне:

version: 1.1
source: samples.tpch.orders

parameters:
  - name: window_size
    data_type: int
    default: 7

fields:
  - name: order_date
    expr: o_orderdate

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

Для запроса к метрическому представлению, определяющему параметры, см. Запрос к метрическому виду с параметрами.

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

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

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

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

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

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

version: 1.1
source: prod.operations.orders_enriched_view
filter: revenue > 0
# filter, fields, and measures can't use invoker-dependent expressions: no current_user(), is_member(), etc.
# source can't have RLS, column masking, or ABAC policies

joins:
  - name: customers
    source: prod.operations.customers
    on: source.customer_id = customers.id
    # if one-to-many, all materializations below drop to exact match only

fields:
  - name: category
    expr: substring(category, 5)
  - name: order_date
    expr: order_date

measures:
  - name: total_revenue
    expr: SUM(revenue)

  - name: number_of_suppliers
    expr: COUNT(DISTINCT supplier_id)

  - name: revenue_for_open_orders
    expr: SUM(revenue) FILTER (WHERE status = 'O')

  - name: blended_margin
    expr: SUM(revenue) - SUM(cost)

  - name: rolling_7day_customers
    expr: COUNT(DISTINCT customer_id)
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

materialization:
  schedule: every 6 hours
  mode: relaxed

  materialized_views:
    - name: baseline
      type: unaggregated
      # only one allowed per metric view; doesn't use dimensions or measures keys
      # no benefit if source is an unfiltered direct table reference

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - category # avoid overly granular dimensions, such as millisecond timestamps
      measures:
        - total_revenue # rollup-eligible
        - number_of_suppliers # exact match only (non-additive)
        - revenue_for_open_orders # rollup-eligible (deterministic filter)
        - blended_margin # exact match only (multiple aggregates)
        - rolling_7day_customers # exact match only (window measure)
      cluster_by:
        cols:
          - order_date
          - category
      partition_by:
        - order_date

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

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

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

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

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

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

Пробелы отсутствуют

Исходный столбец: revenue

expr: "revenue"
expr: 'revenue'
expr: revenue

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

Имя столбца с пробелами

Исходный столбец: `First Name`

expr: '`First Name`'

Используйте обратные апострофы для экранирования пробелов. Заключите все выражение в двойные кавычки.

Имена столбцов с пробелами в выражении SQL

Исходные столбцы: `First Name`, `Last Name`

expr: CONCAT(`First Name`, ' ', `Last Name`)

Если выражение не начинается с обратного выражения, двойные кавычки не требуются.

Имя столбца, содержащее кавычки

Исходный столбец: "name"

expr: '`"name"`'

Используйте обратные знаки, чтобы экранировать двойные кавычки в имени столбца. Заключите выражение в одинарные кавычки.

Выражения с двоеточиями

expr: "CASE WHEN `Customer Tier` = 'Enterprise: Premium' THEN 1 ELSE 0 END"

Многострочный выражения

expr: |
  CASE WHEN
    revenue > 100 THEN 'High'
  ELSE 'Low'
  END

Обновление до 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
fields:
- 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)"

fields:
- 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 и минимальных требованиях к среде выполнения для каждой функции см. в разделе "Доступность функций представления метрик".