Metrix View YAML 構文リファレンス

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

各機能の最小ランタイムおよび YAML 仕様バージョン要件については、「メトリクスの機能の利用可能性の表示」を参照してください。

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

YAMLの概要

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

フィールド	Type	説明
`version`	String	必須。メトリクスビュー仕様のバージョン。 YAML仕様のバージョンを参照してください。
`comment`	String	任意。メトリクスビューの説明。
`source`	String	必須。メトリクスビューのソースデータ。メトリクスビューやSQLクエリを含む、テーブルのようなUnity Catalogアセットを使用できます。 See ソース.
`filter`	String	任意。すべてのクエリに適用されるSQLブール式。フィルターを参照してください。
`joins`	Array	任意。スター型スキーマとスノーフレーク型スキーマの結合。結合を参照してください。
`fields`	Array	条件です。名前、式、およびオプションのセマンティックメタデータを含むフィールド定義。`measures`が指定されていない場合は必須です。「フィールド」を参照してください。`dimensions`キーワードは、後方互換性の同義語として受け入れられています。
`measures`	Array	条件付き。メジャーの定義には、名前、集計式、およびオプションのセマンティックメタデータが含まれます。`fields`が指定されていない場合は必須です。対策を参照してください。
`materialization`	オブジェクト	任意。マテリアライズドビューを使用してクエリを高速化するための設定。更新スケジュールとマテリアライズドビューの定義が含まれます。具現化を参照してください。

ソース

source フィールドは、メトリクスビューのデータソースを指定します。サポートされているソースには、テーブル、ビュー、メトリクスビュー、およびSQLクエリが含まれます。構成可能性はメトリクスビュー全体に適用されます。メトリクスビューをソースとして用いる場合、そのフィールドとメジャーを新しいメトリクスビューで参照できます。構成可能性を参照してください。

テーブルのようなアセットソース

テーブルのようなアセットを参照するには、その3つの部分からなる名前を使用します。

YAML
source: catalog.schema.source_table

SQLクエリソース

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

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

注記

JOIN句を持つSQLクエリをソースとして使用する場合、基になるテーブルに主キー制約と外部キー制約を設定し、最適なクエリパフォーマンスを得るにはRELYオプションを使用します。詳細については、主キー、外部キー、および一意制約の宣言と主キーと一意制約を使用したクエリの最適化を参照してください。

フィルター

YAML 定義内のフィルターは、メトリクスビューを参照するすべてのクエリに適用されます。フィルタはSQLブール式として記述してください。

YAML
# 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'

結合

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

注記

結合テーブルにはMAP型の列を含めることはできません。MAP型の列から値を展開するには、「マップまたは配列からネストされた要素を展開する」を参照してください。

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

フィールド	Type	説明
`name`	String	必須。結合されたテーブルまたはSQLクエリのエイリアスフィールドまたはメジャーで結合テーブルから列を参照する際は、このエイリアスを使用してください。
`source`	String	必須。参加するテーブルの3部構成の名前。SQLクエリでも構いません。
`on`	String	条件付き。結合条件を定義するBoolean式。 `using`が指定されていない場合は必須です。
`using`	Array	条件付き。親テーブルと結合テーブルの両方に存在する列名の一覧。`on`が指定されていない場合は必須です。
`joins`	Array	任意。Snowflakeスキーマモデリングのための、ネストされた結合定義のリスト。最小ランタイム要件については、メトリクスのビュー機能の可用性を参照してください。
`rely`	Map	オプション。アナライザーが、より効率的なクエリプランを生成するために信頼できる結合に関する保証。「`rely`による結合の最適化」を参照してください。

スタースキーマ結合

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

結合列を指定するには、 ON句またはUSING句のいずれかを使用します。

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

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

YAML
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

fields:
  - 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)

注記

source名前空間はメトリクスビューのソースの列を参照しますが、結合のnameは結合されたテーブルの列を参照します。例えば、 source.l_orderkey = orders.o_orderkeyでは、 source lineitemを参照し、 ordersは結合されたテーブルを参照します。on句にプレフィックスが指定されていない場合、参照はデフォルトで結合テーブルになります。

Snowflakeスキーマ結合

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

スノーフレークスキーマを定義するには、 joins親結合定義の中にネストします。

YAML
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

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

結合の最適化 `rely`

クエリ・アナライザーがクエリの計画時に使用する関係に関する保証を宣言するには、JOIN句で「rely」フィールドを使用します。これらの保証により、エンジンはより効率的にクエリを計画し、スキャンされるデータ量を削減できます。特に、結合テーブルのフィールドがフィルターで参照される場合に。

relyマップは、以下のフィールドをサポートしています:

フィールド	Type	説明
`at_most_one_match`	Boolean	オプション。デフォルトは`false`です。`true` が、結合テーブルの最大1行がソースの各行に一致すると宣言する場合（ファンアウトしない多対一のリレーションシップ）。

警告

at_most_one_match: trueは、結合が多対一の場合にのみ設定してください。この関係はランタイムで検証されません。結合されたテーブルの複数の行が、単一のソース行と一致する場合、SUMやCOUNTなどのメジャーは、正しくない結果を返します。

次の例では、at_most_one_match を orders から customer への多対一結合で有効にします。顧客の属性でフィルターまたはグループ化するクエリは、最も効果的です。

YAML
version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    rely:
      at_most_one_match: true

fields:
  - name: Customer name
    expr: customer.c_name
  - name: Customer market segment
    expr: customer.c_mktsegment

measures:
  - name: Total revenue
    expr: SUM(o_totalprice)

フィールド

注記

fields dimensionsとは、メトリクスビュー定義において同等のキーワードです。fields は推奨される用語であり、このドキュメント全体で使用されています。dimensionsを使用している既存のメトリクスビューは引き続き機能し、新しい定義または更新された定義では両方のキーワードが受け入れられます。

フィールドは、クエリ時に SELECT、WHERE、および GROUP BY 句で使用されるメトリックビューの列です。各式はスカラー値を返す必要があります。フィールドは、ソースデータからの列またはメトリクスビューで以前に定義されたフィールドを参照できます。

フィールドは次のいずれかです：

地域、ステータス、部署などのカテゴリ列またはグループ化列です。
年齢、価格、数量などの未集計の数値列です。数値フィールドは、クエリ時にSUM または AVG などのSQL関数を使用して集計できます。

各フィールド定義には次のプロパティが含まれています。

属性	Type	説明
`name`	String	必須。フィールドの列のエイリアス。
`expr`	String	必須。ソースデータまたは以前に定義されたフィールドの列を参照できるSQL式。
`comment`	String	オプション。フィールドの説明。Unity Catalog およびドキュメントツールに表示されます。
`display_name`	String	任意。可視化ツールに表示されるラベル。文字数は255文字までです。YAML仕様1.1が必要です。「メトリクスビュー機能の可用性」を参照してください。
`format`	Map	任意。値の表示方法に関する書式指定。YAML仕様1.1が必要です。フォーマット仕様を参照してください。
`synonyms`	Array	オプション。AIとBIツールで分野を知るための代替名同義語は最大10個、それぞれ255文字以内にしてください。YAML仕様1.1が必要です。同義語をご覧ください。

例：

YAML
fields:
  # Basic field
  - name: order_date
    expr: o_orderdate
    comment: 'Date the order was placed'
    display_name: 'Order Date'

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

  # Field 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 関数を使用します。メジャーは、ソースデータのベース列、以前に定義されたフィールド、または以前に定義されたメジャーを参照できます。

各測定基準には、以下のフィールドが含まれます。

フィールド	Type	説明
`name`	String	必須。メジャーの別名。
`expr`	String	必須。1つ以上の集計関数を含むSQL式。
`comment`	String	任意。措置の説明。Unity Catalogおよびドキュメントツールに表示されます。
`display_name`	String	任意。可視化ツールに表示されるラベル。文字数は255文字までです。YAML仕様1.1が必要です。「メトリクスビュー機能の可用性」を参照してください。
`format`	Map	任意。値の表示方法に関する書式指定。YAML仕様1.1が必要です。フォーマット仕様を参照してください。
`synonyms`	Array	任意。指標を発見するためのAIおよびBIツールの別名。同義語は最大10個まで、それぞれ255文字以内です。YAML仕様1.1が必要です。「メトリクスビュー機能の可用性」を参照してください。
`window`	Array	任意。ウィンドウ処理、累積集計、または半加算集計のためのウィンドウ仕様。指定がない場合、この指標は標準的な集計値として機能します。窓の寸法を参照してください。

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

例：

YAML
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フィールドは、メジャーのウィンドウ集計、累積集計、または半加算集計を定義します。ウィンドウの測定方法と使用例に関する詳細な情報については、「ウィンドウの測定方法」を参照してください。

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

フィールド	Type	説明
`order`	String	必須。ウィンドウの順序を決定するフィールド。（1）
`range`	String	必須。窓の範囲。サポートされている値については、 `range`を参照してください。
`semiadditive`	String	必須。集計方法。サポートされている値: `first`または`last` 。
`offset`	String	オプション。Databricks Runtime 18.1 と YAML バージョン 1.1 以降が必要です。「`order`」フィールドに沿って、ウィンドウフレームを固定の間隔で前後に移動します。`<n> <period>`という形式の値です。ここで、`n`は符号付き整数（負の値は過去を、正の値は未来を指します）であり、`period`は`day`、`days`、`month`、`months`、`year`、または`years`のいずれかです。例：`-12 month`、`1 year`、`-3 days`、`7 day`。`order` フィールドは日付またはタイムスタンプ列である必要があります。`offset`は`range: all`に何の影響もありません。シフトされたフレームが利用可能なデータの範囲外にある場合、メジャーは`NULL`と評価されます。使用方法と動作例については、`offset`がウィンドウフレームをシフトする方法をご覧ください。

(1) 参照されるフィールドは確定的である必要があります。非決定的な式（例: rand()、uuid()、またはcurrent_timestamp()）は、予測できないウィンドウの順序を生成し、不正確な集計結果につながる可能性があります。

サポートされている値`range`

current：ウィンドウの順序付け値がアンカー行の値に等しい行。
cumulative：ウィンドウの順序付け値がアンカー行の値以下であるすべての行です。
trailing <value> <unit> [inclusive | exclusive]：アンカー行から指定された時間単位数だけ遡る行。例：trailing 7 day。オプションのinclusiveまたはexclusive修飾子には、Databricks Runtime 18.1およびYAMLバージョン1.1以降が必要であり、これにより、アンカー行がウィンドウに含まれるかどうかが制御されます。デフォルトはexclusiveです。「アンカー行を含めるか除外する」を参照してください。
leading <value> <unit> [inclusive | exclusive]アンカー行から、指定された時間単位数だけ先に進む行を含みます。たとえば leading 3 month の場合です。オプションのinclusiveまたはexclusive修飾子には、Databricks Runtime 18.1およびYAMLバージョン1.1以降が必要であり、これにより、アンカー行がウィンドウに含まれるかどうかが制御されます。デフォルトはexclusiveです。「アンカー行を含めるか除外する」を参照してください。
allウィンドウ順序の値に関係なく、すべての行。

ウィンドウ測定例

次の例では、過去7日間のユニーク顧客数を集計します。

YAML
version: 1.1
source: samples.tpch.orders

fields:
  - 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フィールドには、以下のトップレベルフィールドが含まれます。

フィールド	Type	説明
`schedule`	String	必須。スケジュールを更新します。マテリアライズドビューのスケジュール句と同じ構文を使用します。 `TRIGGER ON UPDATE`句はサポートされていません。
`mode`	String	必須。`relaxed`に設定する必要があります。
`materialized_views`	Array	必須。具体化するマテリアライズドビューのリスト。各項目には、下記に記載する項目への入力が必要です。

materialized_viewsの各エントリには、以下のフィールドが含まれます。

フィールド	Type	説明
`name`	String	必須。具現化現象の名前。
`type`	String	必須。物質化の種類。サポートされている値: `aggregated` ( `dimensions` 、 `measures` 、またはその両方が必要) または`unaggregated` 。
`dimensions`	Array	条件です。マテリアライズするフィールド名のリスト。`type`が`aggregated`の場合で、かつ`measures`が指定されていない場合は必須です。
`measures`	Array	条件付き。具体化するメジャー名のリスト。`type`が`aggregated`であり、かつ`dimensions`が指定されていない場合に必須です。

注記

マテリアライズブロックでは、fields:ではなくdimensions:キーワードを使用します。トップレベルの定義でfields:を使用している場合でも、マテリアライズするフィールドをリストする際はdimensions:を使用してください。

具体化の例

次の例では、複数の実体化を含むメトリクスビューを定義します。

YAML
version: 1.1
source: samples.tpch.orders

fields:
  - 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の正しいフォーマット方法を学んでください。

列名を参照する

以下の例は、列参照に含まれる文字に応じて列参照の書式を設定する方法を示しています。

スペースなし

ソース列: revenue

YAML
expr: "revenue"
expr: 'revenue'
expr: revenue

列名には、二重引用符、一重引用符、または引用符なしのいずれかを使用してください。

スペースを含む列名

ソース列: `First Name`

YAML
expr: '`First Name`'

バッククォートを使用してスペースをエスケープします。式全体を二重引用符で囲んでください。

SQL式でスペースを含む列名

ソース列: `First Name` 、 `Last Name`

YAML
expr: CONCAT(`First Name`, ' ', `Last Name`)

式がバッククォートで始まっていない場合は、二重引用符は不要です。

引用符を含む列名

ソース列: "name"

YAML
expr: '`"name"`'

列名に含まれる二重引用符をエスケープするには、バッククォートを使用してください。式をシングルクォーテーションで囲んでください。

コロンを含む表現

YAML
expr: "CASE WHEN `Customer Tier` = 'Enterprise: Premium' THEN 1 ELSE 0 END"

注記

YAMLでは、引用符で囲まれていないコロンはキーと値の区切り文字として解釈されます。コロンを含む式は必ず二重引用符で囲んでください。

複数行の式

YAML
expr: |
  CASE WHEN
    revenue > 100 THEN 'High'
  ELSE 'Low'
  END

注記

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

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

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

コメントの種類

YAMLコメント（ # ） ：YAMLファイルに直接記述されたインラインまたは単一行のコメント。
Unity Catalogコメント : メトリクスビューまたはその列のUnity Catalogに保存されているコメント。これらはYAMLコメントとは別物です。

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

メトリクスビューでのコメントの処理方法に一致するアップグレードパスを選択してください。

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

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

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

SQL
ALTER VIEW metric_view_name AS
$$
# The notebook preserves inline comments
version: 1.1
source: samples.tpch.orders
fields:
- 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)
$$

警告

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

オプション2： Unity Catalogコメントを保持する

注記

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

Unity Catalogのコメントをすべてコピーして、YAML定義内の適切なcommentフィールドに貼り付けてください。versionの値を1.1に変更してください。
メトリクスビューを保存します。

SQL
ALTER VIEW metric_view_name AS
$$
version: 1.1
source: samples.tpch.orders
comment: "Metric view of order (Updated comment)"

fields:
- 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 仕様のバージョン履歴と各機能の最小ランタイム要件については、メトリクスの機能の利用可能性の表示を参照してください。

YAMLの概要​

ソース​

テーブルのようなアセットソース​

SQLクエリソース​

フィルター​

結合​

スタースキーマ結合​

Snowflakeスキーマ結合​

結合の最適化 rely​

フィールド​

メジャー​

ウィンドウメジャー​

サポートされている値range​

ウィンドウ測定例​

具現化​

具体化の例​

列名の参照​

書式設定例​

列名を参照する​

スペースなし​

スペースを含む列名​

SQL式でスペースを含む列名​

引用符を含む列名​

コロンを含む表現​

複数行の式​

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

コメントの種類​

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

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

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