通过

指标视图 YAML 参考

重要

此功能目前以公共预览版提供。

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

YAML 概述

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

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

常规表示法

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

在 YAML 定义中的表达式中引用包含空格或特殊字符的列名时，请考虑以下事项：

  • 反引号转义：将列名称括在反引号 (`) 中，以确保正确引用。 例如，若要引用名称中具有空格的列，请使用 `column name`。

  • 用双引号引起来的反引号转义：如果表达式以经过反引号转义的列名称开头，并且需要成为 YAML 中字符串的一部分，请将整个表达式用双引号引起来，以符合 YAML 标准。 例如，将列名与空格一起使用时，整个表达式可能如下所示 "`column name`"。

来源

可以使用类似表的资产或 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

注释

使用包含 JOIN 子句的 SQL 查询作为源时，Databricks 建议在底层表中设置主键和外键约束，并在查询时酌情选择使用 RELY 选项，以实现最佳性能。 有关使用主键和外键约束的详细信息，请参阅 使用主键约束声明主键和外键关系 以及 查询优化。

将指标视图用作源

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

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 子句。

联接

联接用于对星型架构进行建模，其中源被视为事实数据表，并且可以使用多个 LEFT OUTER JOIN维度表进行联接。 可以使用 on 或 using 子句指定联接列。 该 on 子句允许使用布尔表达式定义联接条件。 using 子句引用两个表中具有相同名称的列。

联接应遵循多对一关系。 以下示例演示如何在指标视图的定义中表达联接。

source: catalog.schema.fact_table

joins:

  # The on clause supports a boolean expression
  - name: dimension_table_1
    source: catalog.schema.dimension_table_1
    on: source.dimension_table_1_fk = dimension_table_1.pk

  # The using clause supports an array of columns
  # found in both of the tables being joined.
  - name: dimension_table_2
    source: catalog.schema.dimension_table_2
    using:
      - dimension_table_2_key_a
      - dimension_table_2_key_b

dimensions:

  # Dimension referencing a join column from dimension_table_1 using dot notation
  - name: Dimension table 1 key
    expr: dimension_table_1.pk

measures:

  # Measure referencing a join column from dimension_table_1
  - name: Count of dimension table 1 keys
    expr: COUNT(dimension_table_1.pk)

注释

命名空间 source 引用指标视图源中的列，而联接 name 引用联接表中的列。 例如，在联接条件 source.dimension_table_1_fk = dimension_table_1.pk中， source 引用指标视图的源表（fact_table），并 dimension_table_1 引用联接表。 如果未在 on 子句中提供任何前缀，则引用默认为联接表。

尺寸

在查询时，维度用于 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)