本页介绍指标视图的完整 YAML 语法。 指标视图定义遵循标准 YAML 表示法语法。
有关每项功能的最小运行时和 YAML 规范版本要求，请参阅 指标视图功能可用性。
请参阅 YAML 规范 1.2.2 文档，了解有关 YAML 规范的详细信息。
YAML 概述
指标视图的 YAML 定义包括以下顶级字段：
| 领域 | 类型 | 说明 |
|---|---|---|
version |
String | 必填。 指标视图规范的版本。 请参阅 YAML 规范版本。 |
comment |
String | 可选。 指标视图的说明。 |
source |
String | 必填。 指标视图的源数据。 可以是任何类似表的 Unity 目录资产，包括指标视图或 SQL 查询。 请参阅 源。 |
filter |
String | 可选。 适用于所有查询的 SQL 布尔表达式。 请参阅 筛选器。 |
joins |
数组 | 可选。 星型架构和雪花架构联接。 请参阅 “联接”。 |
dimensions |
数组 | 有條件的。 维度定义，包括名称、表达式和可选语义元数据。 如果未 measures 指定，则为必需。 请参阅 维度。 |
measures |
数组 | 有條件的。 度量值定义，包括名称、聚合表达式和可选的语义元数据。 如果未 dimensions 指定，则为必需。 请参阅 度量值。 |
materialization |
对象 | 可选。 使用具体化视图加速查询的配置。 包括刷新计划和具体化视图定义。 请参阅 具体化。 |
来源
该 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
注释
将 SQL 查询用作包含 JOIN 子句的源时，对基础表设置主键和外键约束，并使用 RELY 该选项来获得最佳查询性能。 有关详细信息，请参阅 使用主键约束声明主键和外键关系 以及 查询优化。
筛选器
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'
联接
指标视图中的联接支持从事实数据表到维度表（星型架构）和跨规范化维度表的多跃点联接（雪花架构）。 还可以使用 SELECT 语句联接到 SQL 查询。 请参阅 将 SQL 查询用作源。
注释
联接表不能包含 MAP 类型列。 若要从 MAP 类型列解包值，请参阅 映射或数组中的“分解嵌套元素”。
每个联接定义包括以下字段：
| 领域 | 类型 | 说明 |
|---|---|---|
name |
String | 必填。 联接表或 SQL 查询的别名。 在维度或度量值中引用联接表中的列时，请使用此别名。 |
source |
String | 必填。 要联接的表的三部分名称。 也可以是 SQL 查询。 |
on |
String | 有條件的。 定义联接条件的布尔表达式。
using如果未指定，则为必需。 |
using |
数组 | 有條件的。 父表和联接表中的列名列表。
on如果未指定，则为必需。 |
joins |
数组 | 可选。 雪花架构建模的嵌套联接定义列表。 有关最低运行时要求，请参阅 指标视图功能可用性 。 |
星型架构联接
在星型架构中，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)
注释
命名空间 source 引用指标视图源中的列，而联接引用该联接表中的 name 列。 例如，在中source.l_orderkey = orders.o_orderkeysource，引用lineitem并orders引用联接表。 如果未在子句中 on 提供前缀，则引用默认为联接表。
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子句中的列即为维度。 每个表达式必须返回标量值。 维度可以引用源数据中的列或指标视图中早期定义的维度。
每个维度定义包括以下字段：
| 领域 | 类型 | 说明 |
|---|---|---|
name |
String | 必填。 维度的列别名。 |
expr |
String | 必填。 可以引用源数据或以前定义的维度中的列的 SQL 表达式。 |
comment |
String | 可选。 维度的说明。 显示在 Unity 目录和文档工具中。 |
display_name |
String | 可选。 可视化工具中显示的标签。 限制为 255 个字符。 需要 YAML 规范 1.1。 请参阅 指标视图功能可用性。 |
format |
地图 | 可选。 如何显示值的格式规范。 需要 YAML 规范 1.1。 请参阅 格式规范。 |
synonyms |
数组 | 可选。 用于发现维度的 AI 和 BI 工具的替代名称。 最多 10 个同义词，每个同义词限制为 255 个字符。 需要 YAML 规范 1.1。 请参阅 同义词。 |
例：
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 。 度量值可以引用源数据、早期定义的维度或早期定义的度量值中的基字段。
每个度量值定义包括以下字段：
| 领域 | 类型 | 说明 |
|---|---|---|
name |
String | 必填。 度量值的别名。 |
expr |
String | 必填。 包含一个或多个聚合函数的 SQL 表达式。 |
comment |
String | 可选。 度量值的说明。 显示在 Unity 目录和文档工具中。 |
display_name |
String | 可选。 可视化工具中显示的标签。 限制为 255 个字符。 需要 YAML 规范 1.1。 请参阅 指标视图功能可用性。 |
format |
地图 | 可选。 如何显示值的格式规范。 需要 YAML 规范 1.1。 请参阅 格式规范。 |
synonyms |
数组 | 可选。 用于发现度量值的 AI 和 BI 工具的替代名称。 最多 10 个同义词，每个同义词限制为 255 个字符。 需要 YAML 规范 1.1。 请参阅 指标视图功能可用性。 |
window |
数组 | 可选。 窗口规范，用于窗口聚合、累积聚合或半累加聚合。 如果未指定，则度量值的行为为标准聚合。 请参阅 窗口度量值。 |
请参阅 聚合函数 获取聚合函数列表。
例：
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 字段定义度量值的窗口化、累积聚合或半累加聚合。 有关窗口度量值和用例的详细信息，请参阅 Window 度量值。
每个窗口规范包括以下字段：
| 领域 | 类型 | 说明 |
|---|---|---|
order |
String | 必填。 确定窗口排序的维度。 (1) |
range |
String | 必填。 窗口的范围。 请参阅 支持 range 的值。 |
semiadditive |
String | 必填。 聚合方法。 支持的值：first 或 last。 |
（1） 引用的维度应具有确定性。 非确定性表达式，例如 rand()， uuid()或 current_timestamp() 生成不可预知的窗口排序，并可能导致不正确的聚合结果。
支持的 range 值
-
current：窗口排序值等于当前行值的行。 -
cumulative：窗口排序值小于或等于当前行值的所有行。 -
trailing <value> <unit>：当前行中的行按指定的时间单位向后移动，例如trailing 7 day。 不包括当前单元。 -
leading <value> <unit>：按指定时间单位前进的当前行中的行，例如leading 3 month。 不包括当前单元。 -
all：无论窗口排序值如何，所有行。
窗口度量示例
以下示例计算唯一客户的滚动 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 字段包括以下顶级字段：
| 领域 | 类型 | 说明 |
|---|---|---|
schedule |
String | 必填。 刷新计划。 对 具体化视图使用与 schedule 子句相同的语法。 不支持 TRIGGER ON UPDATE 子句。 |
mode |
String | 必填。 必须设置为 relaxed。 |
materialized_views |
数组 | 必填。 要具体化的具体化视图的列表。 每个条目都需要下面所述的字段。 |
每个 materialized_views 条目都包含以下字段：
| 领域 | 类型 | 说明 |
|---|---|---|
name |
String | 必填。 具体化的名称。 |
type |
String | 必填。 具体化类型。 支持的值： aggregated （需要 dimensions或 measures两者）或 unaggregated。 |
dimensions |
数组 | 有條件的。 要具体化的维度名称列表。 如果需要typeaggregated且未measures指定，则为必需。 |
measures |
数组 | 有條件的。 要具体化的度量值名称列表。 如果需要typeaggregated且未dimensions指定，则为必需。 |
具体化示例
以下示例定义具有多个具体化的指标视图：
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 的格式。
引用列名称
以下示例演示如何根据列引用包含的字符设置列引用的格式。
无空格
源列： 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"
注释
YAML 将无引号冒号解释为键值分隔符。 始终对包含冒号的表达式使用双引号。
多行表达式
expr: |
CASE WHEN
revenue > 100 THEN 'High'
ELSE 'Low'
END
注释
在|之后使用expr: 块标量以处理多行表达式。 为了正确解析，所有行必须在 expr 键之外至少缩进两个空格。
升级到 YAML 1.1
将指标视图升级到 YAML 规范版本 1.1 需要小心，因为注释的处理方式与早期版本中的处理方式不同。
批注类型
-
YAML 注释 （
#）：直接在 YAML 文件中编写的内联或单行注释。 - Unity 目录注释：存储在 Unity 目录中的指标视图或其列的注释。 这些注释与 YAML 注释不同。
升级注意事项
选择与在指标视图中处理注释的方式匹配的升级路径。
选项 1：使用笔记本或 SQL 编辑器保留 YAML 注释
如果指标视图包含要保留的 YAML 注释（#），请使用以下步骤：
- 使用
ALTER VIEW命令在笔记本或 SQL 编辑器中。 - 将原始 YAML 定义复制到之后
$$..$$的AS节中。 将version的值更改为1.1。 - 保存指标视图。
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)
$$
警告
运行 ALTER VIEW 会删除 Unity 目录注释，除非它们显式包含在 comment YAML 定义的字段中。 若要保留 Unity 目录中显示的注释，请参阅 选项 2。
选项 2：保留 Unity 目录注释
注释
以下指南仅适用于在笔记本或 SQL 编辑器中使用 ALTER VIEW 命令时。 如果使用 YAML 编辑器 UI 将指标视图升级到版本 1.1，则 YAML 编辑器 UI 会自动保留 Unity 目录注释。
- 将所有 Unity 目录注释复制到 YAML 定义中的相应
comment字段。 将version的值更改为1.1。 - 保存指标视图。
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 规范版本历史记录和最低运行时要求，请参阅 指标视图功能可用性。