メインコンテンツまでスキップ

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 定義ではその式を一重引用符で囲みます。

コロンを使った表現を使う​

場合

式

注

コロンを使った表現

expr: "CASE WHEN顧客層= 'Enterprise: Premium' THEN 1 ELSE 0 END"

正しく解釈するために、式全体を二重引用符で囲みます。

注記

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

複数行のインデント​

場合

式

注

複数行のインデント

注記

複数行の式の場合は、 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の列名マッピング​

column_listでCREATE VIEWを使用してメトリクス ビューを作成すると、システムは YAML 定義の列 (メジャーとディメンション) を名前ではなく位置でcolumn_listにマッピングします。

これは、次の例に示すように、標準の SQL 動作に従います。

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 Catalogコメント : メトリクス ビューまたはその列 (ディメンションとメジャー) のUnity Catalogに保存されているコメント。 これらは YAML コメントとは別です。

アップグレードの考慮事項​

メトリクス ビューでのコメントの処理方法に一致するアップグレード パスを選択してください。 次のオプションでは、利用可能なアプローチについて説明し、例を示します。

オプション 1: ノートブックまたは SQL エディターを使用して YAML コメントを保存する​

メトリクス ビューに保持したい YAML コメント (#) が含まれている場合は、次のステップを使用します。

  1. ノートブックまたは SQL エディターで ALTER VIEW コマンドを使用します。

  2. 元の YAML 定義を AS の 後の $$..$$ セクションにコピーします。バージョンの値を 1.1 に変更します。

  3. メトリクス ビューを保存します。

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

警告

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

オプション2: Unity Catalogコメントを保存する​

注記

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

  1. すべてのUnity Catalogコメントを YAML 定義内の適切なcommentフィールドにコピーします。 バージョンの値を 1.1 に変更します。

  2. メトリクス ビューを保存します。

SQL
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​

バージョン0.1​

  • メトリクス ビュー YAML 仕様の初期リリース。
に最終更新