メトリクス view YAML リファレンス

このページでは、メトリクスビューを定義するために使用されるYAMLの各コンポーネントについて説明します。

YAML の概要

メトリクスビューの YAML 定義には、次のトップレベルフィールドが含まれます。

version : デフォルトは1.1です。これは、メトリクスビュー仕様のバージョンです。バージョン仕様の変更ログを参照してください。
source: メトリクスビューのソースデータ。これは、テーブルのようなアセットまたは SQL クエリにすることができます。
joins: 随意。スタースキーマとスノーフレークスキーマの結合がサポートされています。
filter: 随意。すべてのクエリに適用される SQL ブール式。 WHERE 句に相当します。
comment : オプション。メトリクスビューの説明。
dimensions: ディメンション定義の配列 (ディメンション名と式を含む)。
measures: 集計式カラムの配列。

YAMLの構文とフォーマット

メトリクスビューの定義は、標準の YAML 表記構文に従います。 YAML 仕様の詳細については、YAML 仕様 1.2.2 のドキュメントを参照してください。

列名の参照

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 は、引用符で囲まれていないコロンをキーと値の区切り文字として解釈します。コロンを含む式は、常に二重引用符で囲みます。

複数行のインデント

ケース	式	注
複数行のインデント

注記

複数行の式には、 > ブロックの after expr: スカラーを使用します。すべての行は、正しく解析するために、 expr キーより少なくとも 2 スペース先にインデントする必要があります。

ソース

テーブルのようなアセットまたは 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 句を使用するのと同じです。

結合

結合は、メトリクスビューのソースと、テーブル、ビュー、その他のメトリクスビューなどの他のソースとの間の関係を定義します。結合を使用して、ファクトテーブルからディメンションテーブルへの関係をモデル化し(スタースキーマ)、ディメンションからサブディメンションへのトラバースを行うことで、正規化されたディメンションテーブル(スノーフレークスキーマ)間でのマルチホップ結合が可能になります。別のメトリクスビューに結合すると、その寸法のみが下流のメトリクスビューで使用できます。

Snowflake 結合は、コンピュート 17.1 以降を使用している場合にのみサポート Databricks Runtime 。メトリクスビューでの結合の使用を参照してください。

寸法

ディメンションは、クエリ時に SELECT句、 WHERE句、 GROUP BY 句で使用されます。各式はスカラー値を返す必要があります。各ディメンションは、次の 2 つのコンポーネントで構成されています。

name: 列のエイリアス。
expr: ディメンションを定義するソース・データの SQL 式。

注記

バージョン 1.1 以降では、各ディメンションのセマンティックメタデータ (表示名、形式、同義語) も定義できます。詳細については、「メトリクスビューでのセマンティックメタデータの使用」を参照してください。

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

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集計関数を参照してください。

注記

バージョン 1.1 以降では、各メジャーのセマンティックメタデータ (表示名、形式、同義語) も定義できます。詳細については、「メトリクスビューでのセマンティックメタデータの使用」を参照してください。

次の例は、メジャーを定義する方法を示しています。

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)

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

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

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コメントは自動的に保存されます。

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

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

追加した ：
- セマンティックメタデータ機能のサポート。「メトリクスビューでのセマンティックメタデータの使用」を参照してください。
- メトリクスビュー、ディメンション、またはメジャーを記述するためのオプションの YAML commentフィールドのサポート。

バージョン0.1

メトリクスビュー YAML 仕様の初期リリース。

YAML の概要​

YAMLの構文とフォーマット​

列名の参照​

書式設定の例​

列名を参照する​

コロン付きの式を使用する​

複数行のインデント​

ソース​

テーブルをソースとして使用する​

SQL クエリをソースとして使用する​

メトリクスビューをソースとして使用する​

フィルター​

結合​

寸法​

措置​

ウィンドウ対策​

コンポーザビリティ​

YAMLを使用した CREATE VIEW での列名のマッピング​

YAMLを1.1にアップグレードする​

コメントの種類​

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

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

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

バージョン仕様の変更履歴​

バージョン1.1​

バージョン0.1​