YAML 语法参考

指标视图定义遵循标准 YAML 表示法语法。本页介绍如何定义指标视图。

请参阅 YAML 规范 1.2.2 文档，了解有关 YAML 规范的详细信息。

YAML 概述

指标视图的 YAML 定义包括以下顶级字段：

version： 默认值为 1.1. 这是指标视图规范的版本。请参阅版本规范更改日志。
source： 指标视图的源数据。这可以是表状结构的资产或 SQL 查询。
joins： 可选。支持星型架构和雪花架构联接。
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 Catalog 注释：Unity Catalog 中存储的指标视图或其列（维度和度量值）的注释。这些注释与 YAML 注释不同。

升级注意事项

选择与在指标视图中处理注释的方式匹配的升级路径。以下选项描述了可用的方法并提供示例。

选项 1：使用笔记本或 SQL 编辑器保留 YAML 注释

如果指标视图包含要保留的 YAML 注释（#），请使用以下步骤：

在笔记本或 SQL 编辑器中使用 ALTER VIEW 命令。
将原始 YAML 定义复制到 $$..$$ 部分，位于 AS 之后。将版本值更改为 1.1。

保存指标视图。

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 目录注释

注释

以下指南仅适用于在笔记本或 SQL 编辑器中使用 ALTER VIEW 命令时。如果使用 YAML 编辑器 UI 将指标视图升级到版本 1.1，则会自动保留 Unity 目录注释。

将所有 Unity 目录注释复制到 YAML 定义中的相应 comment 字段。将版本值更改为 1.1。