databricks-metric-views

Unity Catalog メトリックビュー

柔軟なクエリに対応できるよう、メジャーの定義とディメンションのグループ化を分離し、再利用可能で統制されたビジネスメトリックを YAML で定義します。

使用する場面

次のような場合にこのスキルを使用します。

• 標準化されたビジネスメトリック（収益、注文数、コンバージョン率）を定義する
• ダッシュボード、Genie、SQL クエリで共有する KPI レイヤーを構築する
• 複雑な集計（比率、個別カウント、フィルター付きメジャー）を含むメトリックを作成する
• ウィンドウメジャー（移動平均、累計、期間比較、YTD）を定義する
• メトリック定義に結合を含む スター型またはスノーフレーク型スキーマをモデル化する
• 事前計算済みのメトリック集計を行うために マテリアライズを有効にする

まず確認：これは本当にメトリックビューにできますか？（判定ゲート）

作成を始める前に、メジャーがクエリ時に再集計されることを確認してください。 加法的な SUM／COUNT、セルごとに再計算される COUNT(DISTINCT)、MEASURE() を使った比率（最後に除算）、およびサポート対象の ウィンドウメジャー（後方移動／累積／期間比較 — パターン 8）は、いずれも正しく再集計されるため、メトリックビューのメジャーとして有効です。このリストはすべてを網羅しているわけではありません。以下の判定ゲートは、対象外となる形状を見極めるものです。次のいずれかに該当する場合は、メトリックビューではありません。ビューや事前集計済みのヘルパービューに無理に押し込まず、代わりに 統制された Unity Catalog SQL 関数（databricks-dbsql で構築）を作成し、信頼できる登録済み SQL 関数として Genie に公開します（Design Priorities のサーフェス #11）。

• クエリ対象の粒度で加法的でない — ディメンション間で合計すると二重計上になります。個別エンティティのカウントは典型的な落とし穴です。ある属性値の下に現れるエンティティは 2 つではなく 1 つなので、セルごとの個別カウントを任意の複数属性のクロス集計で合計してはいけません。
• エンティティごとに計算してから集計するが、エンティティごとの処理が合計／カウント／合計値の比率ではない — たとえば、2 つの期間にわたるエンティティごとの最小値／最大値や、エンティティごとの個別カウントに対するしきい値です。
• 選択に依存する — ユーザーのフィルターに応じて結果の配分が変わります（セルごとに変化する「その他すべて」バケットなど）。
• 反復的である — 収束するまで繰り返します（パネルの再重み付けなど）。
• 単一のメジャーではなくテーブルの組み合わせを返す — たとえば、行ごとの純額を含む送信元×送信先のマトリックスです。

メジャーの大部分をメトリックビューにし、一部だけを関数に切り出すこともできます（浸透率 = 加法的な購入者数 ÷ ベース。最後に除算します。ただし、短期間の補正や、任意の複数属性クロス／エンティティごとのしきい値は関数に含めます）。扱いにくい処理をベースビュー／ヘルパービューに事前計算する方法が有効なのは、定義が固定の場合に限られます。つまり、すべての切り口に対して一度だけ確定するパフォーマンス上の選択です。Genie でユーザーの実行時選択（任意のクロス集計、パラメーター、変動する分母）に応じてメジャーを変える必要がある場合、オンザフライで計算するため事前計算できません。必要なのは事前集計済みビューではなく、パラメーター化された統制 SQL 関数です。規則の全文と 2 つの具体例（浸透率、ブランド切り替えによる獲得と損失）については、metric-view-advisor.md §メトリックビューが適切なツールではない場合を参照してください。外部手法を再現する関数への Genie のルーティングをベンチマークする前に、参照値に対する小数点以下 N 桁の 一致を検証してください。詳しくは databricks-genie-agents スキルを参照してください。

前提条件

• Databricks Runtime 17.2 以降（YAML バージョン 1.1 の場合）、17.3 以降（セマンティックメタデータ（synonyms／display_name／format）の場合）
• CAN USE 権限を持つ SQL ウェアハウス
• ソーステーブルに対する SELECT、ターゲットスキーマにおける CREATE TABLE と USE SCHEMA

Metric View のライフサイクル

タスク	リファレンス	読み込むタイミング
作成	metric-view-advisor.md	作成タスク全般 — アドバイザーがワークフロー全体（スキーマのプロファイリング、ソースの分析、提案、デプロイ）を処理します。YAML の仕様とパターンのリファレンスとして、create-patterns.md もあわせて読み込みます。
YAML 仕様／パターン	create-patterns.md	パターン 1～12、YAML フィールドの完全なリファレンス、書式設定上の注意点、デプロイエラー、クイックリファレンス。アドバイザーとあわせて使用します。パターンの検索に直接読み込むこともできます。
クエリ	query-patterns.md	メトリックビューに対する SQL の作成 — MEASURE() の基本、フィルター、結合のロールアップ、ウィンドウメジャー、ルール 1～3。
Genie との統合	metric-view-advisor.md §Genie Design Rules	単一ファクトソースのルール、ベースビュー、ドメインの整理、命名。エージェントのメタデータフィールド（comment、synonyms、display_name、format）については、create-patterns.md §YAML Field Reference を参照してください。

一般的な流れ：アドバイザー → 作成 → クエリ／検証 → Genie との統合（Genie Agent に追加する場合）。

Declarative Automation Bundles によるソース管理下でのデプロイ

メトリックビューをソース管理するには、その完全な SQL 定義をコミットし、バンドル管理の SQL ジョブを通じて実行します。DAB にはネイティブのメトリックビューリソースはありませんが、バンドル管理の SQL ジョブでコミット済みの定義を適用できます。

# databricks.yml
bundle:
  name: orders_metrics

variables:
  catalog: { default: main }
  schema:  { default: default }
  warehouse_id: { default: "" }

resources:
  jobs:
    deploy_orders_metrics:
      name: deploy_orders_metrics
      parameters:
        - name: catalog
          default: ${var.catalog}
        - name: schema
          default: ${var.schema}
      tasks:
        - task_key: create_metric_view
          sql_task:
            warehouse_id: ${var.warehouse_id}
            file:
              path: ../src/orders_metrics.metric_view.sql

デプロイして実行します。

databricks bundle deploy --target <TARGET> --profile <PROFILE>
databricks bundle run deploy_orders_metrics --target <TARGET> --profile <PROFILE>

公式のメトリックビューバンドルの例を参照してください。

関連スキル

• databricks-genie-agents — ここで作成したメトリックビューを使用する Genie Agent の作成、管理、検証を行います。Genie 向けのメトリックビュー設計ルールはアドバイザー §Genie Design Rulesに、クエリルールはquery-patterns.mdに記載されています。
• databricks-aibi-dashboards — メトリックビューを基盤に AI/BI ダッシュボードを構築します。
• databricks-data-discovery — メトリックビューの作成前にデータを調査し、ワークスペース全体を対象に質問への回答を得ます。
• databricks-dabs — バンドル管理のジョブを通じて、メトリックビューの SQL 定義をソース管理し、デプロイします。

リソース

• メトリックビューのドキュメント
• YAML 構文リファレンス
• 結合
• ウィンドウメジャー
• マテリアライゼーション
• MEASURE() 関数