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

備考

プレビュー

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

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

YAML の概要

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

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

一般的な表記

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

YAML 定義の式でスペースまたは特殊文字を含む列名を参照する場合は、次の点を考慮してください。

バッククォートエスケープ: 列名はバッククォート (') で囲み、適切に参照されるようにします。たとえば、名前にスペースが含まれている列を参照するには、 column nameを使用します。
二重引用符で囲まれたバッククォートエスケープ: 式がバッククォートでエスケープされた列名で始まり、YAML の文字列の一部である必要がある場合は、YAML に準拠するために式全体を二重引用符で囲みます。たとえば、スペースを含む列名を使用すると、式全体が "`column name`"のようになります。

ソース

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

結合

結合は、スタースキーマをモデル化するために使用され、ソースはファクトテーブルとして扱われ、 LEFT OUTER JOINを使用して複数のディメンションテーブルと結合できます。結合列は、 on 節または using 節を使用して指定できます。on句を使用すると、ブール式を使用してジョイン条件を定義できます。using句は、両方のテーブルで同じ名前のカラムを参照します。

結合は、多対 1 の関係に従う必要があります。次の例は、メトリクスビューの定義で結合を表現する方法を示しています。

source: catalog.schema.fact_table

joins:

  # The on clause supports a boolean expression
  - name: dimension_table_1
    source: catalog.schema.dimension_table_1
    on: source.dimension_table_1_fk = dimension_table_1.pk

  # The using clause supports an array of columns
  # found in both of the tables being joined.
  - name: dimension_table_2
    source: catalog.schema.dimension_table_2
    using:
      - dimension_table_2_key_a
      - dimension_table_2_key_b

dimensions:

  # Dimension referencing a join column from dimension_table_1 using dot notation
  - name: Dimension table 1 key
    expr: dimension_table_1.pk

measures:

  # Measure referencing a join column from dimension_table_1
  - name: Count of dimension table 1 keys
    expr: COUNT(dimension_table_1.pk)

注記

source 名前空間はメトリクスビューのソースから列を参照し、結合nameは結合されたテーブルの列を参照します。たとえば、ジョイン条件 source.dimension_table_1_fk = dimension_table_1.pkでは、 source はメトリクスビューのソーステーブル (fact_table) を参照し、 dimension_table_1 はジョインされたテーブルを参照します。参照は、 on 句に接頭部が指定されていない場合、デフォルトで結合テーブルになります。

寸法

ディメンションは、クエリ時に 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 の概要​

一般的な表記​

ソース​

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

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

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

フィルター​

結合​

寸法​

措置​

ウィンドウ対策​

コンポーザビリティ​