メトリック ビューの YAML 構文リファレンス

このページでは、メトリック ビューの完全な YAML 文法について説明します。 メトリック ビューの定義は、標準の YAML 表記構文に従います。

各機能の最小ランタイムおよび YAML 仕様バージョンの要件については、 メトリック ビュー機能の可用性に関するページを参照してください。

YAML 仕様の詳細については、 YAML 仕様 1.2.2 のドキュメントを参照してください。

YAML の概要

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

情報源

source フィールドは、メトリック ビューのデータ ソースを指定します。 テーブル、ビュー、メトリック ビューなどのテーブルに似た資産、または SQL クエリをソースとして使用できます。 構成可能性は、メトリック ビュー全体に適用されます。 メトリック ビューをソースとして使用する場合は、新しいメトリック ビューでそのディメンションとメジャーを参照できます。 コンポーザビリティを参照してください。

テーブルに似た資産ソース

3 部構成の名前を使用して、テーブルのような資産を参照します。

source: catalog.schema.source_table

SQL クエリ ソース

SQL クエリを使用するには、クエリ テキストを YAML に直接記述します。

source: SELECT * FROM samples.tpch.orders o
  LEFT JOIN samples.tpch.customer c
  ON o.o_custkey = c.c_custkey

フィルター

YAML 定義のフィルターは、メトリック ビューを参照するすべてのクエリに適用されます。 フィルターを SQL ブール式として書き込みます。

# Single condition filter
filter: o_orderdate > '2024-01-01'

# Multiple conditions with AND
filter: o_orderdate > '2024-01-01' AND o_orderstatus = 'F'

# Multiple conditions with OR
filter: o_orderpriority = '1-URGENT' OR o_orderpriority = '2-HIGH'

# Complex filter with IN clause
filter: o_orderstatus IN ('F', 'P') AND o_orderdate >= '2024-01-01'

# Filter with NOT
filter: o_orderstatus != 'O' AND o_totalprice > 1000.00

# Filter with LIKE pattern matching
filter: o_comment LIKE '%express%' AND o_orderdate > '2024-01-01'

Joins

メトリック ビューでの結合では、ファクト テーブルからディメンション テーブル (スター スキーマ) への直接結合と、正規化されたディメンション テーブル (スノーフレーク スキーマ) 間のマルチホップ結合の両方がサポートされます。 SELECT ステートメントを使用して SQL クエリに結合することもできます。 ソースとして SQL クエリを使用するを参照してください。

各結合定義には、次のフィールドが含まれています。

スター スキーマ結合

スター スキーマでは、 source はファクト テーブルであり、 LEFT OUTER JOINを使用して 1 つ以上のディメンション テーブルと結合します。 メトリック ビューは、選択した列に基づいて、特定のクエリに必要なファクト テーブルとディメンション テーブルを結合します。

ON句または USING 句を使用して結合列を指定します。

• ON 句: ブール式を使用して結合条件を定義します。
• USING 句: 親テーブルと結合テーブルの両方で同じ名前の列を一覧表示します。

結合は「多対一の関係」に従う必要があります。 多対多の場合、結合されたディメンション テーブルから最初に一致する行が選択されます。

version: 1.1
source: samples.tpch.lineitem

joins:
  - name: orders
    source: samples.tpch.orders
    on: source.l_orderkey = orders.o_orderkey

  - name: part
    source: samples.tpch.part
    on: source.l_partkey = part.p_partkey

dimensions:
  - name: Order Status
    expr: orders.o_orderstatus

  - name: Part Name
    expr: part.p_name

measures:
  - name: Total Revenue
    expr: SUM(l_extendedprice * (1 - l_discount))

  - name: Line Item Count
    expr: COUNT(1)

Snowflake スキーマ結合

スノーフレーク スキーマは、ディメンション テーブルを正規化してサブディメンションに接続することで、スター スキーマを拡張します。 これにより、複数レベルの結合構造が作成されます。 最小ランタイム要件については、 メトリック ビュー機能の可用性 に関する記事を参照してください。

スノーフレーク スキーマを定義するには、親結合定義内に joins を入れ子にします。

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    'on': o_custkey = c_custkey
    joins:
      - name: nation
        source: samples.tpch.nation
        'on': c_nationkey = n_nationkey

dimensions:
  - name: customer_nation
    expr: customer.nation.n_name

ディメンション

ディメンションは、クエリ時に SELECT句、 WHERE句、および GROUP BY 句で使用される列です。 各式はスカラー値を返さなければなりません。 ディメンションは、メトリック ビューでソース データまたは以前に定義されたディメンションから列を参照できます。

各ディメンション定義には、次のフィールドが含まれています。

例：

dimensions:
  # Basic dimension
  - name: order_date
    expr: o_orderdate
    comment: 'Date the order was placed'
    display_name: 'Order Date'

  # Dimension with SQL expression
  - name: order_month
    expr: DATE_TRUNC('MONTH', o_orderdate)
    display_name: 'Order Month'

  # Dimension with synonyms
  - name: order_status
    expr: CASE
      WHEN o_orderstatus = 'O' THEN 'Open'
      WHEN o_orderstatus = 'P' THEN 'Processing'
      WHEN o_orderstatus = 'F' THEN 'Fulfilled'
      END
    display_name: 'Order Status'
    synonyms: ['status', 'fulfillment status']

対策

メジャーは、事前に決定された集計レベルなしで結果を生成する式です。 集計関数を使用して表現する必要があります。 クエリでメジャーを参照するには、 MEASURE 関数を使用します。 メジャーは、ソース データ、以前に定義されたディメンション、または以前に定義されたメジャーの基本フィールドを参照できます。

各メジャー定義には、次のフィールドが含まれています。

集計関数の一覧については、集計関数を参照してください。

例：

measures:
  # Simple count measure
  - name: order_count
    expr: COUNT(1)
    display_name: 'Order Count'

  # Sum aggregation measure with synonyms
  - name: total_revenue
    expr: SUM(o_totalprice)
    comment: 'Gross revenue from all orders'
    display_name: 'Total Revenue'
    synonyms: ['revenue', 'total sales']

  # Distinct count measure
  - name: unique_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: 'Unique Customers'

  # Calculated measure combining multiple aggregations
  - name: avg_order_value
    expr: SUM(o_totalprice) / COUNT(DISTINCT o_orderkey)
    display_name: 'Avg Order Value'
    synonyms: ['AOV', 'average order']

  # Filtered measure with WHERE condition
  - name: open_order_revenue
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'O')
    display_name: 'Open Order Revenue'
    synonyms: ['backlog', 'outstanding revenue']

ウィンドウ メジャー

window フィールドは、メジャーのウィンドウ集計、累積集計、または準加法集計を定義します。 ウィンドウ メジャーとユース ケースの詳細については、「 ウィンドウ メジャー」を参照してください。

各ウィンドウの仕様には、次のフィールドが含まれています。

ウィンドウ メジャーの例

次の例では、一意の顧客のローリング 7 日間のカウントを計算します。

version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate

measures:
  - name: rolling_7day_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: '7-Day Rolling Customers'
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

具体化

materialization フィールドは、具体化されたビューを使用して自動クエリ アクセラレーションを構成します。 具体化のしくみ、要件、ベスト プラクティスの詳細については、 メトリック ビューの具体化を参照してください。

materialization フィールドには、次の最上位レベルのフィールドが含まれています。

materialized_viewsの各エントリには、次のフィールドがあります。

具体化の例

次の例では、複数の具体化を使用してメトリック ビューを定義します。

version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate
  - name: order_status
    expr: o_orderstatus

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
  - name: order_count
    expr: COUNT(1)

materialization:
  schedule: every 6 hours
  mode: relaxed
  materialized_views:
    - name: baseline
      type: unaggregated

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - order_status
      measures:
        - total_revenue
        - order_count

列名の参照

YAML 式でスペースまたは特殊文字を含む列名を参照する場合は、列名をバックティックで囲んでスペースまたは文字をエスケープします。 式がバックティックで始まり、YAML 値として直接使用される場合は、式全体を二重引用符で囲みます。 有効なYAMLの値はバックティックで始めることができません。

書式設定の例

次の例を使用して、一般的なシナリオで YAML を正しく書式設定する方法について説明します。

列名を参照する

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

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

複数行インデント

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

コメントは以前のバージョンとは異なる方法で処理されるため、メトリック ビューを YAML 仕様バージョン 1.1 にアップグレードするには注意が必要です。

コメントの種類

• YAML コメント (#): # 記号を使用して YAML ファイルに直接書き込まれたインラインまたは 1 行のコメント。
• Unity カタログのコメント: メトリック ビューまたはその列 (ディメンションとメジャー) の Unity カタログに格納されているコメント。 これらは YAML コメントとは別です。

アップグレードに関する考慮事項

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

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

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

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

ALTER VIEW metric_view_name AS
$$
# The notebook preserves inline comments
version: 1.1
source: samples.tpch.orders
dimensions:
- name: order_date # The notebook preserves inline comments
  expr: o_orderdate
measures:
# The notebook preserves commented out definitions
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

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

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

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

YAML 仕様のバージョン履歴と各機能の最小ランタイム要件については、 メトリック ビューの機能の可用性に関するページを参照してください。