metabase

Metabase Skill

Metabase 向けのエンドツーエンドの BI 開発ツールです。ダッシュボードの設計、SQL の作成とテスト、ダッシュボードのファイルとしての保存、公開、結果の確認、共有やスケジュール設定ができます。

すべてのスクリプトは ${CLAUDE_SKILL_DIR}/scripts/ にあり、必要なのは Node.js のみです（npm install は不要です。レンダリングには Node 22+ と Google Chrome が必要です）。以下のすべてのコマンドは node ${CLAUDE_SKILL_DIR}/scripts/metabase.mjs <command> です。

初回セットアップ

instances を実行すると、存在する Metabase 接続を確認できます（キーやトークンが表示されることはありません）。~/.metabase-skill/config.json や ~/.metabase-skill/tokens/ 以下のファイルは、秘密情報が含まれている可能性があるため、決して読み取らないでください。

• インスタンスが表示された場合： それらを使用します。複数ある場合は、どれを使うか尋ねてください。status では、サインイン中のユーザー、サインイン方法、 Metabase のバージョン、無料版かどうかを確認できます。
• 設定済みのインスタンスがない場合： ユーザーにターミナルでサインインしてもらいます（ブラウザーが開きます。代わりに実行することはできません）。

node ${CLAUDE_SKILL_DIR}/scripts/metabase.mjs login --instance <name> --url https://metabase.example.com

ブラウザーでのサインイン（Metabase v63+）では、ユーザー自身の Metabase アカウントと権限が使用されます。トークンは macOS Keychain（別の場所にあるプライベートファイル）に保存され、自動的に更新されます。API キーはスクリプトや CI でも引き続き使用できます。setup → env または direct モードを選択してください。login でアプリの登録がオフだと表示された場合、管理者が Admin > AI > MCP を無効にしています（自動登録もオフになります）。再度有効にするか、アプリを登録して --client-id を渡してください。

クイックリファレンス

グローバルオプション（すべてのコマンドで使用できます）：

• --instance <name> — デフォルト以外の接続を使用します
• --json — JSON 出力（リスト／検出コマンドは指定しない場合、テキストの表を出力します。get/create/update は常に JSON を出力します）
• --fields <a,b.c> — JSON 結果のうち、指定したドットパスのみを出力します（リストでは項目ごと）。例：card 402 --fields name,dataset_query.stages.0.native
• --max-bytes <n> — 出力する JSON のサイズ上限（デフォルトは 24576、0 = 上限なし）。リストは通知とともに省略されます。サイズ超過のオブジェクトは出力されません（終了コード 2）。--fields で範囲を絞るか、--out を使用してください
• --skip-preflight — 機能がないインスタンスで、Pro／Enterprise 専用コマンドを試します
• --theme light|dark — Chrome でレンダリングする画像の配色（デフォルトは light。Metabase はそれ以外では OS の設定に従います）

終了コード：0 成功、1 操作の失敗、2 入力／事前チェックの問題（入力を修正してください。メッセージに原因が表示されます）。

サインイン

コマンド	内容
login --instance <n> --url <u> [--client-id <id>]	ブラウザーでサインイン（v63+）。接続を作成します
logout [--instance <n>]	保存されたサインインを取り消して削除します
status [--instance <n>]	ユーザー、認証方法、トークンの有効期限、Metabase のバージョン、エディション
setup / instances	ウィザード（ブラウザーまたは API キー）／接続の一覧表示

プロジェクト — YAML + SQL ファイルで構成するダッシュボード（specs/project-format.md を参照）

コマンド	説明
project new <dir> --name <n> --database <id> [--collection <id>]	新しいダッシュボード用の空のプロジェクトフォルダーを作成します
project pull <dir> [--dashboard <id> [--loose-cards] | --collection <id>] [--force]	Metabase → ファイル（初回の pull では --dashboard または --collection が必要です。--loose-cards を指定すると、ダッシュボードに含まれないコレクションのカードも保持します。ローカルの編集内容は上書きしません）
project validate <dir> [--json]	構造、参照、24 列グリッド、フィルターの接続、SQL タグ、チャート設定を検証します
project lint <dir> [--strict] [--offline]	デザインをチェックします（説明、数値形式、行全体、未接続のフィルターなど）
project diff <dir> [--json]	push で変更される内容を、フィールドごと、配置ごとに正確に表示します
project status <dir>... [--json]	フォルダー内またはその配下にあるすべてのプロジェクトの状態を表示します。同期済み、Metabase 側で変更済み（pull）、または未 push です。読み取り専用です
project push <dir> [--dry-run] [--yes]	ファイル → Metabase（スニペット、カード、ダッシュボード、サブスクリプション）。差分がある場合は警告します
project test <dir> [--card <key>] [--images]	ダッシュボードのデフォルトフィルターを適用し、ファイルに記述されたすべてのカードを実行します。--images は PNG を出力します
project render <dir> [--pdf] [--tab <name>]	公開済みダッシュボードの画像／PDFを <dir>/.mbsync/render/ に出力します

画像とPDF（specs/rendering.md を参照）

コマンド	説明
card image <id> [--out f.png|f.pdf] [--params <json>] [--width N --height N]	保存済みの質問のチャート（カードレベルの設定。ダッシュボードのフィルターは適用されません）
dashcard image <dashboard-id> <index|name> [--id] [--out ..] [--params <json>]	ダッシュボード上での表示と同じタイルを出力します。独自のタイトル、値、書式設定、ダッシュボードのフィルターが反映されます
dashboard render <id> [--out f.png|f.pdf] [--tab <name|id>] [--params <json>]	すべてのタブを出力します（タブごとに PNG、または1つのPDF）。エラーが表示されているカードを報告します
dashboard render <id> --server [--out f.pdf] [--paper a4|letter]	Metabase 自体が描画するPDF（v63以降、サブスクリプション形式）。Chrome は不要です

検索

コマンド	説明
databases / tables --database <id>	データベース／テーブルとフィールド
collections [--tree] / collection-items <id> [--models card,dashboard]	コレクション（★ は公式）／内容
search <query> [--models ...]	名前であらゆるものを検索します

カード（質問）

コマンド	説明
card <id>	概要：結果の列、スニペット、テンプレートタグ
card <id> --full --out <file> / --layout --out <file>	全ペイロード／書き込み可能なフィールドをファイルに出力します
card create --from <file> [--skip-validate]	作成します（事前にタグ、フィールドフィルター、コンパイル、チャート設定を検証します）
card update <id> --patch <file> [--skip-validate]	取得 → マージ → 検証 → 保存
card delete <id> [--permanent --yes] / card restore <id>	アーカイブ（復元可能）／完全削除／アーカイブ解除
card copy <id> [--collection <id>]	複製します
card query <id> [--params '{"tag": value}'] [--out <file>]	実行します（20 行、または全行をファイルに出力します）
card query <id> --export csv|json|xlsx --out <file> [--params ..]	結果をダウンロードします
card history <id> / card revert <id> --to <revision-id> [--yes]	変更内容と変更者を確認／バージョンを復元します
pivot build --table <id> --rows <f[:unit],..> [--columns ..] --values <count|sum:F,..> (--out f.json | --project <dir> --key <k>)	正しい構造のピボット質問を書き出します（1回実行して確認してください）

ダッシュボード

コマンド	説明
dashboard <id>	概要：タブ、フィルター、配置、repeated_card_ids、配置ごとのoverrides
dashboard <id> --layout --out <file> / --full --out <file>	レイアウトのみ（カード30件で約3Kトークン）／全ペイロード
dashboard create --from <file>	シェルを作成
dashboard put <id> --from <file> [--skip-validate]	レイアウト全体を保存（参照されているすべてのカードを事前にチェックします）
dashboard update <id> --patch <file>	取得 → マージ → 保存
dashcard <dashboard-id> <index|name> [--id]	1つの配置の設定とフィルターの接続
dashcard update <dashboard-id> <index|name> [--id] --patch <file>	1つの配置を変更し、ほかは変更しません
dashboard delete <id> [--permanent --yes] / dashboard restore <id>	アーカイブ／完全削除／アーカイブ解除
dashboard copy <id> [--collection <id>]	複製
dashboard history <id> / dashboard revert <id> --to <revision-id>	変更内容と変更者の確認／バージョンの復元

アラートとサブスクリプション（specs/notifications-api-spec.mdを参照）

コマンド	説明
alerts [--card <id>] / alert <id>	カードのアラートを一覧表示／表示
alert create --from <file> / alert update <id> --patch <file>	カードにアラートを設定（条件 + Quartz cron + 受信者）
alert archive <id> / alert restore <id> / alert send <id> [--yes]	停止／再開／実際の受信者に今すぐ配信
subscriptions [--dashboard <id>] / subscription <id>	ダッシュボードのサブスクリプションを一覧表示／表示
subscription create --from <file> / subscription update <id> --patch <file>	スケジュールに従ってダッシュボードをメール／Slackで配信
subscription archive <id> / subscription restore <id>	停止／再開

スニペット、コレクション、メタデータ

コマンド	説明
snippets / snippet <id>	SQLを一覧表示／表示
snippet create --name <n> --content <sql> [--collection <id>] [--description <d>]	作成
snippet update <id> [--name] [--content] [--description] [--archived true|false]	更新またはアーカイブ（完全削除はできません）
collection create --name <n> [--parent <id>] [--description <d>]	作成
collection update <id> [--name] [--parent] [--description] [--archived true|false]	名前変更、移動、アーカイブ
database sync-schema <id> / field rescan-values <id> / field discard-values <id>	新しいカラムを取り込む／ドロップダウンの値を更新

ユーザー、グループ、権限

users [--query --status --admins --group <ids> --groups-all <ids>]、user <id>|create|update|deactivate、 groups、group <id>|create|delete|add-user|remove-user、permissions [--database] [--group] [--native-sql] [--collections]、permissions summary、permissions set … [--dry-run] [--yes]、permissions set-collection …。

Pro／Enterprise限定（無料版では早期に拒否されます）：usage-analytics …、sandboxes、sandbox create|delete、 permissions app [set]、permissions set-snippets、collection … --authority-level official。

--helpですべてのコマンドとフラグが表示されます。

コンテキストの安全ルール

必ず守ってください。

• ダッシュボード／カードの全ペイロードをコンテキストに読み込まないでください。 概要（card <id>、dashboard <id>）、一部分を指定する--fields、または--full --out <file>を使用してください。
• シークレットを表示したり読み取ったりしないでください。 APIキーとトークンが出力に含まれることはありません。config.jsonやtokens/を読み取らないでください。
• 送信するデータにはファイルを使用してください。 --from／--patchには、プロジェクトディレクトリ内のファイルパスを指定します。/tmpは使用しないでください。
• グラフの判断にはペイロードではなく画像を確認してください。 card image／dashboard renderを実行し、PNGをReadしてください。

ユーザーに確認するタイミング

あなたは作成者であり、ユーザーが決定します。インスタンス、ダッシュボードの目的と対象ユーザー、指標とディメンション、レイアウト（タブ、配置、グラフの種類）、フィルター（対象、デフォルト、連動）、不明確な場合の SQL と MBQL のどちらを使うか、複数の妥当な選択肢があるビジュアル上の選択について判断する際は、質問（AskUserQuestion）してください。Metabase で何かを作成または変更する前に（計画または project diff を提示してください）、実際の受信者に何かを送る前に（alert send、新しいサブスクリプション — 宛先を確認してください）、また予期しない問題が起きたときは必ず質問してください（問題を報告し、黙って再試行してはいけません）。

タスクの特定

モード	タイミング	ワークフロー
NEW	ダッシュボードを作成する	設計 → プロジェクトファイル → 検証／lint／テスト → push → ビジュアル確認
EDIT（プロジェクト）	プロジェクトフォルダーとして保持されているダッシュボードを変更する	pull → ファイルを編集 → diff → push → ビジュアル確認
EDIT（直接）	ファイルとして保持されていないダッシュボードを簡単に変更する	STUDY → カード／ダッシュカードのコマンドで変更 → ビジュアル確認
STUDY	ダッシュボードを理解する（説明、監査、変更計画）	概要 → レンダリング → カードごとの調査 → 上書きの監査
SHARE & SCHEDULE	誰かに PDF／PNG を送る、アラート、サブスクリプション	render／alert／subscription
EXPLORE / REORGANIZE	閲覧、検索、移動、名前変更	検出およびコレクションのコマンド
HISTORY	「誰が変更した？」「元に戻して」	history → 確認 → revert
USAGE-ANALYTICS	利用状況、古いコンテンツ、クエリのパフォーマンス（Pro／Enterprise）	アナリティクスモデルに対する MBQL
ADMIN	ユーザー、グループ、権限	権限のコマンド

すでにプロジェクトフォルダー（project.yaml と ids.json がある）を持つダッシュボードは、常にプロジェクト経由で編集します。Metabase で直接編集するとファイルが古くなります（push で差異について警告されます）。

リファレンスの読み込み戦略

モードを選択したら、作業を開始する前に、そのモードのバンドルに含まれるすべての仕様書を読んでください。後回しにすると、ペイロードの不具合につながります。

モード	仕様書（${CLAUDE_SKILL_DIR}/specs/…）
NEW / EDIT / STUDY	project-format.md、rendering.md、dashboard-api-spec.md、card-api-spec.md、visualization-cookbook.md、sql-style-guide.md、snippet-api-spec.md、discovery-api-spec.md
SHARE & SCHEDULE	rendering.md、notifications-api-spec.md
EXPLORE / REORGANIZE	discovery-api-spec.md、collection-api-spec.md、card-api-spec.md
単独の SQL／カード／スニペット	card-api-spec.md、sql-style-guide.md、snippet-api-spec.md、visualization-cookbook.md
USAGE-ANALYTICS	usage-analytics-spec.md
ADMIN	permissions-api-spec.md、permissions-guide.md

アセット（${CLAUDE_SKILL_DIR}/assets/templates/）：mockup-text-template.md、mockup-html-template.html、 design-doc.md — 必要な設計段階で読み込んでください。

仕様書	内容
project-format.md	プロジェクトフォルダーの形式、派生する内容、push／pull の動作、lint ルール
rendering.md	カード／ダッシュボードの画像と PDF の作成方法、オプション、出力、制限
notifications-api-spec.md	アラートとサブスクリプションの違い、本文、スケジュール、注意点
dashboard-api-spec.md	ダッシュボードの CRUD、レイアウト、パラメーター、マッピング先、PUT のルール
card-api-spec.md	カードの CRUD、MBQL、ネイティブ SQL、テンプレートタグ、v63 で返される内容
visualization-cookbook.md	各表示形式に必要な設定とサイズ、コピーして使用できる例
sql-style-guide.md	SQL の規約、サンプルデータベースの方言
snippet-api-spec.md / collection-api-spec.md / discovery-api-spec.md	スニペット／コレクション／メタデータと検索
permissions-api-spec.md / permissions-guide.md	ユーザー、グループ、権限グラフ／レシピと安全性
usage-analytics-spec.md	アナリティクスモデル、MBQL のパターン（Enterprise）

---

NEW ダッシュボードのワークフロー

始める前に

先にデザインする（カード、タブ、複雑なフィルターが5つ以上の場合に推奨）か、直接構築する（シンプルなリクエストの場合）かを確認します。 次にプロジェクトフォルダー（例：<repo>/dwh/metabase/<dashboard>/）を決めます。/tmpは使用しないでください。

フェーズ 1：デザイン — 定義 → モックアップ → 承認

各段階で明示的な承認を得てください。黙って段階を飛ばしてはいけません。

ステージ 1：要件。 ビジネス上の問い、対象者（経営幹部：タイルと傾向、アナリスト：テーブルとドリルダウン）、データ（databases、tables --database <id>）を確認します。次に以下を定義し、承認を得るために提示します。

指標	計算	表示形式	カード
総売上	SUM(total)	単一値	売上 KPI

ディメンション	ソース	使用先
月	orders.created_at（month）	売上推移

フィルター	種類	デフォルト	適用先
日付	date/all-options	past30days~	すべてのカード

ユーザーが確認するまで先に進まないでください。データモデルを誤ると、それを基に構築するものがすべて誤ってしまいます。

ステージ 2：段階的なモックアップ（各段階で承認を得ます）。

1. テキストモックアップ（assets/templates/mockup-text-template.md）→ <project>/design/mockup.md：24列グリッド上のタイル／チャート／テーブルの配置。
2. HTML モックアップ（assets/templates/mockup-html-template.html）→ ブラウザーで表示する <project>/design/mockup.html。
3. Metabase モックアップ：シンプルなサンプル SQL（SELECT 'Gadgets' AS "Category", 42000 AS "Revenue" または LIMIT 付きの実際のクエリ）でプロジェクトを作成し、project push を実行してから project render <dir> を実行し、PNG をユーザーに見せます。ユーザーは Metabase をクリックして操作しなくても、実際のレイアウト、フィルター、書式を確認できます。

ステージ 3：デザインドキュメント（assets/templates/design-doc.md）→ <project>/design/design-doc.md。

フェーズ 2：プロジェクトファイル

project new <dir> --name "Store Analytics" --database 3 --collection 17

次に作成します（形式：specs/project-format.md）。

1. snippets/<name>.sql — データソースごとに1つ、データを供給するスニペットを作成します。結合、フィルター（[[AND {{date}}]]）、時間のグループ化（Postgres/Redshift では {{time_perspective}} :: DATE AS period、SQLite では DATE({{time_perspective}})）を記述します。カード側で次のようにラップします：WITH base AS ({{snippet: name}}) SELECT …。SQL コメントに {{…}} を入れてはいけません（Metabase が展開します）。
2. filters.yaml — スニペットで使用するテンプレートタグを記述します。フィールドフィルター（type: dimension、dimension: [field, {base-type: type/Date}, <field id>]、alias: table_alias.column、widget-type）と temporal-unit タグを含めます。共通タグはここに一度だけ記述します。例は specs/project-format.md にあります。
3. cards/<key>.sql + cards/<key>.yaml — カードごとに1組作成します。SQL は specs/sql-style-guide.md に従います。.yaml には名前、説明、表示形式、チャート設定を記述します。チャートカードでは必ず graph.dimensions と graph.metrics を設定します（日付の場合は graph.x_axis.scale: timeseries も設定してください）。visualization-cookbook.md 冒頭の表を参照してください。
4. dashboard.yaml — フィルター（parameters）、タブ、at: [col, row, width, height] で指定する配置、タイルごとの viz 上書き、およびタグを持つすべてのカードに対するフィルター接続 filters: {p_date: date} を記述します。

SQL と MBQL：レビュー、バージョン管理、再利用の対象となるもの（CTE、ウィンドウ関数、独自の日付ロジック、スニペット）にはネイティブ SQL を優先します。シンプルな集計や再利用可能な指標には MBQL を使用します。構造化クエスチョンもプロジェクトで動作し、その query: はそのまま保持されます。

パラメーター付き SQL — 2つの異なる仕組み：

• 基本変数（text、number、date）：そのまま置換されるため、演算子は自分で記述します — WHERE status = {{status}}。省略可能な場合は [[AND category = {{category}}]] のようにします。
• フィールドフィルター（dimension）：Metabase が条件を記述します — WHERE {{date_range}} [[AND {{category}}]]。WHERE col = {{tag}} と書いてはいけません（事前チェックで拒否されます）。テーブルエイリアスを使う場合、alias は alias.column にする必要があります。

フェーズ 3：確認、公開、表示

project validate <dir>           # must be clean
project lint <dir>               # fix, or record deliberate choices under lint.ignore in project.yaml
project test <dir>               # every card runs with the default filters, and chart settings are checked
                                 # against the columns each query really returns — must be all ok
project diff <dir>               # show the user what will be created
project push <dir>               # after the user approves
project lint <dir>               # again: column-based rules (number formats, …) only run once cards exist in Metabase

次にビジュアルチェック（以下を参照）を実行します。これは必須です。設定が誤っていても、Metabase は妥当なチャートを描画することがあります（別の列にフォールバックするため）。そのため、見栄えのよい画像が表示されても、project test が問題なく完了することの代わりにはなりません。

フェーズ 4：テストして引き渡す

1. project test <dir> --images — すべてのカードが実行され、<dir>/.mbsync/render/ にカードごと、タブごとの PNG が生成されていることを確認します。
2. 重要な数値を 2～3 個、既知の値または直接実行した SQL と照合します。
3. フィルター：別の値でレンダリングし（dashboard render <id> --params '{"category": "Gizmo"}'）、カードの表示が変わることを確認します。
4. エッジケース：結果が空の場合、null、空のフィルターを確認します。
5. project render <dir> --pdf で最終結果を表示して Metabase を開かずに確認できるようにし、プロジェクトフォルダーをコミットして引き渡します。

---

ビジュアルチェック（カードまたはレイアウトを変更した後）

Metabase は、間違ったチャートでも問題なく保存します。実際に確認しましょう。

1. カードを作成または変更した後： ダッシュボード上のカードの場合は dashcard image <dashboard-id> <tile title>（閲覧者に表示される内容：タイル独自のタイトル、表示値と書式、ダッシュボードのデフォルトフィルター。カードが 3 か所に配置されている場合は、3 回確認します）。単独の質問の場合は card image <id> を使います。PNG を読み込み、次を確認します。
   • チャートの種類が質問に適しており、軸に意図した列が使われている
   • ラベルが読みやすく重なっていない。並び順が適切
   • 数値の書式（通貨、%、小数点以下の桁数。「44,383.9」のような表示がないこと）。色がダッシュボード内で統一されている
   • 空でなく、エラーがない（JSON の error フィールド）。タイトルと説明が設定されている
2. 修正して再レンダリングします — カードごとに最大 3 回までです。それ以降は画像をユーザーに見せて確認を求めます。
3. レイアウトを変更した後： dashboard render <id>（または project render <dir>）を実行し、各タブの PNG を読み込みます。次を確認します。
   • 行が 24 列に収まり、KPI タイルが整列して一目で分かる
   • 見出しでセクションが分かれており、チャートが窮屈でない
   • フィルターバーにすべてのフィルターがあり、読み進める順序が自然
   • すべてのタブで、JSON の card_errors が空
4. 引き渡し時に --pdf でレンダリングしたものを添付します。

レンダリングに表示されるのは、Metabase の現在の状態です。プロジェクトの変更を先にプッシュしてください。

---

STUDY ワークフロー

ダッシュボードを理解したと判断する前に、これを実行してください。JSON だけを読むと、異なる設定でカードが複数回配置されたダッシュボードを誤って説明してしまうことがよくあります。

1. 概要 — dashboard <id>：collection_authority_level（official = キュレーション済み）、card_count と unique_card_count、repeated_card_ids、配置ごとの overrides（タイトル、scalar_field、graph_metrics など）。
2. 実際に見る — dashboard render <id> を実行し、各タブの PNG をすべて読み込みます。これはスクリーンショットを求める代わりになります。レンダリングに失敗した場合に限り、スクリーンショットを求めてください。壊れたカードは card_errors に一覧表示されます。
3. 一意のカードごと — card <id>（結果列、スニペット、テンプレートタグ）。SQL の場合に限り --full --out を使います。
4. 繰り返し配置されている項目ごと — dashcard <dashboard-id> <index|name> で完全な設定を確認します。
5. 共有スニペット — 参照されているスニペットごとに snippet <id> を実行します。
6. 生成列と表示列 — result_columns と各配置の scalar_field / graph_metrics を比較します。
7. パラメーター — 種類、デフォルト値、各パラメーターが対応するタグ／フィールドを確認します。
8. データ形状 — 最も複雑なカードに対して card query <id> [--out <file>] を実行します。

（ダッシュボードがプロジェクトフォルダーの場合は、project pull を実行してから dashboard.yaml を読むと、手順 1、4、7 を確認できます。）

---

EDIT ワークフロー

プロジェクトフォルダーとして管理するダッシュボード

project pull <dir>               # bring in anything changed in Metabase (refuses to overwrite local edits)
# edit the YAML / SQL
project validate <dir> && project lint <dir>
project test <dir> --card <key>  # the cards you touched
project diff <dir>               # show the user
project push <dir>               # then the visual check

• ファイルが信頼できる唯一の情報源です。 誰かが Metabase の UI で変更しましたか？ project pull を実行してコミットします（ids.json も含めます。これは各項目の同期時点を記録するもので、ドリフトチェックはこれと比較します）。
• プッシュ時にドリフト（「これらのファイルを最後に同期してから Metabase で変更されています」）が報告されたら、作業を止めて確認してください。Metabase の変更を保持する（別の場所に編集内容を保存した後、pull --force を実行する）か、上書きする（push --yes）かを尋ねます。
• カードをアーカイブせずに管理対象から外すには、cards/ と ids.json の両方から削除します。

ファイルとして保持されないダッシュボード

1. まず STUDY を実行します。配置ごとの上書き設定を把握でき、上書きしてしまうのを防げます。
2. 正しい情報源はライブカードであり、リポジトリ内の .sql ファイルではありません。card <id> --full --out から始めます。
3. レイアウト：1 つの配置には dashcard update <dash> <index|name> --patch f.json を使います。大きな変更には dashboard <id> --layout --out f.json を実行し、編集してから dashboard put <id> --from f.json を実行します。
4. カードのクエリ／設定：card update <id> --patch f.json（保存前に検証されます）。
5. 表示を確認します。
6. プロジェクト化を提案します：project pull <dir> --dashboard <id>（Metabase では何も行われません。ファイル、差分、 git の履歴が得られます）。

「全体の仕組みを理解する」ために、リポジトリの古いビルド／デプロイスクリプトを読まないでください。CLI で十分です。ライブペイロードからはわからない規約（フィールド ID のレジストリなど）を確認する場合や、変更を依頼された場合に限り、スクリプトを読んでください。

---

共有とスケジュール設定

• 画像や PDF を共有する場合： dashboard render <id> --server --out <dir>/name.pdf（Metabase 独自の印刷レイアウト、A4／レターサイズ、有効なフィルターを一覧表示します。共有に最適です）、dashboard render <id> --out name.pdf （ライブ UI のスクリーンショットをタブごとに 1 ページに表示します）、または card image <id> --out name.png を使います。フィルター値には --params を使います（ダッシュボードではフィルタースラッグ、カードではタグ名）。
• アラート（条件に基づく 1 枚のカード）：specs/notifications-api-spec.md に従って本文を作成し、受信者を確認してから alert create --from f.json を実行します。goal_above/below を使うには、カードに目標線が必要です。そうでない場合は、 has_result で条件を表現できるようカードを構成します。alert send の前に、自分だけを受信者としてリハーサルしてください。
• サブスクリプション（スケジュールに従うダッシュボード）：subscription create --from f.json を実行します。すべてのカードを含めるには、cards を省略します。プロジェクトでは、dashboard.yaml の subscriptions: の下に追加して push します。
• メール／Slack が設定されていない場合は、どちらも警告します。管理者による設定が必要だとユーザーに伝えてください。配信先がないまま通知を作成しないでください。スケジュールはインスタンスのレポート用タイムゾーンで報告します（作成時に表示されます）。

履歴

card history <id> ／ dashboard history <id> で、リビジョン（誰が、いつ、何を変更したか）を一覧表示します。対象をユーザーに確認してから、 card revert <id> --to <revision-id> を実行します。プロジェクトフォルダーの場合は、その後 project pull を実行します。

EXPLORE ワークフロー

1. databases → tables --database <id> → collections --tree（★ = 公式）→ collection-items <id> → search <query> → card <id> ／ dashboard <id>。
2. 公式コレクション（authority_level: "official"）にはメダルバッジが表示されます。公式に昇格するには Pro／Enterprise が必要です。

ショートカット：意図が明確な場合（「地域別の第 3 四半期の売上を表示して」など）は、探索を省略して SQL に進みます。

使用状況分析ワークフロー（Pro／Enterprise）

利用状況、古いコンテンツ、クエリのパフォーマンス、各コンテンツの利用者を調べます。無料エディションでは早い段階で拒否されます。

1. usage-analytics — モデルとそれぞれのカード ID を表示します（ID はインスタンスごとに異なるため、ハードコードしないでください）。
2. 質問に答えられる場合は、組み込みの分析ダッシュボード 8 種類を優先します。
3. それ以外の場合は MBQL を使います（監査データベースではネイティブ SQL はブロックされています）。クエリをファイルに書き込み、 usage-analytics query --from <file> を実行します。閲覧には usage-analytics query --card <id> --limit N を使います。

ルール：View／Query／Activity ログには必ず日付フィルターを適用します（7～30 日）。query_source は人間による操作（dashboard、ad-hoc、 question、collection）と自動処理（pulse、dashboard-subscription、cache-refresh）を区別します。SQL と MBQL の件数を比較するには、Content モデルの question_is_native を使います。「External User」は埋め込みビューを意味します。

防御的ガードレール

• すべての SQL クエリでは集計するか、LIMIT を指定してください。 大きなテーブルに対する無制限の SELECT * は避けてください。クエリに 2 分以上かかる場合は、ソートキーに対する日付フィルターの不足、事前集計、またはマテリアライズドビューが原因の可能性があります。
• 公開前に SQL をテストしてください（project test、card query、またはプロジェクトで使用しているデータベーススキルを使います）。
• 削除はアーカイブを意味します。 card delete／dashboard delete はアーカイブします（restore で復元できます）。--permanent --yes は、ユーザーが完全削除を求めた場合にのみ使用してください。コレクションとスニペットはアーカイブのみ可能です。
• 事前チェックには理由があります。 報告された内容を修正してください。チェックが誤っていると確信できる場合に限り --skip-validate を使用し、その旨を伝えてください。
• 配信物は実際の人に届きます。 アラートやサブスクリプションを作成したり、alert send を実行したりする前に、宛先を確認してください。

よくある落とし穴

Metabase v63 のペイロード（v0.63.18 で検証済み）：

• テンプレートタグは、マップとして記述されていても配列として返されます（[{name: …}]）。どちらの形式も読み取れるようにしてください。
• 保存されたフィールド参照にはランダムな lib/uuid スタンプが含まれ、構造化クエリには読み取るたびに新しい lib/uuid が付与されます。これは変更ではありません。（Project の diff／pull ではすでに無視されます。）
• ネイティブカードの parameters は [] のままにしてください。設定するのは静的リストのドロップダウンの場合のみです。
• v63 の Sample Database は SQLite です（以前は H2）。DATE_TRUNC は使えません。代わりに strftime('%Y-%m-01', col) を使用してください。databases でエンジンを確認してください。Metabase はこのような月の列を数値として扱います。graph.dimensions に含め、graph.x_axis.scale: timeseries を設定してください。

プロジェクト（コードとしての設定）：

• pull と push のたびに ids.json をコミットしてください。その updated_at 値によって、Metabase の UI で行った変更がチームメイトの push に上書きされないよう保護されます。記録されたタイムスタンプがないフォルダーでは、各アイテムについて push のたびに警告が表示されます。
• スニペットごとに所有者は 1 つにしてください。 2 つのプロジェクトのカードが同じスニペットを使う場合、両方の pull がそれを書き込み、最後の push が優先されます。スニペットは 1 つのプロジェクトに置き、他のプロジェクトでは external_snippets に記載してください。
• 1 つのコレクションにつき、--loose-cards を使うプロジェクトは 1 つだけにしてください。複数のプロジェクトで使わないでください。
• 個人用コレクションを共有リポジトリに pull しないでください。
• ファイルとして編集するものには、スニペットを使ったネイティブ SQL カードを推奨します。構造化（MBQL）質問は正確に往復変換できますが、手動での編集には適していません。

ダッシュボード PUT とレイアウト：

• tabs は dashcards と併せて指定する必要があります。各ダッシュカードには card_id が必要です（仮想カードの場合は null）。負の ID は新しいタブ／配置の作成に使われます。省略された配置は削除されます。
• レイアウトを再作成すると配置 ID が変わり、サブスクリプションはその ID を参照します。project push は既存の ID を再利用します。手書きのレイアウトでも同様にしてください（まず最新の状態を GET します）。
• 24 列のグリッドでは、全幅は size_x: 24 です。col + size_x ≤ 24 を維持してください。Metabase は送信されたとおりに重複を保存します。
• 配置の visualization_settings は、その配置に限りカードの設定を上書きします。配置の column_settings は、カードの column_settings 全体を置き換えます。

ダッシュボード概要の解釈：

• card_count は配置数、unique_card_count は重複を除いたカード数です。repeated_card_ids は複数回配置されているカードを示します。ほとんどの場合、タイトル／指標は異なります。ダッシュボードを説明する前に、それぞれで dashcard を実行してください。
• overrides は厳選された項目のサブセットです（title、scalar_field、graph_metrics、graph_dimensions、series_titles）。複合ビジュアライゼーションでは設定は visualization.settings の COLUMN_N という名前で格納されます。概要ではそれらが解決されています。 フィルターの接続：
• フィルターが機能するのは、マッピングされている場所だけです。ネイティブ SQL カードでは、マッピングが機能する前にテンプレートタグを定義する必要があります。
• 対象：フィールドフィルター／時間グルーピング ["dimension", ["template-tag", t], {"stage-number": 0}]、通常の変数は 正確に ["variable", ["template-tag", t]]（3 つ目の項目は拒否されます）、テキストカードは ["text-tag", t]。
• マッピング内のフィールド参照には、null ではなく {"base-type": "type/Text"} のようなオプションが必要です。
• スニペット内でのみ使用されるタグも、スニペットを使うすべてのカードで宣言する必要があります（プロジェクトがこれを自動で行います）。 また、ネストされたスニペットはすべて、カード上でスニペットタグとして宣言する必要があります。
• フィールドフィルターは派生列（CASE、計算されたバケット）を対象にできません。静的リストの ダッシュボードフィルターと基本的な text 変数を使用してください。
• 相対日付のデフォルト：past7days は今日を含みません。past7days~ は今日を含みます。
• 静的リストの string/= フィルターをドロップダウンとして表示するには、"values_query_type": "list" が必要です。
• テキストカードではフィルター値を表示できます：テキスト内に {{d}} を置き、対象を ["text-tag", "d"]、 card_id: null とするマッピングを設定します。

表示タイプ：

• pivot は構造化クエリ専用です。ネイティブ SQL の場合は display: "table" と "table.pivot": true、table.pivot_column、 table.cell_column を使用します。ピボットは pivot build で作成してください（MBQL を手書きしないでください）。ピボットカードでの card query は ユーザーに表示されるグリッドを返し、エクスポートはデフォルトでピボット形式になります（行形式にするには --flat を指定します）。詳細はクックブックの「Pivot Table」を参照してください。
• visualization_settings: {} のチャートカードは作成しないでください。graph.dimensions、graph.metrics、日付の場合は graph.x_axis.scale: timeseries を設定します。スカラーとテーブルは空の状態から作成できます。
• 見出し：プレーンテキスト。テキストカード：Markdown。見出しのレシピ：{"dashcard.background": false, "virtual_card": {"name": null, "display": "heading", "visualization_settings": {}, "archived": false}, "text": "Section"}。

SQL：

• ネイティブカードでは pMBQL のみ使用します：{"lib/type": "mbql/query", "database": <id>, "stages": [{"lib/type": "mbql.stage/native", "native": "<SQL>", "template-tags": {...}}]} — レガシー形式ではデータベースが通知なく削除されます。
• SQL は dataset_query.stages[0].native から、タグは stages[0].template-tags から読み取ります。
• 列のエイリアスには人が読みやすい名前を付け、引用符で囲みます：AS "Revenue"。最初から specs/sql-style-guide.md に従ってください。
• SQL コメント内に {{snippet: x}} を記述しないでください。Metabase はコメント内でも展開します。

サインインとエディション：

• ブラウザーでのサインインには v63 以降と、Admin > AI > MCP から利用できるアプリ登録スイッチが必要です。
• Chrome でのレンダリングには Chrome と Node 22 以降が必要です。--server の PDF にはどちらも必要ありません。どちらも現在の Metabase の状態を表示します。v63 では単一カード向けのサーバーサイド PNG はありません（ダウンロードメニューの PNG はブラウザーで描画されます）。
• Pro／Enterprise 専用コマンドは、無料エディションでは明確なメッセージとともに拒否されます（試すには --skip-preflight を指定してください）。

CLI： --patch ／ --from に指定できるのはファイルパスのみです。バッチ更新では、最初にすべてのパッチファイルを書き、その後ループ処理してください。

プロンプト例

「ストアのパフォーマンスダッシュボードを作成してください。週ごとのインストール数、コンバージョン率、評価を KPI として、トレンドライン、国別の内訳、日付と国のフィルターを表示してください。」

NEW → design（指標／ディメンション／フィルター → テキスト → HTML モックアップ）→ project new → スニペット、filters.yaml、カード、dashboard.yaml → validate / lint / test → diff → push → ビジュアルチェック（カード画像、ダッシュボードのレンダリング）→ test --images → PDF で引き渡し。

「ダッシュボード 134 の表示を確認してください。何か問題はありますか？」

STUDY ステップ 2：dashboard render 134 → 各タブを読み取り → レイアウトと card_errors を報告します。

「ダッシュボード 22 の日付フィルターが Revenue by State カードに反映されません。」

プロジェクトフォルダーがある場合：project pull を実行し、その配置の filters: とカードのタグを確認して修正し、diff、push、render を行います。 ない場合：dashcard 22 "Revenue by State" を実行し、タグがない場合はカードに追加し（card update）、dashcard update で接続してから、dashboard render 22 --params '{"date": "past30days~"}' で確認します。

「ストアのダッシュボードを PDF で送ってください。」— dashboard render 134 --out <dir>/store-analytics.pdf。

「エグゼクティブダッシュボードを毎週月曜日の 8 時に経営陣のメーリングリストへメールしてください。」— メールアドレスを確認 → サブスクリプション（weekly、mon、8）→ タイムゾーンを報告します。プロジェクト内では、subscriptions: の下に追加して push します。

「昨日のサインアップ数が 50 件を下回ったら知らせてください。」— サインアップ数が 50 未満の場合にのみ行を返すカードを作成 → has_result を使ったアラート、毎日の cron。

「先週、誰がカード 402 を変更しましたか？元に戻してください。」— card history 402 → リビジョンを確認 → card revert。

「Commercial コレクションを整理してください。」— REORGANIZE：collections --tree、collection-items を実行して構成を提案し、collection create を実行してから、collection_id を指定した card update／dashboard update でアイテムを移動します。

「サインインしていますか？バージョンはいくつですか？」— status。