Databricks の Metric View は、Unity Catalog 上で KPI や業績指標を「一か所で定義・再利用」するための仕組みです。
BI ツールや Genie など複数の場所から同じ指標を参照できるため、「チームによって数字が違う…」という古典的な問題を根本から解決してくれます。
この記事では、Metric View を YAML で定義する際に使えるフィールドをひと通り整理しました。
公式ドキュメントを読み込むのが大変という方や、「あのオプションどこに書くんだっけ？」となったときの辞書代わりに活用してもらえれば幸いです。
Databricks Metric ViewのYAML定義とは
Metric View の YAML は以下のトップレベルキーで構成されます。
| フィールド | 必須/任意 | 概要 |
|---|---|---|
version | 必須 | YAML 仕様のバージョン（0.1 or 1.1） |
source | 必須 | データの取得元（テーブル名 or SQL クエリ） |
dimensions | 条件付き | 集計の軸になる列の定義。measures がなければ必須 |
measures | 条件付き | 集計値（KPI）の定義。dimensions がなければ必須 |
comment | 任意 | この Metric View 全体の説明メモ |
filter | 任意 | 全クエリに自動で適用される絞り込み条件 |
joins | 任意 | 他テーブルとの結合定義（スター・スノーフレーク対応） |
materialization | 任意 | クエリ高速化のためのマテリアライズドビュー設定 |
dimensions と measures はどちらか一方があれば OK ですが、実運用ではほぼ両方書くことになります。
以降のセクションで、各フィールドの使い方を順番に解説します。
sourceの書き方：データの取得元を指定する
テーブル・ビュー・マテリアライズドビュー・ストリーミングテーブル・外部テーブル・システムテーブル・別の Metric View など、Unity Catalog 上で SELECT が使えるオブジェクトならほぼ何でも指定できます。
テーブルを指定する場合は catalog.schema.table の形式で書きます。
別の Metric View を source にすることで、指標の「組み合わせ」も作れます（コンポーザビリティ）。
# パターン①：テーブルをそのまま指定
source: my_catalog.sales.transactions
# パターン②：SQL クエリを直接記述（JOIN も可能）
source: |
SELECT *
FROM my_catalog.sales.transactions t
LEFT JOIN my_catalog.master.customers c
ON t.customer_id = c.id
# パターン③：別の Metric View を指定（コンポーザビリティ）
source: my_catalog.my_schema.base_metric_view
dimensionsの書き方：集計の「軸」を定義する
ディメンションは GROUP BY や WHERE で使う列のことです。
単純な列参照だけでなく、CASE WHEN や DATE_TRUNC などの SQL 式も書けます。
| フィールド | 必須/任意 | 概要 |
|---|---|---|
name | 必須 | YAML 内部での識別子。materialization からもここで付けた名前で参照する |
expr | 必須 | 実際のデータを取得する SQL 式 |
comment | 任意 | Unity Catalog に保存されるメモ。管理者向けの説明に使う |
display_name | 任意 | Genie や BI ツール上に表示される名前（日本語・スペース可）。仕様 v1.1 が必要 |
format | 任意 | 値の表示形式（日付フォーマット、通貨など）。仕様 v1.1 が必要 |
synonyms | 任意 | Genie が自然言語で質問を理解するための別名リスト（最大 10 個）。仕様 v1.1 が必要 |
dimensions:
- name: purchased_at
expr: purchased_at
comment: '購入日時（タイムスタンプ型）'
display_name: '購入日'
synonyms: ['買った日', '注文日']
- name: payment_method
expr: |
CASE
WHEN payment_type = 'CREDIT' THEN 'クレジットカード'
WHEN payment_type = 'CASH' THEN '現金'
ELSE 'その他'
END
display_name: '支払い方法'
synonyms: ['決済方法', '支払方法']
name は内部識別子なので英数字・アンダースコア推奨です。
display_name は人が目にする表示名なので日本語や空白も使えます。
synonyms に登録しておくと、「決済方法を教えて」「支払方法は？」といった質問でも Genie が正しく参照してくれます。
measuresの書き方：業績指標（KPI）を定義する
メジャーは SUM・COUNT・AVG などの集計関数を必ず含む式です。
クエリから使うときは MEASURE() 関数でラップします。
| フィールド | 必須/任意 | 概要 |
|---|---|---|
name | 必須 | 内部識別子 |
expr | 必須 | 集計関数を含む SQL 式。SUM や COUNT などの集計関数を必ず使うこと |
comment | 任意 | Unity Catalog に保存されるメモ |
display_name | 任意 | 表示名。仕様 v1.1 が必要 |
format | 任意 | 値の表示形式。仕様 v1.1 が必要 |
synonyms | 任意 | 「売上高は？」「総売上を教えて」といった質問でも Genie が正しく参照できるようにするための別名リスト（最大 10 個）。仕様 v1.1 が必要 |
window | 任意 | 移動集計・累積集計を定義する（Experimental） |
measures:
- name: total_sales
expr: SUM(amount)
comment: '税込みの売上合計金額'
display_name: '売上合計'
synonyms: ['売上高', '総売上', '売り上げ']
format:
type: currency
currency_code: JPY
- name: online_sales
expr: SUM(amount) FILTER (WHERE channel = 'ONLINE')
display_name: 'オンライン売上'
display_name と format の使い分け
display_name→ 列の「名前」をどう表示するかformat→ 値の「見た目」をどう整えるか
上の例でいうと、画面上には 売上合計（display_name） という列見出しの下に ¥1,234,567（format） という値が表示されるイメージです。
windowで移動集計・累積集計を定義する方法
measures:
- name: rolling_7day_sales
expr: SUM(amount)
display_name: '直近7日間の売上合計'
window:
- order: purchased_at # どのディメンションを基準に並べるか
range: trailing 7 day # 集計範囲
semiadditive: last
range に指定できる値は current・cumulative・trailing N unit・leading N unit・all の 5 種類です。
週次ローリング集計や累計値が必要な場面で活躍します。
なお、この機能は現在 Experimental ステータスのため、本番利用の際は動作確認を十分に行うことをおすすめします。
commentの書き方：Metric View の説明を残す
任意項目ですが、Unity Catalog 上に表示されるメモとして機能します。
後から見たときに「このビューは何のためにあるのか」がすぐわかるよう、一言でも書いておくと運用が楽になります。
comment: '店舗別・チャネル別の売上集計ビュー。月次レポートおよび Genie からの参照を想定。'
filterの書き方：全クエリに共通の絞り込みをかける
filter を設定すると、この Metric View を参照するすべてのクエリに自動で WHERE 条件が付きます。
「このビューは直近1年分だけ使う」「テスト注文は除外したい」といった共通ルールを一か所に集約できます。
# 単一条件
filter: purchased_at > '2024-01-01'
# AND で複数条件を組み合わせる
filter: purchased_at > '2024-01-01' AND channel = 'ONLINE'
SQL の WHERE 句と同じ記法がそのまま使えます。
クエリ実行時に追加で絞り込むことは引き続き可能なので、「Metric View 側で大枠を固定し、クエリ側で細かく絞る」という使い方が自然です。
joinsの書き方：複数テーブルを組み合わせる
単一テーブルだけでなく、スタースキーマやスノーフレークスキーマ構成にも対応しています。
| フィールド | 必須/任意 | 概要 |
|---|---|---|
name | 必須 | 結合テーブルの別名 |
source | 必須 | 結合するテーブルを catalog.schema.table の形式で指定する |
on | 条件付き | 結合条件を SQL の条件式で記述。using がなければ必須 |
using | 条件付き | 両テーブルに同名の列がある場合に使える省略記法。on がなければ必須 |
joins | 任意 | ネストした結合（スノーフレーク構造に使う） |
version: 1.1
source: my_catalog.sales.transactions # ファクトテーブル（売上明細）
joins:
- name: stores
source: my_catalog.master.stores
on: source.store_id = stores.id
- name: products
source: my_catalog.master.products
on: source.product_id = products.id
dimensions:
- name: store_region
expr: stores.region # 別名.列名 で参照
- name: product_category
expr: products.category
on 句では source.列名 でファクトテーブル側を、別名.列名 で結合テーブル側を区別します。
スノーフレーク構造にしたい場合は joins の中にさらに joins をネストして書くことができます。
materializationの書き方：クエリを事前計算で高速化する
デフォルトでは Metric View は普通のビューと同じく、参照のたびにクエリが走ります。
materialization を設定すると、よく使う集計をマテリアライズドビューとして事前計算・保存しておき、クエリを高速化できます。
トップレベルの設定項目
| フィールド | 必須/任意 | 概要 |
|---|---|---|
schedule | 必須 | 再計算の頻度（例：every 6 hours、every 1 day） |
mode | 必須 | 現時点では relaxed 固定。多少古くてもキャッシュを使う動作 |
materialized_views | 必須 | 事前計算するビューのリスト |
materialized_views の各設定項目
| フィールド | 必須/任意 | 概要 |
|---|---|---|
name | 必須 | このマテリアライズドビューの識別名 |
type | 必須 | aggregated（集計済み）か unaggregated（元データのまま）か |
dimensions | 条件付き | 事前計算する dimension の name を列挙。aggregated で measures 未指定なら必須 |
measures | 条件付き | 事前計算する measure の name を列挙。aggregated で dimensions 未指定なら必須 |
materialization:
schedule: every 1 day
mode: relaxed
materialized_views:
- name: raw_cache
type: unaggregated # 元データを丸ごとキャッシュ
- name: daily_by_region
type: aggregated # 日別×地域 の集計を事前計算
dimensions:
- purchased_at
- store_region
measures:
- total_sales
- online_sales
unaggregated はベースラインとして元データをキャッシュするイメージです。
aggregated はよく使う集計粒度を指定して計算結果を保存するイメージです。
両方を組み合わせて定義することもできます。
Metric View YAMLのバージョンの違いについて
現在は v0.1 と v1.1 の 2 つが存在します。
- v0.1：初期リリース版。
source・dimensions・measures・joinsなど基本機能が使える - v1.1：
display_name・format・synonyms・commentなどの機能が追加。Genie と連携して自然言語対応を強化したい場合はこちら
特に Genie で自然言語の質問に的確に答えさせたい場合は、v1.1 に上げて display_name と synonyms をしっかり設定するのがおすすめです。
Databricks Metric ViewのYAML設定まとめ
Databricks Metric View の YAML 定義を整理すると、以下の 4 つの関心事に分けて考えられます。
- 何を集計するか（
source・joins） - どう切り分けるか（
dimensions） - 何を計算するか（
measures） - どう高速化するか（
materialization）
最初は source・dimensions・measures だけのシンプルな構成から始めて、慣れてきたら display_name・synonyms を加えて Genie との連携を磨いていくのが実践的な進め方です。
Metric View の概要や Genie との連携については、別記事でも解説しています。あわせてご参照ください。
