Справочник по синтаксису YAML

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

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

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

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

• version: По умолчанию 1.1. Это версия спецификации представления метрик. См. журнал изменений спецификации версии.
• source: исходные данные для представления метрик. Это может быть табличный ресурс или SQL-запрос.
• joins: необязательно. Поддерживаются схемы star и соединения схемы snowflake.
• filter: необязательно. Логическое выражение SQL, которое применяется ко всем запросам; WHERE эквивалент предложения.
• comment: необязательно. Описание представления метрик.
• dimensions: массив определений измерений, включая имя измерения и выражение.
• measures: массив столбцов статистических выражений.

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

При ссылке на имена столбцов, содержащих пробелы или специальные символы в выражениях 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"`'	Используйте обратные апострофы, чтобы экранировать двойные кавычки в имени столбца. Заключите это выражение в одинарные кавычки в определении YAML.

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

Случай	Expression	Примечания.
Выражения с двоеточиями	expr: "CASE WHEN Уровень клиента = 'Enterprise: Premium' THEN 1 ELSE 0 END"	Поместите всё выражение в двойные кавычки для правильной интерпретации

Замечание

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

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

Случай	Expression	Примечания.
Многострочная индентация	expr: \| CASE WHEN revenue > 100 THEN 'High' ELSE 'Low' END	Отступите выражение под первой строкой

Замечание

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

Определение измерения

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

dimensions:

  # Column name
  - name: Order date
    expr: o_orderdate

  # SQL expression
  - name: Order month
    expr: DATE_TRUNC('MONTH', `Order date`)

  # Referring to a column with a space in the name
  - name: Month of order
    expr: `Order month`

  # Multi-line expression
  - name: Order status
    expr: CASE
            WHEN o_orderstatus = 'O' THEN 'Open'
            WHEN o_orderstatus = 'P' THEN 'Processing'
            WHEN o_orderstatus = 'F' THEN 'Fulfilled'
          END

Определение меры

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

measures:

  # Basic aggregation
  - name: Total revenue
    expr: SUM(o_totalprice)

  # Basic aggregation with ratio
  - name: Total revenue per customer
    expr: SUM(`Total revenue`) / COUNT(DISTINCT o_custkey)

  # Measure-level filter
  - name: Total revenue for open orders
    expr: COUNT(o_totalprice) FILTER (WHERE o_orderstatus='O')

  # Measure-level filter with multiple aggregate functions
  # filter needs to be specified for each aggregate function in the expression
  - name: Total revenue per customer for open orders
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus='O')/COUNT(DISTINCT o_custkey) FILTER (WHERE o_orderstatus='O')

Сопоставление названий столбцов с помощью YAML в CREATE VIEW

При создании представления метрик с помощью CREATE VIEW и column_list система сопоставляет столбцы, определенные в YAML (меры и измерения), с column_list по позиции, а не по имени.

Это соответствует стандартному поведению SQL, как показано в следующем примере:

CREATE VIEW v (col1, col2) AS SELECT a, b FROM table;

В этом примере a сопоставляется с col1, а b сопоставляется с col2, независимо от их исходных имен.

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

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

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

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

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

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

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

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

1. ALTER VIEW Используйте команду в записной книжке или редакторе SQL.

2. Скопируйте исходное определение YAML в $$.. $$ раздел после AS. Измените значение версии на 1.1.

3. Сохраните представление метрик.

ALTER VIEW metric_view_name AS
$$
# Inline comments are preserved in the notebook
version: 1.1
source: samples.tpch.orders
dimensions:
- name: order_date # Inline comments are preserved in the notebook
  expr: o_orderdate
measures:
# Commented out definition is preserved
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

Предупреждение

При выполнении ALTER VIEW удаляются комментарии каталога Unity, если они явно не включены в comment поля определения YAML. Если вы хотите сохранить комментарии, отображаемые в каталоге Unity, см. вариант 2.

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

Замечание

Следующее руководство применяется только при использовании ALTER VIEW команды в записной книжке или редакторе SQL. При обновлении представления метрик до версии 1.1 с помощью пользовательского интерфейса редактора YAML комментарии каталога Unity будут сохранены автоматически.

1. Скопируйте все комментарии каталога Unity в соответствующие comment поля в определении YAML. Измените значение версии на 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"
$$

Журнал изменений спецификации версии

Версия 1.1 (требуется Databricks Runtime 17.2 или более поздней версии)

• Добавлено:
  • Поддержка функций семантических метаданных. См. раздел "Использование семантических метаданных" в представлениях метрик.
  • Поддержка необязательного поля YAML comment для описания представления метрик, измерений или мер.

Версия 0.1 (требуется Databricks Runtime 16.4–17.1)

• Первоначальный выпуск спецификации представления метрик YAML.