指标视图 YAML 语法参考

指标视图定义使用标准 YAML 语法声明源、联接、字段、度量值、筛选器、窗口度量值和具体化。 以下各节记录了每个语法的完整语法。

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

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

在指标视图编辑器中编辑 YAML

可以直接在指标视图编辑器中编写和编辑此页上所述的 YAML。 在目录资源管理器中，打开指标视图，然后单击 <> 按钮编辑定义。 若要改为从自然语言说明生成 YAML，请从编辑器打开 Genie Code。 有关完整的编辑器演练，请参阅 “创建指标”视图。

顶级 YAML 字段

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

Source

该 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

Parameters

该 parameters 块定义调用方在将指标视图查询为表值函数时传递的命名值。 有关何时以及如何使用参数（包括查询参数化指标视图）的信息，请参阅 将参数与指标视图配合使用。

每个参数定义包括以下字段：

以下示例定义参数 discount 并在度量值表达式中引用它：

version: 1.1
source: main.default.sales

parameters:
  - name: discount
    data_type: double
    default: 0

fields:
  - name: product
    expr: product

measures:
  - name: discountedSales
    expr: SUM((1 - discount) * amount)

筛选器

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'

Joins

指标视图中的联接支持从事实数据表到维度表（星型架构）和跨规范化维度表的多跃点联接（雪花架构）。 还可以使用 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

fields:
  - 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

fields:
  - name: customer_nation
    expr: customer.nation.n_name

一对多联接

该 cardinality 字段设置源表与联接表之间的关系。 many_to_one默认值将联接表视为维度查找。 设置为 cardinality: one_to_many 将联接表视为引擎在源粒度上独立聚合的事实源，这样一个源行就可以匹配联接表中的多行。 一对多联接需要 Databricks Runtime 18.1 或更高版本，以及 YAML 规范 1.1 版。 请参阅 指标视图功能可用性。

以下规则适用于一对多联接：

• 一对多列不能用于 fields 定义，因为字段必须解析为每个源行的单个值。
• 单个聚合函数必须引用来自一个源的列。 可以跨单独的聚合结果应用算术，例如 count(orders.order_id) / count(*)。
• 一对多联接的所有后代也必须是 one_to_many。 顶级同级联接可以混合基数。
• 通过联接名称引用嵌套联接中的列及其完整的点路径，例如 orders.order_items.item_id。

以下示例联接 orders 到 customers 源 cardinality: one_to_many ，以便订单度量值聚合而不复制客户行：

version: 1.1
source: main.sales.customers

joins:
  - name: orders
    source: main.sales.orders
    on: orders.customer_id = source.customer_id
    cardinality: one_to_many

fields:
  - name: customer_name
    expr: customer_name

measures:
  - name: customer_count
    expr: count(*)
  - name: order_count
    expr: count(orders.order_id)
  - name: total_order_revenue
    expr: sum(orders.amount)

有关概念详细信息和嵌套联接示例和同级联接示例，请参阅 Join 基数。

使用 优化联接

rely使用联接上的字段声明有关查询分析器在规划查询时使用的关系的保证。 这些保证使引擎能够更高效地规划查询并减少扫描的数据，尤其是在筛选器中引用联接表中的字段时。

地图 rely 支持以下字段：

以下示例对从at_most_one_matchorders多对一联接启用 customer 。 按客户属性筛选或分组的查询最受益：

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    rely:
      at_most_one_match: true

fields:
  - name: Customer name
    expr: customer.c_name
  - name: Customer market segment
    expr: customer.c_mktsegment

measures:
  - name: Total revenue
    expr: SUM(o_totalprice)

Fields

字段是查询时使用的SELECTWHERE指标视图列和GROUP BY子句。 每个表达式必须返回标量值。 字段可以引用源数据中的列或指标视图中早期定义的字段。

字段可以是：

• 分类或分组列，例如区域、状态或部门。
• 未聚合的数字列，例如年龄、价格或数量。 可以使用 SQL 函数（例如 SUM 或 AVG） 在查询时聚合数值字段。

每个字段定义包括以下属性：

Example:

fields:
  # Basic field
  - name: order_date
    expr: o_orderdate
    comment: 'Date the order was placed'
    display_name: 'Order Date'

  # Field with SQL expression
  - name: order_month
    expr: DATE_TRUNC('MONTH', o_orderdate)
    display_name: 'Order Month'

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

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

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

Example:

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']

使用通配符批量导入字段和度量值

适用于： 使用 YAML 规范 1.1 的 Databricks Runtime 18.2 及更高版本

在或fieldsmeasures定义中*，可以使用字段中的通配符（expr）从源表或联接表导入所有列，而无需列出每个列。 如果希望指标视图公开来自上游资产的每个列，类似于 SELECT * 标准视图中，这非常有用。 Azure Databricks创建或替换指标视图时将通配符扩展到具体列，并从源列名称派生每个列名。

与显式列定义一样，创建指标视图时会扩展通配符表达式。 若要稍后选取添加到源的列， CREATE OR REPLACE 请使用或 ALTER.

通配符支持以下形式：

以下规则适用于通配符表达式：

• 省略字段 name 。 Azure Databricks从源派生列名，因此name不允许在通配符表达式上使用。
• 通配符表达式上不允许语义元数据。 请勿在通配符上设置comment、display_nameformat设置或synonyms设置。 若要将元数据添加到特定列，请将其从通配符 EXCEPT 中排除并显式定义。
• measures在定义中，通配符仅从指标视图源导入度量值。 基表没有度量值，因此当源是基表时，通配符将扩展到无度量值。
• 不能在以后 fields 或 measures 表达式中按其派生名称引用通配符导入的列。 请改用其完整路径引用源列。

解决名称冲突

使用通配符从多个源导入列时，共享名称（如 id 或 date）的列会冲突，并在保存定义时导致错误。 若要解决冲突，请从每个通配符 EXCEPT中排除该列，然后使用唯一名称显式定义该列：

fields:
  - expr: source.* EXCEPT (id)
  - expr: customer.* EXCEPT (id)
  - name: source_id
    expr: source.id
  - name: customer_id
    expr: customer.id

通配符示例

以下定义从源和联接表导入所有列，排除两列，并显式定义一列以添加元数据：

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    joins:
      - name: nation
        source: samples.tpch.nation
        on: customer.c_nationkey = nation.n_nationkey

fields:
  # Import all columns from the source
  - expr: source.*

  # Import all columns from a joined table, excluding two
  - expr: customer.nation.* EXCEPT (n_name, n_comment)

  # Define a specific column explicitly to add metadata
  - name: nation_name
    expr: customer.nation.n_name
    comment: "Customer's nation"
    display_name: 'Nation Name'

窗口测量

该 window 字段定义度量值的窗口化、累积聚合或半累加聚合。 有关窗口度量值和用例的详细信息，请参阅 Window 度量值。

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

（1） 引用的字段必须是确定性的。 非确定性表达式，例如 rand()， uuid()或 current_timestamp() 生成不可预知的窗口排序，并可能导致不正确的聚合结果。

支持 range 的值

• current：窗口排序值等于定位行值的行。
• cumulative：窗口排序值小于或等于定位行值的所有行。
• trailing <value> <unit> [inclusive | exclusive]：定位行中的行按指定的时间单位向后移动，例如 trailing 7 day。 可选 inclusive 或 exclusive 修饰符需要 Databricks Runtime 18.1 和 YAML 规范版本 1.1 或更高版本，并控制定位行是否包含在窗口中。 默认值为 exclusive。 请参阅“包含或排除锚定行”。
• leading <value> <unit> [inclusive | exclusive]：按指定时间单位前进的定位行中的行，例如 leading 3 month。 可选 inclusive 或 exclusive 修饰符需要 Databricks Runtime 18.1 和 YAML 规范版本 1.1 或更高版本，并控制定位行是否包含在窗口中。 默认值为 exclusive。 请参阅“包含或排除锚定行”。
• all：无论窗口排序值如何，所有行。

窗口度量示例

以下示例计算唯一客户的滚动 7 天计数：

version: 1.1
source: samples.tpch.orders

fields:
  - 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

fields:
  - 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
      cluster_by:
        cols:
          - order_date
          - order_status
      partition_by:
        - order_date

列名引用

在 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"

多行表达式

expr: |
  CASE WHEN
    revenue > 100 THEN 'High'
  ELSE 'Low'
  END

升级到 YAML 1.1

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

批注类型

• YAML 注释 （#）：直接在 YAML 文件中编写的内联或单行注释。
• Unity 目录注释：存储在 Unity 目录中的指标视图或其列的注释。 这些注释与 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
fields:
- 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)"

fields:
- 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 规范版本历史记录和最低运行时要求，请参阅 指标视图功能可用性。