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

備考

プレビュー

この機能はパブリックプレビュー段階です。

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

YAML の概要

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

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

YAMLの構文とフォーマット

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

列名の参照

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 式。

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

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

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

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 の概要​

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

列名の参照​

書式設定の例​

列名を参照する​

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

複数行のインデント​

ソース​

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

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

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

フィルター​

結合​

寸法​

措置​

ウィンドウ対策​

コンポーザビリティ​

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