YAML 語法參考

計量檢視定義遵循標準 YAML 表示法語法。 本頁說明如何定義度量檢視。

請參閱 YAML 規格 1.2.2 文件，以進一步瞭解 YAML 規格。

YAML 概觀

度量檢視的 YAML 定義包含下列最上層欄位：

• version： 預設為 1.1。 這是計量檢視規格的版本。 請參閱 版本規格變更日誌。
• source： 計量檢視的源數據。 這可以是類似數據表的資產或 SQL 查詢。
• joins： 選擇性。 支援星狀架構和雪花式架構聯結。
• filter： 選擇性。 適用於所有查詢的 SQL 布爾表示式;相當於 WHERE 子句。
• comment： 選擇性。 度量視圖的描述。
• dimensions： 維度定義的陣列，包括維度名稱和表達式。
• measures： 匯總表達式數據行的陣列。

欄位名稱參考

在 YAML 運算式中參照包含空格或特殊字元的直欄名稱時，請將直欄名稱括在反引號中，以逸出空格或字元。 如果運算式以反引號開頭，並直接用作 YAML 值，請將整個運算式括在雙引號中。 YAML 的有效值不能以反引號開頭。

格式範例

使用下列範例來瞭解如何在常見案例中正確格式化 YAML。

參考欄名稱

下表顯示如何根據資料行名稱所包含的字元來設定資料行名稱的格式。

使用帶有冒號的表達式

多行縮排

定義維度

下列範例示範如何定義維度：

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

定義量值

下列範例示範如何定義量值：

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 進行 CREATE VIEW 資料行名稱對應

當您使用 CREATE VIEW 搭配 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)
$$

選項 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 版 （需要 Databricks Runtime 17.2 或更新版本）

• 新增：
  • 支援語意中繼資料功能。 請參閱在度量視圖中使用語意中繼資料。
  • 支援選用 YAML comment 欄位，以描述度量檢視、維度或量值。

0.1 版 （需要 Databricks Runtime 16.4 到 17.1）

• 度量視圖 YAML 規範的初始版本。