YAML 構文リファレンス

メトリック ビューの定義は、標準の YAML 表記構文に従います。 このページでは、メトリック ビューを定義する方法について説明します。

YAML 仕様の詳細については、 YAML 仕様 1.2.2 のドキュメントを参照してください。

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 ファイルに直接書き込まれたインラインまたは 1 行のコメント。
• Unity カタログのコメント: メトリック ビューまたはその列 (ディメンションとメジャー) の Unity カタログに格納されているコメント。 これらは 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. YAML 定義内の適切な comment フィールドにすべての Unity カタログ コメントをコピーします。 バージョンの値を 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 仕様の初期リリース。