databricks-aibi-dashboards について
Databricks AI/BI ダッシュボードの設計、検証、公開を支援するスキルです。ウィジェット選択、SQL の確認、フィルターや構成の計画に加え、カスタム Databricks App が適する場合も案内します。
主な機能
- 01標準または Vega-Lite のウィジェット選択
- 02スキーマ調査と SQL 検証
- 03データセット、フィルター、配置の計画
- 04ダッシュボードの作成、更新、公開
活用シーン
- 01KPI やトレンドのダッシュボード作成
- 02コホート維持率やスケジュールの可視化
- 03公開前のクエリ確認
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/databricks-aibi-dashboardsを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
agents/openai.yamlassets/databricks.svgreferences/1-widget-specifications.md2-advanced-widget-specifications.md3-filters.md4-examples.md5-troubleshooting.md6-custom-visualizations.md詳細
AI/BI ダッシュボードスキル
Databricks AI/BI ダッシュボード（旧 Lakeview ダッシュボード）を作成します。 ダッシュボードには通常、上部に KPI を配置し、ストーリーに基づいてグラフ（多くの場合、時系列）を表示して、「何かが起きている」ことが分かるようにします。 以下のガイドラインを厳守してください。
ウィジェットを選択する
デフォルトでは標準ウィジェットを使用します。必要なビジュアライゼーションを標準ウィジェットで表現できない場合は、Vega-Lite を使用してください。集計方法、カラーパレット、ツールチップ、参照線、またはスモールマルチプルの変更であれば、通常はカスタム仕様は必要ありません。
| 表示する内容 | 使用するもの |
|---|---|
| KPI、傾向、ランキング、分布、地理的な比較 | 標準のカウンター、折れ線／棒グラフ、ヒストグラム／箱ひげ図、またはマップのウィジェット |
| 2 軸目に利益率の折れ線を重ねた売上棒グラフ | 標準の combo |
| コホートと経過期間別のリテンション | カラースケール付きの標準の pivot |
| スケジュール上のタスク開始時刻と終了時刻 | 標準の gantt |
| 配送ルートまたは順序付き GPS トラック | 標準の path-map |
| 目標線、または地域ごとに繰り返される同一のグラフ | 標準のアノテーションまたはファセットを使用してください。ウィジェット仕様を参照してください |
| カテゴリごとに実績値の棒と目標マーカーを表示するブレットチャート | custom-vega-viz。ブレットチャートの作成例を参照してください |
| ローリング平均線を重ねて点として描画する生の観測値 | custom-vega-viz。レイヤー化した時系列の例を参照してください |
| 要望されたゲージ、レーダー、またはネストされた放射状／サンバーストレイアウト | custom-vega-viz。カスタムチャートのパターンを参照してください |
カスタムチャートでは、必要なマークと変換が Vega-Lite でサポートされていることを確認してください。Vega のすべての例やチャートタイプがサポートされるわけではありません。結合やビジネス計算はデータセットの SQL で行い、カスタム仕様は返されたデータの描画方法を制御します。
カスタムアプリが適している場合： 管理された AI/BI ダッシュボードは、ガバナンス対象のテーブルに対する読み取り専用の KPI、チャート、フィルターに適しています。一方、ユーザーが カスタムコードのインタラクティブアプリ（書き戻し／データ入力、ダッシュボードのグリッドを超える独自の UI や操作、埋め込み型または認証で制御されるワークフロー、あるいは主要な画面としての会話型 Genie／チャットアシスタント）を必要としている場合は、代わりに
databricks-appsスキルを使って Databricks App を構築してください（データ画面の UX 向けにdatabricks-app-designが組み込まれています）。「Ask Genie」スペースを この ダッシュボードにリンクする場合は、ここで対応します（以下の「Genie Space のリンク」を参照してください）。
クイックリファレンス
| タスク | コマンド |
|---|---|
| ウェアハウスの一覧表示 | databricks warehouses list |
| テーブルの一覧表示 | databricks experimental aitools tools query --warehouse WH "SHOW TABLES IN catalog.schema" |
| スキーマの取得 | databricks experimental aitools tools discover-schema catalog.schema.table1 catalog.schema.table2 |
| クエリのテスト | databricks experimental aitools tools query --warehouse WH "SELECT..." |
| ダッシュボードの作成 | databricks lakeview create --display-name "X" --warehouse-id "WH" --dataset-catalog CATALOG --dataset-schema SCHEMA --serialized-dashboard "$(cat file.json)" --json '{"parent_path": "/Workspace/Users/<you>/path"}' — --dataset-catalog / --dataset-schema はフラグ専用（必須。--json に指定すると、CLI は警告なしで無視します）。parent_path は JSON 専用です（フラグはありません）。クエリではテーブル名のみを指定してください。 |
| ダッシュボードの更新 | databricks lakeview update DASHBOARD_ID --dataset-catalog CATALOG --dataset-schema SCHEMA --serialized-dashboard "$(cat file.json)" — 更新時は必ず --dataset-catalog / --dataset-schema を再指定してください（作成時と同じフラグ専用のルールです）。更新するとシリアライズされたダッシュボードが置き換えられるため、これらを省略するとデータセットごとのデフォルト値が null になり、テーブル名のみを指定したすべてのクエリが動作しなくなります。 |
| 公開 | databricks lakeview publish DASHBOARD_ID --warehouse-id WH |
| 削除 | databricks lakeview trash DASHBOARD_ID |
--warehouseフラグ：databricks experimental aitools tools query --warehouse WH "..."を実行したとき、お使いの CLI バージョンでunknown flag: --warehouseが発生する場合は、代わりに環境変数DATABRICKS_WAREHOUSE_ID=WHを設定し、フラグを省略してください。コマンドは環境変数から値を自動的に取得します。
ウィジェット一覧（バージョン＋ドキュメントの掲載場所）
バージョンが間違っているとウィジェットは動作しません！ ダッシュボードのエラーの原因として最も多いものです。
コホート継続率チャートは、色スケールのセルスタイルを使用する
pivotとして作成します。cohortウィジェットの種類はありません。詳しくは、2-advanced-widget-specifications.md の pivot を参照してください。
新しいダッシュボードの作成ワークフロー
デプロイする前に、CLI を使ってすべての SQL クエリを必ずテストしてください。新しいダッシュボードを作成する際は、以下の手順の全体的な流れに従ってください。検証を省略すると、ダッシュボードが正しく動作しなくなります。
ステップ 1：まだわかっていない場合は Warehouse ID を取得する
# List warehouses to find one for SQL execution
databricks warehouses list
ステップ 2：テーブルスキーマと既存データのパターンを確認する
良いダッシュボードを作るには、まずデータを把握する必要があります。ここに時間をかけてください。データの探索は、ステップ 4 での設計上の判断（ウィジェット、フィルター、グループ化の選択）に役立ちます。
標準では discover-schema を使ってください。1 回の呼び出しで、列、型、サンプル行、NULL 件数、行数が返されます。スキーマしかわからない場合は、まず query "SHOW TABLES IN ..." でテーブルを一覧表示してください。
databricks experimental aitools tools discover-schema catalog.schema.orders catalog.schema.customers
サンプル行だけでは、何を作るべきかはわかりません。通常は、databricks experimental aitools tools query --warehouse <WH> "..." を使って集計 SQL を実行し、次の項目を調べます。
- 候補となるグループ化列のカーディナリティ → グラフで色分けするか、テーブルにするかを決定します（グラフの場合は個別値が 8 以下です。「カーディナリティと読みやすさ」を参照）。
- カテゴリ値の上位項目 → フィルターの選択肢やグラフの凡例に適切な値を設定できます。
- 数値の分布（最小値／最大値／平均値／パーセンタイル）→ 差分付き KPI にするか、トレンドグラフにするかを決定します（変動のない指標は折れ線グラフにしないでください。「データの変動に関する考慮事項」を参照）。
- トレンドの有効性（日次／週次／月次の粒度）→ 適切なトレンドの粒度を選択できます。
- ストーリーの確認 — ダッシュボードに含める予定の集計を実行し、結果が一定のまま、空、または興味を引かない状態ではないことを確認します。次に進む前に、クエリを修正するか、ストーリーを調整してください。
独立したプローブは、1 回の呼び出しでまとめて実行できます。位置引数で複数の SQL を渡す（および／または --file を繰り返し指定する）と、並列実行されます（デフォルトの --concurrency 8）。
DATABRICKS_WAREHOUSE_ID=<WH> databricks experimental aitools tools query --output json \
"SELECT COUNT(*) FROM catalog.schema.orders" \
"SELECT region, COUNT(*) FROM catalog.schema.orders GROUP BY region ORDER BY 2 DESC LIMIT 10" \
"SELECT MIN(ts), MAX(ts) FROM catalog.schema.orders"
- 複数クエリモードでは、
--output jsonが必須です。各ステートメントにつき 1 つのオブジェクト{sql, state, rows, error}が返されます。失敗はステートメントごとに記録され（state: "FAILED"）、ほかのステートメントは引き続き成功します。 - ⚠️ 終了コードを信用しないでください（ステートメントが失敗していても、終了コードが
0になることがあります）。各オブジェクトのstate != "SUCCEEDED"を条件として判定してください。
ダッシュボードのクエリは異なります — ダッシュボード JSON 内では、
FROM句にカタログやスキーマのプレフィックスを付けず、テーブル名だけを指定する必要があります。
- ✅ 正しい例：
FROM trips- ❌ 誤った例：
FROM nyctaxi.trips- ❌ 誤った例：
FROM samples.nyctaxi.tripsカタログとスキーマは、
databricks lakeview createの実行時に--dataset-catalogフラグと--dataset-schemaフラグで別々に指定します。これらのフラグはクエリを書き換えません。クエリから省略されているカタログ／スキーマを補うだけです。FROM句にカタログやスキーマを直接指定した場合、そのクエリではフラグが無視され、ダッシュボードを環境間で移植できなくなります。
ステップ 3：データがストーリーに合っていることを確認する
ダッシュボード JSON の datasets.querylines（以下の例を参照）は、確実に実行できることを確認するためにテストする必要があります。
最終決定する前に、各データセットに追加する予定の SQL クエリを実行し、正常に実行されることと、結果が妥当であることを確認してください。 これは非常に重要です。JSON で定義されたウィジェットは、可視化の描画にクエリフィールドの出力を使用します。また、その値がビジネスの観点から見て妥当であることも確認してください。 フィルターを機能させるには、クエリでそのフィールドを使用できるようにする必要があります（通常は、フィルターフィールドでグループ化します）。
値が期待と一致しない場合は、クエリが正しいことを確認し、可能であればデータを修正するか、ダッシュボードを作成する前にストーリーを調整してください。
ステップ 4：ダッシュボードの構成を計画する
JSON を作成する前に、ダッシュボードの構成を計画します。
- 想定される具体的な JSON 構造を把握する必要があります。そのために、リファレンスファイルを読みます：1-widget-specifications.md、3-filters.md。
構造を理解できるよう、4-examples.md などのサンプルを最後まで読んでください。
-
次の点を検討します：どのウィジェットを使うか？ 各ビジュアライゼーションをデータセットに対応付けます。
ウィジェット 種類 データセット フィルターフィールドがあるか？ 売上 KPI カウンター ds_sales ✓ date、region トレンドチャート 折れ線 ds_sales ✓ date、region 人気商品 テーブル ds_products ✗ date なし ... -
どのフィルターを使うか？ フィルターごとに、フィルター対象にするすべてのデータセットにフィルターフィールドが含まれていることを確認します。
フィルターの影響を受けるのは、フィルターフィールドがあるデータセットのみです。 日付のない事前集計テーブルは、日付でフィルターされません。
-
ダッシュボード JSON を作成します。ローカルの作業ファイルとして作成してください（中間成果物であり、納品物ではありません）。
ステップ 5：デプロイする
ここで JSON をワークスペースにデプロイします。 databricks lakeview create（下記）を実行します。このコマンドが成功し、ダッシュボード ID が返されるまでタスクは完了していません。JSON ファイルだけでは、中間作業成果物にすぎません。
ユーザーにダッシュボードのリンクを提示します（ホストは databricks auth env -o json → .env.DATABRICKS_HOST から取得します）。v3 に注意してください。/sql/dashboards/ にはこの部分がなく、古い形式のパスになるため誤りです。
- ドラフト：
https://<host>/sql/dashboardsv3/<DASHBOARD_ID> - 公開済み：
/publishedを追加します（databricks lakeview publish DASHBOARD_IDを実行した後にのみ有効です）
デプロイ後は、同じ lakeview サブコマンドを使ってダッシュボードのライフサイクル（一覧表示、取得、更新、公開、ゴミ箱への移動）を管理できます。
# Deploy: creates the dashboard in the workspace and returns a dashboard ID.
# Canonical form — MIX flags + --json. Each field has exactly ONE valid place:
# --dataset-catalog / --dataset-schema : FLAG-ONLY (REQUIRED — no JSON field).
# The CLI silently warns "unknown field" and drops them if put in --json,
# leaving every dataset query unable to resolve its catalog.schema.
# parent_path : JSON-ONLY (no flag). Without it, dashboard lands at
# /Users/<you>/<display-name>.
# display_name / warehouse_id / serialized_dashboard : either form works;
# prefer flags for readability.
# Queries inside dashboard.json MUST use bare table names ("FROM trips", never
# "FROM schema.trips" or "FROM catalog.schema.trips") — --dataset-catalog and
# --dataset-schema only fill in missing parts, they do NOT rewrite hardcoded
# prefixes.
#
# parent_path must ALREADY EXIST or create fails "Tree node ... does not exist":
databricks workspace mkdirs /Workspace/Users/[email protected]/dashboards
# Capture the dashboard_id with -o json. Do NOT add 2>&1: create echoes the
# serialized dashboard back, and merging stderr breaks the output so jq can't
# parse it (the dashboard IS created, but you lose the id and the step looks failed).
DASHBOARD_ID=$(databricks lakeview create \
--display-name "My Dashboard" \
--warehouse-id "abc123def456" \
--dataset-catalog "my_catalog" \
--dataset-schema "my_schema" \
--serialized-dashboard "$(cat dashboard.json)" \
--json '{"parent_path": "/Workspace/Users/[email protected]/dashboards"}' \
-o json | jq -r '.dashboard_id')
# List all dashboards
databricks lakeview list
# Get dashboard details
databricks lakeview get DASHBOARD_ID
# Update a dashboard
# ALWAYS re-pass --dataset-catalog / --dataset-schema: update replaces the
# serialized dashboard, so omitting them nulls the defaults and breaks queries.
databricks lakeview update DASHBOARD_ID \
--dataset-catalog "my_catalog" \
--dataset-schema "my_schema" \
--serialized-dashboard "$(cat dashboard.json)"
# Publish a dashboard
databricks lakeview publish DASHBOARD_ID --warehouse-id WAREHOUSE_ID
# Unpublish a dashboard
databricks lakeview unpublish DASHBOARD_ID
# Delete (trash) a dashboard
databricks lakeview trash DASHBOARD_ID
# By default, after creation, tag dashboards to track resources created with this skill
databricks workspace-entity-tag-assignments create-tag-assignment \
dashboards DASHBOARD_ID aidevkit_project --tag-value ai-dev-kit
既存のダッシュボードを更新する
既存のダッシュボードを変更するには、上記の新しいダッシュボードの作成ワークフローに従って更新後の JSON を作成し、同じ DASHBOARD_ID に対して update と publish を実行してデプロイします。create やインポートを再実行してはいけません。
- 更新には
createやインポートを使わないでください。 新しいダッシュボード ID と URL が発行され、すでに共有したリンクが使えなくなります。createを使うのは、新しいダッシュボードを作成する場合のみです。 updateで変更されるのはドラフトのみです。 閲覧者に表示される/publishedのリンクは、最後に公開した時点のスナップショットを引き続き表示します。そのため、updateの後は必ず再度publishを実行してください。
JSON 構造（必須の骨組み）
すべてのダッシュボードの serialized_dashboard コンテンツは、必ず次の構造にしてください。
重要：データセットの作成時に値が連結されるため、各 queryLines の値の末尾には必ずスペースまたは \n を追加してください。
{
"datasets": [
{
"name": "ds_x",
"displayName": "Dataset X",
"queryLines": ["SELECT col1, col2 ", "FROM my_table"]
}
],
"pages": [
{
"name": "main",
"displayName": "Main",
"pageType": "PAGE_TYPE_CANVAS",
"layout": [
{"widget": {/* INLINE widget definition */}, "position": {"x":0,"y":0,"width":2,"height":3}}
]
}
]
}
構造上のルール（違反すると「failed to parse serialized dashboard」が発生します）：
queryLines：文字列の配列であり、"query": "string"ではありません。各要素は区切り文字なしでそのまま連結されるため、各行の末尾に\nを付けてください（または--コメントを削除してください）。改行のない-- commentで終わる行は、次の行をコメントにしてしまいます。- ウィジェット：
"widgets"配列として分離せず、layout[].widget内に配置します。 pageType：各ページで必須です（PAGE_TYPE_CANVASまたはPAGE_TYPE_GLOBAL_FILTERS）。- クエリのバインド：チャート、テーブル、カウンター、カスタムビジュアライゼーションの
query.fields[].nameの値は、encodings.*.fieldNameの値と完全に一致している必要があります。フィルターはウィジェットごとのバインドを使用します。範囲スライダーでは、1 つの基になるfieldNameに対してMIN／MAXクエリフィールドが公開されます。パラメーターにバインドされた日付フィルターではquery.parametersを使用します。
テーマと色（必ず設定してください。ダッシュボードの仕上がりを大きく左右します）
トップレベルの uiSettings.theme は、ダッシュボード上のすべてのウィジェットに適用される色、フォント、ウィジェットの外観を制御します。これがないと、ダッシュボードはワークスペースのデフォルト設定を引き継ぎ、ありきたりな見た目になります。作成するすべてのダッシュボードで、テーマの設定ブロック全体を指定してください。 一貫性のある配色は、仕上がりを大きく高める最も重要な要素です。
メンタルモデル — テーマキーに当てはめた 60/30/10 ルール：60％はニュートラルカラー＝キャンバス／ウィジェット／境界線の背景（境界線を非表示にするには widgetBorderColor = widgetBackgroundColor を設定）；30％はセカンダリカラー＝fontColor ＋ visualizationColors（コンテンツの比重を担います）；10％はアクセントカラー＝フィルター／タブ／アクティブな選択項目の selectionColor — テキストやパレットとはっきり区別できる色を選びます。安全な青である #2272B4 前後の色は、ハイパーリンクの慣例に合い、デフォルトとして使えます。
{
"datasets": [...],
"pages": [...],
"uiSettings": {
"theme": {
"canvasBackgroundColor": {"light": "#FCFCFC", "dark": "#1F272D"},
"widgetBackgroundColor": {"light": "#FFFFFF", "dark": "#11171C"},
"fontColor": {"light": "#11171C", "dark": "#E8ECF0"},
"selectionColor": {"light": "#2272B4", "dark": "#8ACAFF"},
"visualizationColors": [
"#FFA600", "#FF7054", "#DE5582", "#995495",
"#4E5185", "#1D425C", "#99DDB4"
],
"widgetHeaderAlignment": "LEFT"
}
}
}
テーマキー（仕組み）：
visualizationColors：すべてのチャート系列とカテゴリのマッピングが循環して使用する、順序付きのパレットです。位置は 0 始まりです。position: 0= 1 番目の色（上記の#FFA600）、position: 6= 7 番目（#99DDB4）です。通常は 5～8 色です。- 背景色／フォント色／選択色には
lightとdarkのペアを指定します。ダッシュボードは閲覧者のモードに応じて自動選択します。 fontColorはカウンターの数値の色も決めます。カウンターにはウィジェット単位の色設定がないため、これだけが設定手段です（タイルごとではなく、ダッシュボード上のすべてのカウンターの値に適用されます）。widgetHeaderAlignment："LEFT"（デフォルト）、"CENTER"、または"RIGHT"。任意のトップレベル設定：fontFamily（例："Space Grotesk"、"Inter"— サンセリフ体にすると、情報量の多いデータを読みやすく保てます。ウィジェットごとには上書きしないでください）およびwidgetCornerRadius（整数の px 値。例：角を丸くする場合は12、四角にする場合は0または省略）。- ウィジェット単位の色指定（チャートのみ）：パレットのスロットに固定する場合は
{"themeColorType": "visualizationColors", "position": N}（0 始まり）、パレット外の正確な色を指定する場合は{"hex": "#FF0000"}を使います。カウンターはウィジェット単位の色指定に対応していません — カウンターのvalueにcolorを指定すると、ウィジェットは「unsupported widget definition」として表示されます。カウンターの色は、上記のfontColorで設定してください。
パレット設計のルール（洗練されたダッシュボードと雑然としたダッシュボードの違いを生むポイントです）：
- ダッシュボードごとに統一感のある色系統を 1 つ使い、スイート内では色系統を変えます。 白に近づけて同じ色を薄くするのではなく、色相を変化させます（例：アンバー → コーラル → ピンク → パープル → ネイビー）。単色の明度ランプは 1 色に見え、閲覧者がカテゴリを区別できません。隣り合う色は、見た目ではっきり区別できるようにします。目を細めて 2 色がひとつに見えるなら、さらに差を広げてください。単色のランプは定量的なウィジェットのみで使用し（
colorRamp.mode: "custom-sequential"）、visualizationColorsでは使用しないでください。 - 意味を持つ色は、パレット外のリテラルな hex 値として固定します。 「悪い」は暖色系のコーラル（例：
#FF7E5C）、「良い」は落ち着いたティール／グリーンにします。color.scale.mappingsには、裸の hex 文字列を使用します —{"value": "Critical", "color": "#FF7E5C"}—{"hex": "..."}やthemeColorType: positionは使わないでください（チャートウィジェットでは、どちらも警告なしに無視されます）。すでにパレットにある良いティールを再利用し、色がぶつからないようにします。 - カテゴリ別ではないウィジェットには明示的に色を指定し、色系統になじませます。 マップとヒートマップ：色系統の
{start, end}を指定してcolorRamp.mode: "custom-sequential"を使います（方向性がある場合は、start= 悪い色、end= 良い色）。予測／複数系列：displayNameをキーにしたcolor.scale.mappingsで系列ごとに固定します（実績 = 色系統の基本色、予測 = 対照色／警告色、しきい値 = 控えめな色調）。カウンター（スパークラインカウンターを含む）にはウィジェット単位の色を指定できません — 数値の色はテーマのfontColorで決まります。value.colorは設定しないでください（「unsupported widget definition」として表示されます）。 - 「もっと明るく／パステル調にする」調整：個々の色を変更せず、すべての色をまとめて明度を上げます。固定した意味色の hex 値も合わせて更新し、警告色は警告として認識できるだけのコントラストを維持します。
スターターパレット（1 つ選んで調整してください。必要に応じて 7～8 色まで拡張します。ルール 2 に従い、意味を持つ赤／緑はリテラルな hex 値のままにしてください）：
#094074 #3C6997 #5ADBFF #FFDD4A #FE9000
#003F5C #594E90 #BC4C96 #FF5F66 #FFA600
#4A8CC7 #F59770 #FFD84A #F0E09E #6DD980
#440154 #3B528B #21918C #5EC962 #FDE725
#4E79A7 #F28E2C #E15759 #76B7B2 #59A14F
#0072B2 #E69F00 #009E73 #CC79A7 #D55E00
#0D0887 #7E03A8 #CC4778 #F89441 #F0F921
#6929C4 #1192E8 #005D5D #9F1853 #FA4D56
閲覧者の約 4～5％は色覚異常があります（主に赤／緑）。上記の 4 行目と 6 行目（viridis、Okabe-Ito）は、設計上、色覚異常に配慮しています。カスタマイズしたパレットはシミュレーター（Adobe Color、colorbrewer2.org）で確認してください。赤と緑を隣り合わせにせず、隣り合う色の違いは色相だけでなく明度のコントラストにも頼ってください。
Genie Space のリンク（任意）
ダッシュボードに「Ask Genie」ボタンを追加する場合、または ID を使って genie space／room をリンクする場合は、JSON に uiSettings.genieSpace を追加します（theme がある場合は、その横に追加します）。
"uiSettings": {
"theme": { /* ... */ },
"genieSpace": {
"isEnabled": true,
"overrideId": "your-genie-space-id-here",
"enablementMode": "ENABLED"
}
}
Genie はウィジェットではありません。 リンクには
uiSettings.genieSpaceのみを使用してください。"widgetType": "assistant"はありません。
デザインのベストプラクティス
ユーザーから別途指定がない限り、以下を適用してください。
- グローバル日付フィルター：データに時間列がある場合は、日付範囲フィルターを追加します。ほとんどのダッシュボードで時間によるフィルタリングが必要です。
- KPI の期間設定：期間比較（MoM、YoY）を可能にする、期間を限定した指標を使用します。「全期間」の合計は、実用性が低くなりがちです。
- 値の書式設定：値の意味に合わせて書式を設定します。通貨には通貨記号、割合には % を付け、大きな数値は短縮表記（K/M/B）にします。
- チャートの選択：値の種類の数に合ったチャートタイプを選びます。異なる値が少ない場合は、色分けした棒グラフ（スナップショットを表示したい場合は円グラフも可）、多い場合はテーブルを使用します。
リファレンスファイル
ダッシュボード JSON を生成する前に、まず 4-examples.md を読んでください。 データセットのメジャーと
MEASURE()、スパークラインカウンター、注釈付き予測線、条件付きセルを含むピボット、シンボルマップ、ヒストグラム、範囲スライダーフィルター、テーマなど、あらゆる構成要素を網羅した完全なリファレンスダッシュボードです。JSON の構造を確認してから、ユーザーのデータとデモのストーリーに合わせて調整してください。構造は保ちつつ、構築するケースに合わせてテーブル、指標、パレット、説明を差し替えます。
| 作成するもの | リファレンス |
|---|---|
| まずはこちら — 完全に動作するダッシュボードのテンプレート | 4-examples.md |
| 任意のウィジェット（テキスト、カウンター、テーブル、チャート） | 1-widget-specifications.md |
| 高度なチャート（面、散布図／バブル、複合、ガント、コロプレス／経路マップ） | 2-advanced-widget-specifications.md |
| フィルター付きダッシュボード（グローバルまたはページレベル） | 3-filters.md |
| カスタム Vega-Lite ウィジェット（レイヤーチャート、ブレット、ゲージ、レーダー、サンバースト） | 6-custom-visualizations.md |
| 壊れたダッシュボードのデバッグ | 5-troubleshooting.md |
実装ガイドライン
1) データセットアーキテクチャ
- データセットは少ないほどよく、できるだけ多くのウィジェットを支えるデータセットを1つ作ることを目指します。 チャートの値（棒やスライスなど）をクリックすると、そのデータセットにフィルターが適用され、同じデータセットを共有するほかのすべてのウィジェットが、クリックによるフィルターを適用して再描画されます。ウィジェットを多数の細分化されたデータセットに分けると、このクロスフィルタリングが機能せず、本来は「そのまま動作する」はずの処理に、ユーザーが明示的なフィルターウィジェットを設定する必要が生じます。ドメインごと（注文、ケース、顧客など）に、幅広いデータセットを1つ使うことを優先します。ウィジェットに異なる粒度や事前集計が本当に必要な場合、またはほかのウィジェットでは扱えないパラメーターが必要な場合に限り、分割してください。
- データセットの定義方法は2つあります。
- SQL クエリ：
{"name": "ds_x", "displayName": "...", "queryLines": ["SELECT ...", "FROM table"]}— 完全に制御でき、WITH／JOIN／AI_FORECASTなどを含められます。 - UC アセットの省略記法：
{"name": "ds_x", "asset_name": "catalog.schema.table_or_view"}— SQL は不要です。テーブル、ビュー、メトリックビューで使用できます。columns（メジャーおよび派生ディメンション）を追加することもできます。例：{"name": "ds_x", "asset_name": "...", "columns": [{"displayName": "Total Revenue", "expression": "SUM(\amount_usd`)"}]}— 同じMEASURE()` パターンを使用します。
- SQL クエリ：
queryLinesを使用する場合、データセットごとに有効な SQL クエリは必ず1つだけにしてください（;で区切った複数のクエリは不可）。- クエリではテーブル名のみを指定してください — カタログ名やスキーマ名のプレフィックスは付けません。例：
FROM ordersとし、FROM gold.ordersやFROM main.gold.ordersとはしないでください。カタログとスキーマは、作成時の--dataset-catalogおよび--dataset-schemaフラグから指定します。これらのフラグは不足している部分のみを補い、クエリに記述されたカタログ名やスキーマ名を上書きしません。 - SELECT には、ウィジェットに必要なすべてのディメンションと、
ASエイリアスを付けた派生列を含めてください。 - すべてのビジネスロジック（CASE／WHEN、COALESCE、比率）は、明示的なエイリアスを付けてデータセットの SELECT に記述してください。
- 可視化のコントラクトルール：チャート、テーブル、カウンター、カスタム可視化ウィジェットでは、すべての
fieldNameが対応するquery.fields[].nameと一致している必要があります。そのクエリフィールドの式は、データセットの列またはエイリアスを参照します。範囲スライダーとパラメーターバインディングの例外を含む、フィルター固有のコントラクトについては、3-filters.md を参照してください。 - 可視化がデータの順序に依存する場合は、ORDER BY を追加してください。
- 時系列：時系列で表示するには
ORDER BY date - ランキング／上位 N 件：上位10件のチャートには
ORDER BY metric DESC LIMIT 10 - カテゴリ別チャート：値の大きいものから表示するには
ORDER BY metric DESC
- 時系列：時系列で表示するには
データセットレベルのメジャーと MEASURE()
ウィジェットの式には通常、インラインの集計（{"name": "sum(x)", "expression": "SUM(\x`)"}`）を使います。ただし、再利用可能なメジャーをデータセット自体に定義し、名前で参照することもできます。データセットを使うすべてのウィジェットで、定義し直すことなく同じメトリックを使用できます。
メジャーの定義方法は2つあります。
-
ダッシュボードレベルの
columns（SQL クエリまたはasset_nameのどちらのデータセットでも使用できます）：{ "name": "ds_support", "queryLines": ["SELECT * FROM support_cases"], "columns": [ {"displayName": "Total Cases", "description": "Count of cases", "expression": "COUNT(`case_id`)"}, {"displayName": "Reopen Rate %", "description": "% of reopened cases", "expression": "SUM(CASE WHEN `reopened_flag` THEN 1 ELSE 0 END) * 100.0 / COUNT(`case_id`)"}, {"displayName": "Priority Level", "description": "Sorted priority label", "expression": "CASE WHEN `priority`='Critical' THEN '1-Critical' ELSE '4-Low' END"} ] } -
メトリックビューのソース — データセットの
asset_name（またはFROM句）が UC メトリックビューの場合、YAML で定義されたメジャーはすでにクエリ可能です。columnsで再定義しないでください。databricks-metric-views を参照してください。
どちらの場合も、ウィジェットではメジャーを名前で参照します。
"fields": [{"name": "measure(Total Cases)", "expression": "MEASURE(`Total Cases`)"}],
"encodings": {"value": {"fieldName": "measure(Total Cases)", "displayName": "Total Cases"}}
MEASURE(\...`)` は、カウンター、テーブル、棒、折れ線、円、ピボットなど、フィールド式を受け取るあらゆるウィジェットで使用できます。インライン集計と自由に組み合わせられます。
2) ウィジェットのフィールド式
重要：フィールド名の一致ルール グラフ、テーブル、カウンター、カスタムビジュアライゼーションの各ウィジェットでは、
query.fieldsで選択する各nameが、encodings内のfieldNameと完全に一致している必要があります。 一致しない場合、ウィジェットに「no selected fields to visualize」エラーが表示されます。
custom-vega-viz の場合は、spec.encodings.fields[].fieldName も Vega-Lite の入力 field 名に一致させてください。spec.data.queryName には、ウィジェットのクエリ名を設定します。内部の Vega-Lite 仕様では data.name: "databricks_query" を読み込み、spec.jsonSpec.spec に JSON 文字列として保存します。カスタムウィジェットを生成する前に、6-custom-visualizations.md をお読みください。
集計式の正しいパターン：
// In query.fields:
{"name": "sum(spend)", "expression": "SUM(`spend`)"}
// In encodings (must match!):
{"fieldName": "sum(spend)", "displayName": "Total Spend"}
誤り — 名前が一致していません：
// In query.fields:
{"name": "spend", "expression": "SUM(`spend`)"} // name is "spend"
// In encodings:
{"fieldName": "sum(spend)", ...} // ERROR: "sum(spend)" ≠ "spend"
ウィジェットのクエリで使用できる式（式の中で CAST やその他の SQL は使用できません）：
{"name": "(sum|avg|count|countdistinct|min|max)(col)", "expression": "(SUM|AVG|COUNT|COUNT(DISTINCT)|MIN|MAX)(`col`)"}
{"name": "(daily|weekly|monthly)(date)", "expression": "DATE_TRUNC(\"(DAY|WEEK|MONTH)\", `date`)"}
{"name": "field", "expression": "`field`"}
条件分岐や複数フィールドを使った数式が必要な場合は、先にデータセットの SQL で派生列を計算してください。
一部のウィジェットでは、追加の式を使用できます。ガントではステータスフィールドに FIRST(...) を使用でき、ジオメトリマップのバインディングには ST_ASGEOJSON(...) が必要です。これらの形式については、該当するウィジェットのリファレンスを参照してください。
3) SPARK SQL のパターン
- 日付計算：日数には
date_sub(current_date(), N)、月数にはadd_months(current_date(), -N)を使用します - 日付の切り捨て：
DATE_TRUNC('DAY'|'WEEK'|'MONTH'|'QUARTER'|'YEAR', column) INTERVAL構文は避けてください。代わりに関数を使用します
4) レイアウト（12 列グリッド、隙間なし）
各ページには pageType と併せて "layoutVersion": "GRID_V1" を必ず含めてください。
{
"name": "overview",
"displayName": "Overview",
"pageType": "PAGE_TYPE_CANVAS",
"layoutVersion": "GRID_V1",
"layout": [...]
}
各ウィジェットには位置を指定します：{"x": 0, "y": 0, "width": 4, "height": 4}
対象ユーザーに合わせて分割方法を選んでください。 12 列グリッドは、3 列、4 列、6 列にきれいに分割できます。3 列のレイアウト（各ウィジェットの width: 4）は認知負荷を軽減し、経営層向けの概要に適しています。4 列（width: 3）は幅広い用途に対応します。6 列（width: 2）は、一度に多くの指標を確認する技術部門や運用部門向けのダッシュボードで、最も多くの情報を詰め込めます。
デフォルトのルール：各行の幅は隙間なく、正確に 12 にしてください。グリッドに慣れてきたら、列ごとに高さをずらすこともできます（左側に高さのあるウィジェットを置き、右側に短いウィジェットを複数並べるなど）。これにより、左右の半分で行の境界を揃えずに済みます。パターンについては 4-examples.md を参照してください。まずは行を厳密に揃え、視覚的に見やすくなる場合にのみずらしてください。
CORRECT: WRONG:
y=0: [w=12] y=0: [w=8]____ ← gap!
y=1: [w=4][w=4][w=4] ← fills 12 y=1: [w=2][w=2][w=2][w=2]__ ← gap!
y=4: [w=6][w=6] ← fills 12
推奨ウィジェットサイズ：
| ウィジェットの種類 | 幅 | 高さ | 備考 |
|---|---|---|---|
| テキスト見出し | 12 | 1 | 全幅を使用します。タイトルとサブタイトルには別々のウィジェットを使用してください |
| カウンター／KPI | 4 | 3-4 | 高さを 2 にしないでください。狭すぎます |
| 折れ線／棒／面グラフ | 6 | 5-6 | 行を埋めるように横に並べます |
| 円グラフ | 6 | 5-6 | 凡例を表示するためのスペースが必要です |
| 全幅グラフ | 12 | 5-7 | 詳細な時系列データ向けです |
| テーブル | 12 | 5-8 | 読みやすさのため全幅を使用します |
標準的なダッシュボードの構成：
y=0: Title (w=12, h=1) - Dashboard title (use separate widget!)
y=1: Subtitle (w=12, h=1) - Description (use separate widget!)
y=2: KPIs (w=4 each, h=3) - 3 key metrics side-by-side
y=5: Section header (w=12, h=1) - "Trends" or similar
y=6: Charts (w=6 each, h=5) - Two charts side-by-side
y=11: Section header (w=12, h=1) - "Details"
y=12: Table (w=12, h=6) - Detailed data
5) カーディナリティと読みやすさ（重要）
ダッシュボードの読みやすさは、異なる値の数を制限することに左右されます：
| ディメンションの種類 | 最大値数 | 例 |
|---|---|---|
| グラフの色／グループ | 3-8 | 4 つの地域、5 つの商品ライン、3 つのティア |
| フィルター | 4-15 | 8 つの国、5 つのチャネル |
| 高カーディナリティ | テーブルのみ | customer_id、order_id、SKU |
色分け／グループ化を使うグラフを作成する前に：
- discover-schema または COUNT DISTINCT クエリで、列のカーディナリティを確認します
- 異なる値が 10 を超える場合は、より上位のレベルに集計するか、TOP-N と「その他」のバケットを使用します
- カーディナリティの高いディメンションには、グラフではなくテーブルウィジェットを使用します
6) 品質チェックリスト
デプロイする前に、次の項目を確認してください。
- すべてのウィジェット名が、英数字、ハイフン、アンダースコアのみを使用している
- すべてのページに
"layoutVersion": "GRID_V1"が設定されている - すべての行の幅の合計が 12 で、隙間がない
- KPI の高さが 3～4、チャートの高さが 5～6 である
- チャートのディメンションのカーディナリティが適切である（色／グループは 8 以下）
- すべてのウィジェットのクエリ式が、既存のデータセットの列またはエイリアスを参照している
- 可視化のフィールドバインディングが完全に一致している：チャート、テーブル、カウンター、カスタム可視化では、それぞれの
query.fields[].nameがエンコーディングのfieldNameと一致している（例：どちらも"sum(spend)"）。フィルターは、代わりにウィジェット固有の仕様に照らして検証してください。 - カウンターのデータセット：1 行のデータセットでは
disaggregated: true、複数行のデータセットでは集計を使用してdisaggregated: falseを指定する number-percent形式では、パーセント値は 0～1 で指定する必要があります（0.865 は「86.5%」と表示されます。形式の設定を忘れないでください）。データが 0～100 の場合は、SQL で 100 で割るか、代わりにnumber形式を使用してください。- SQL では Spark の構文を使用する（
INTERVALではなくdate_sub） - すべての SQL クエリを CLI 経由でテストし、期待どおりのデータが返ることを確認する
- フィルターを適用するデータセットには、必ずフィルターフィールドを含める — フィルターの影響を受けるのは、クエリにその列が含まれるデータセットのみです。
abbreviation: "compact"にはdecimalPlacesが必要です — 設定しないと値は丸められず、$9.76Mではなく$9.756278496Mと表示されます。
データのばらつきに関する考慮事項
トレンドチャートを作成する前に、指標に意味のある可視化に十分なばらつきがあるか確認してください。
SELECT MIN(metric), MAX(metric), MAX(metric) - MIN(metric) as range FROM dataset
スケールに対して範囲が非常に小さい場合（例：0～100 のスケールで 83～89%）、チャートはほぼ平坦に見えます。次の方法を検討してください。
- チャートの代わりに、差分／比較を含む KPI として表示する
- テーブルを使って正確な値を表示する
- ばらつきに焦点を当てるよう、可視化を調整する
関連スキル
- databricks-apps - 管理型ダッシュボードではなく、カスタムコードによるインタラクティブアプリ（書き戻し、独自 UI、アプリ内チャット／Genie）が必要な場合
- databricks-unity-catalog - 基盤となるデータやシステムテーブルをクエリする場合
- databricks-pipelines - ダッシュボードにデータを供給するデータパイプラインを構築する場合
- databricks-jobs - ダッシュボードのデータ更新をスケジュールする場合