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	任意。スター型スキーマとスノーフレーク型スキーマの結合。結合を参照してください。
`dimensions`	Array	条件付き。ディメンションの定義には、名前、式、およびオプションのセマンティックメタデータが含まれます。`measures`が指定されていない場合は必須です。寸法を参照してください。
`measures`	Array	条件付き。メジャーの定義には、名前、集計式、およびオプションのセマンティックメタデータが含まれます。`dimensions`が指定されていない場合は必須です。対策を参照してください。
`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

注記

SQLクエリをJOIN句を含むソースとして使用する場合は、基となるテーブルに主キーと外部キーの制約を設定し、最適なクエリパフォーマンスを得るために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スキーマモデリングのための、ネストされた結合定義のリスト。最小ランタイム要件については、メトリクスのビュー機能の可用性を参照してください。

スタースキーマ結合

スター型スキーマでは、 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

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)

注記

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

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

寸法

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

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

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

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

フィールド	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	必須。ウィンドウの順序を決定する寸法。（１）
`range`	String	必須。窓の範囲。サポートされている値については、 `range`を参照してください。
`semiadditive`	String	必須。集計方法。サポートされている値: `first`または`last` 。

（１） 参照される次元は決定論的であるべきである。rand() 、 uuid() 、 current_timestamp()などの非決定的な式は、予測不可能なウィンドウ順序を生成し、集計結果が不正確になる可能性があります。

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

currentウィンドウ順序付け値が現在の行の値と等しい行。
cumulativeウィンドウ順序付け値が現在の行の値以下であるすべての行。
trailing <value> <unit>: 現在の行から指定された時間単位だけ遡った行。例: trailing 7 day 。現在のユニットは含まれません。
leading <value> <unit>: 現在の行から指定された時間単位だけ先の行。例えばleading 3 month 。現在のユニットは含まれません。
allウィンドウ順序の値に関係なく、すべての行。

ウィンドウ測定例

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

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

フィールド	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`が指定されていない場合に必須です。

具体化の例

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

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

列名を参照する

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

スペースなし

ソース列: 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
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)
$$

警告

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

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

YAMLの概要​

ソース​

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

SQLクエリソース​

フィルター​

参加する​

スタースキーマ結合​

Snowflakeスキーマ結合​

寸法​

メジャー​

ウィンドウメジャー​

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

ウィンドウ測定例​

具現化​

具体化の例​

列名の参照​

書式設定例​

列名を参照する​

スペースなし​

スペースを含む列名​

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

引用符を含む列名​

コロンを含む表現​

複数行の式​

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

コメントの種類​

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

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

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