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 を正しく書式設定する方法について説明します。

列名を参照する

次の表は、含まれる文字に応じて列名を書式設定する方法を示しています。

場合	ソース列名（複数可）	参照式	注記
スペースは使用できません	`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"`'	列名の二重引用符をエスケープするには、バッククォートを使用します。 YAML 定義でその式を一重引用符で囲みます。

コロンを使用して式を組み合わせる

場合	Expression	注記
コロンを含む式	`expr: "CASE WHEN` 顧客層 `= 'Enterprise: Premium' THEN 1 ELSE 0 END"`	正しい解釈を行う場合は、式全体を二重引用符で囲みます

注

YAML は、引用符で囲まれていないコロンをキーと値の区切り記号として解釈します。常に、コロンを含む式を二重引用符で囲みます。

複数行インデント

場合	Expression	注記
複数行インデント	`expr: \\|` `CASE WHEN` `revenue > 100 THEN 'High'` `ELSE 'Low'` `END`	最初の行の下に式をインデントする

注

複数行式の|の後に、expr: ブロックスカラーを使用します。正しい解析を行うには、すべての行に expr キーを超えるスペースを少なくとも 2 つインデントする必要があります。

ディメンションを定義する

次の例では、ディメンションを定義する方法を示します。

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 コメント (#) が含まれている場合は、次の手順を使用します。

ノートブックまたは SQL エディターで ALTER VIEW コマンドを使用します。
元の YAML 定義を AS の後の $$..$$ セクションにコピーします。バージョンの値を 1.1 に変更します。
メトリックビューを保存します。

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

Warnung

ALTER VIEWを実行すると、YAML 定義のcomment フィールドに明示的に含まれていない限り、Unity カタログのコメントが削除されます。 Unity カタログに表示されているコメントを保持する場合は、オプション 2 を参照してください。

オプション 2: Unity カタログのコメントを保持する

注

次のガイダンスは、ノートブックまたは SQL エディターで ALTER VIEW コマンドを使用する場合にのみ適用されます。 YAML エディター UI を使用してメトリックビューをバージョン 1.1 にアップグレードすると、Unity カタログのコメントは自動的に保持されます。

YAML 定義内の適切な comment フィールドにすべての Unity カタログコメントをコピーします。バージョンの値を 1.1 に変更します。
メトリックビューを保存します。

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 仕様の初期リリース。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-24