指标视图 YAML 参考

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

YAML 概述

指标视图的 YAML 定义包括六个顶级字段：

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

YAML 语法和格式设置

指标视图定义遵循标准 YAML 表示法语法。 请参阅 yaml.org 的文档 ，了解有关 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它们。