指标视图 YAML 参考

本页介绍用于定义指标视图的 YAML 的每个组件。

YAML 概述

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

• version： 默认值为 1.1. 这是指标视图规范的版本。 请参阅 版本规范更改日志。
• source： 指标视图的源数据。 这可以是表状结构的资产或 SQL 查询。
• joins： 可选。 支持星型架构和雪花架构联接。
• filter： 可选。 适用于所有查询的 SQL 布尔表达式;等效于子 WHERE 句。
• comment： 可选。 指标视图的说明。
• dimensions： 维度定义的数组，包括维度名称和表达式。
• measures： 聚合表达式列的数组。

YAML 语法和格式设置

指标视图定义遵循标准 YAML 表示法语法。 请参阅 YAML 规范 1.2.2 文档，了解有关 YAML 规范的详细信息。

列名引用

在 YAML 表达式中引用包含空格或特殊字符的列名时，请将列名括在反引号中以转义空格或字符。 如果表达式以反引号开头，并且直接用作 YAML 值，请将整个表达式包装在双引号中。 有效的 YAML 值不能以反杆开头。

格式设置示例

使用以下示例了解如何在常见方案中正确设置 YAML 的格式。

引用列名称

下表显示如何根据列名称包含的字符设置列名称的格式。

将表达式与冒号一起使用

多行缩进

来源

可以使用类似表的资产或 SQL 查询作为指标视图的源。 若要使用类似表的资产，必须至少拥有对该资产的SELECT特权。

将表用作源

若要将表用作源，请包括完全限定的表名称，如以下示例所示。

source: samples.tpch.orders

使用 SQL 查询作为源

若要使用 SQL 查询，请直接在 YAML 中编写查询文本。

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

将指标视图用作源

还可以使用现有指标视图作为新指标视图的源：

version: 0.1
source: views.examples.source_metric_view

dimensions:

  # Dimension referencing dimension from source_metric_view
  - name: Order date
    expr: order_date_dim

measures:

  # Measure referencing dimension from source_metric_view
  - name: Latest order month
    expr: MAX(order_date_dim_month)

  # Measure referencing measure from source_metric_view
  - name: Latest order year
    expr: DATE_TRUNC('year', MEASURE(max_order_date_measure))

将指标视图用作源时：

• 新指标视图中的维度可以引用源指标视图中的任何维度。

• 新指标视图中的度量值可以引用源指标视图中的任何维度或度量值。

所有其他可组合性规则都适用。 请参阅 “可组合性”。

过滤器

指标视图的 YAML 定义中的筛选器适用于引用它的所有查询。 它必须编写为 SQL 布尔表达式，并且等效于在 SQL 查询中使用 WHERE 子句。

加入

联接定义指标视图的源和其他源（例如表、视图或其他指标视图）之间的关系。 可以使用联接对事实数据表到维度表（星型架构）之间的关系建模，以及从维度遍历到子维度，从而允许跨规范化维度表（雪花架构）进行多跃点联接。 如果加入另一个指标视图，则下游指标视图中仅提供其维度。

仅当使用 Databricks Runtime 计算 17.1 及更高版本时，才支持 Snowflake 联接。 请参阅 指标视图中的“使用联接”。

尺寸

维度在查询时用于SELECT、WHERE和GROUP BY子句。 每个表达式必须返回标量值。 每个维度由两个组件组成：

• name：列的别名。

• expr：定义维度的源数据的 SQL 表达式。

以下示例演示如何定义维度：

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

措施

度量值是一个聚合表达式数组，用于定义聚合结果，而无需预先确定聚合级别。 它们必须表示为聚合函数。 若要在查询中引用度量值，必须使用函数 MEASURE 。 每个度量值由以下组件组成：

• name：度量值的别名。

• expr：可以包含 SQL 聚合函数的聚合 SQL 表达式。

请参阅 聚合函数 获取聚合函数列表。

请参阅 measure 聚合函数。

以下示例演示如何定义度量值：

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 中定义的维度。
• 度量值可以引用所有维度。
• 度量值可以引用以前使用 MEASURE() 函数定义的度量值。

以下示例演示如何组合维度和度量值：

dimensions:

  # Dimension referencing a source column
  - name: Order month
    expr: DATE_TRUNC('month', o_orderdate)

  # Dimension referencing a previously defined dimension
  - name: Previous order month
    expr: ADD_MONTHS(`Order Month`, -1)

measures:

  # Measure referencing a dimension
  - name: Earliest order month
    expr: MIN(`Order month`)

  # Measure referencing a source column
  - name: Revenue
    expr: SUM(sales_amount)

  # Measure referencing a source column
  - name: Costs
    expr: SUM(item_cost)

  # Measure referencing previously defined measures
  - name: Profit
    expr: MEASURE(Revenue) - MEASURE(Costs)

使用 YAML 进行 CREATE VIEW 列名称映射

使用 CREATE VIEW a 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 注释（#），请使用以下步骤：

1. 在笔记本或 SQL 编辑器中使用 ALTER VIEW 命令。

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

1. 将所有 Unity 目录注释复制到 YAML 定义中的相应 comment 字段。 将版本值更改为 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

• 添加了：
  • 支持语义元数据功能。 请参阅 在指标视图中使用语义元数据。
  • 支持可选的 YAML comment 字段来描述指标视图、维度或度量值。

版本 0.1

• 指标视图 YAML 规范的初始发布。