指标视图 YAML 语法参考

本页介绍指标视图的完整 YAML 语法。 指标视图定义遵循标准 YAML 表示法语法。

有关每项功能的最小运行时和 YAML 规范版本要求，请参阅 指标视图功能可用性。

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

YAML 概述

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

来源

该 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

筛选器

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 查询用作源。

每个联接定义包括以下字段：

星型架构联接

在星型架构中，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)

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子句中的列即为维度。 每个表达式必须返回标量值。 维度可以引用源数据中的列或指标视图中早期定义的维度。

每个维度定义包括以下字段：

例：

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 。 度量值可以引用源数据、早期定义的维度或早期定义的度量值中的基字段。

每个度量值定义包括以下字段：

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

例：

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 度量值。

每个窗口规范包括以下字段：

窗口度量示例

以下示例计算唯一客户的滚动 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 字段包括以下顶级字段：

每个 materialized_views 条目都包含以下字段：

具体化示例

以下示例定义具有多个具体化的指标视图：

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 的格式。

引用列名称

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

将表达式与冒号一起使用

多行缩进

将 YAML 升级到 1.1

将指标视图升级到 YAML 规范版本 1.1 需要小心，因为注释的处理方式与早期版本中的处理方式不同。

批注类型

• YAML 注释 （#）：使用 #符号直接在 YAML 文件中编写的内联或单行注释。
• Unity Catalog 注释：Unity Catalog 中存储的指标视图或其列（维度和度量值）的注释。 这些注释与 YAML 注释不同。

升级注意事项

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

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

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

1. 使用 ALTER VIEW 命令在笔记本或 SQL 编辑器中。
2. 将原始 YAML 定义复制到之后$$..$$的AS节中。 将 version 的值更改为 1.1。
3. 保存指标视图。

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)
$$

选项 2：保留 Unity 目录注释

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

有关每个功能的 YAML 规范版本历史记录和最低运行时要求，请参阅 指标视图功能可用性。