data-metabase

Metabase の自動化

従来の Metabase REST API は、カード、ダッシュボード、コレクション、権限、スキーマの更新を管理します。バージョン管理された Agent API は、ヘッドレスのセマンティック BI アシスタントとアプリ側の AI ワークフロー向けのインターフェイスです。公式 MCP サーバー（v60 で追加）と @metabase/cli（v62 で追加）は、AI クライアントとターミナルでのスクリプト実行に対応します。各機能が追加されたリリースについては、references/metabase-59-surface.md を参照してください。バージョン固有の挙動について記載する前に、GET /api/session/properties の version でユーザーのバージョンを確認し、metabase.com/releases で現在の安定版の系統を確認し、/docs/latest で挙動を確認してください。

クイックリファレンス

タスク	パス	使用する場面
質問とダッシュボードの作成・更新	クラシック REST API + scripts/metabase_api.py	標準的なコンテンツの自動化と段階的なアップサート
環境間でコンテンツを昇格	Remote Sync またはシリアル化	Git に基づく昇格、レビュー可能な差分、環境間の移行
埋め込み型の顧客向け分析機能の構築	埋め込み + テナント + 埋め込み権限	マルチテナントアプリ、顧客ポータル、行レベルの分離
AI 分析アプリの構築	Agent API	バージョン管理されたセマンティックなアプリ側 AI クエリ
Metabase と AI コーディングエージェントの統合	MCP サーバー（v60 以降）	Claude、Cursor、VS Code — 会話を通じた質問やダッシュボードの生成
グループごとの AI アクセスの管理	Metabot AI governance（v61 以降、Pro/Enterprise）	グループ単位の制御、トークン制限、使用状況の分析
スキーマメタデータの更新	データベースの同期／再スキャンエンドポイント	新しいテーブル、変更されたカラム、古いフィールド値
ネイティブ SQL の質問の調整	エクスポート優先 + ネイティブクエリのパターン	リクエスト形式を推測せずに安定した自動化を実現

判断ツリー

Need to create or edit saved Metabase content?
  -> Use classic REST API (`card`, `dashboard`, `collection`).

Need repeatable dev -> prod promotion with reviewable diffs?
  -> Prefer Remote Sync or serialization before raw REST upserts.

Need embedded analytics for many customers or workspaces?
  -> Use embedding + tenants + embedding permissions.

Need an AI assistant to discover metrics/tables and construct queries?
  -> Use the versioned Agent API, not raw card CRUD.

Need to generate or edit questions/dashboards from an AI coding agent or terminal?
  -> Use the official Metabase MCP server (v60+, connects Claude/Cursor/VS Code).

クイックスタート

入力（環境変数）

• METABASE_URL（例：https://metabase.example.com）
• 推奨：METABASE_API_KEY
• 任意：METABASE_SESSION
• フォールバック：METABASE_USERNAME + METABASE_PASSWORD

動作確認

python3 skills/universal/data-metabase/scripts/metabase_api.py health
python3 skills/universal/data-metabase/scripts/metabase_api.py whoami
python3 skills/universal/data-metabase/scripts/metabase_api.py list-databases
python3 skills/universal/data-metabase/scripts/metabase_api.py list-collections --tree

ライブ API ドキュメント

Metabase インスタンスでは、/api/docs に OpenAPI ドキュメントが用意されています（例：https://metabase.example.com/api/docs）。一括編集のスクリプトを作成する前に、このドキュメントで実際のビルドにおけるリクエスト形式を確認してください。

ワークフロー

1. API が利用可能であることを確認します（GET /api/util/health）。
2. まず API キーで認証し、必要な場合に限りセッション認証に切り替えます。
3. 環境間で ID をハードコードせず、検出します：
   • 保存先の collection_id
   • dataset_query の database ID
   • MBQL を使用する場合のテーブル ID とフィールド ID
4. 適切なインターフェイスを選択します：
   • カード／ダッシュボード／管理機能にはクラシック REST API
   • セマンティックな AI 主導のクエリには Agent API
   • 昇格ワークフローには Remote Sync またはシリアル化
5. カードを作成・更新します：
   • 安定した自動化にはネイティブ SQL を優先します
   • display と visualization_settings を明示的に設定します
6. ダッシュボードを作成・更新してから、明示的なレイアウトでカードを配置します。
7. スキーマが変更された場合はメタデータを更新します。
8. 結果を実行・エクスポートし、エクスポートした JSON を開き直して検証します。

変更と昇格のゲート

Metabase のコンテンツ変更は、小規模なマイグレーションとして扱ってください。特に、ダッシュボードのフィルターや権限が関わる場合は注意が必要です。

1. 診断のため、現在のカード／ダッシュボードの JSON をエクスポートし、安定したエンティティ ID または環境固有の検索キーを記録します。その読み取りレスポンスを復元用アーティファクトとは呼ばないでください。
2. ターゲット環境内のすべてのデータベース、コレクション、テーブル、フィールド、グループを解決します。数値 ID を位置によって変換しないでください。
3. 目的のペイロードと変更内容の一覧（create、update、archive、権限変更）を作成します。各操作について、サポートされている逆操作、書き込み可能な正確なフィールド、ターゲット識別子、依存関係を記録します。権限、アーカイブ状態、カード、ダッシュボード、ダッシュカードのレイアウト、フィルターマッピングをそれぞれ個別に一覧化します。
4. 依存関係の順序に従って適用します。コレクションと権限 -> カード -> ダッシュボード -> ダッシュカードのレイアウト／フィルターマッピング。
5. 結果を再エクスポートし、セマンティックなフィールド、レイアウト、権限、クエリ出力を目的のペイロードと比較します。
6. 本番環境で変更を加える前に、ステージング環境または使い捨てのコレクションで、選択した復元方法をリハーサルします。JSON の読み取りレスポンスは証拠にはなりますが、自動的に再生可能な書き込みペイロードになるわけではありません。
7. 検証に失敗した場合は、それ以降の変更を中止し、実証済みの方法だけを実行します。エンドポイント固有の逆書き込み、対象エンティティを含む Serialization のエクスポート／インポート、または自己完結型の同期済みコンテンツに対する Remote Sync のリビジョンです。先に製品とライセンスのサポート状況、および対象範囲を確認してください。Serialization と Remote Sync ではユーザー、グループ、権限は対象外であり、Remote Sync ではテーブルメタデータ、アラート、サブスクリプションも対象外です。対象外の状態は、それぞれを管理する API またはドキュメントに記載された管理ワークフローで復元します。その後、再エクスポートしてクエリを再実行し、復旧したことを確認します。

アップサートが冪等になるのは、その検索キーがその環境で一意かつ安定している場合に限られます。候補が 2 つ一致した場合は処理を中止し、最初の結果を更新するのではなく、曖昧さを提示してください。

主な概念

• UI の「Question」 == API の card
• チャートの設定は、カードの display + visualization_settings に保存されます
• ほとんどのビジュアライゼーションキーは、既存のカード JSON をエクスポートしてからペイロードを編集するのが最も簡単に管理できます
• Remote Sync は Git ベースの昇格に使用するもので、リクエストごとのランタイム自動化用ではありません
• Agent API は、セマンティックなクエリ構築と実行のための、独立したバージョン管理対象の API です。レスポンスごとの行数に上限があるため（上限は Agent API のドキュメントで確認してください）、continuation_token によるページネーションを必ず処理してください
• MCP サーバー（v60 以降）は、認証済みユーザーと同じ権限で Metabase を Claude、Cursor、VS Code、およびその他の MCP クライアントに接続し、AI ターミナルからのダッシュボードのコード管理を可能にします。v62 では、SQL の実行、コレクションの作成、AI クライアント内でレンダリングされるインタラクティブなチャートが追加されます
• Metabase 公式 CLI（npm install -g @metabase/cli。API キーとブラウザーログインで最小 Metabase バージョンが異なるため、CLI の README で確認してください。従来の REST／JAR 管理用インターフェースとは別のものです）は、ターミナルから質問、ダッシュボード、ドキュメント、トランスフォームを作成します。詳しくは references/metabase-cli.md を参照してください
• Metabot（v60 以降、オープンソース）は Slack と連携します。v61 では、グループごとのアクセス制御、トークン上限、使用状況分析が追加されます（ガバナンス機能は Pro／Enterprise のみ）
• モジュラー埋め込み SDK は有料プランの機能です。アプリの足場作りやアップグレードの前に、/docs/latest/embedding で React、Node、Metabase／SDK のバージョンの組み合わせに関する要件を確認してください。互換性の境界に注意してください。SDK 1.54.x 以下では従来の認証 API（authProviderUri、バックエンドは { id } を返します）が使われます。それ以降のバージョンでは authProviderUri がなくなり、バックエンドは { jwt } を返します
• カスタムビジュアライゼーション（v62 以降、有料プラン）では、プラグイン SDK を通じて React ベースのチャートタイプを構築できます。特定の画面で表示できるかどうかをドキュメントで確認してください（リリース時点では、埋め込み、サブスクリプション、アラートでは表示できません）。対応していない画面での利用を約束しないでください

プランと料金

プランの階層は、多くの設計に影響します。SSO、行と列のセキュリティ（サンドボックス化）、モジュール式の埋め込み SDK、カスタム可視化、Metabot／AI ガバナンスは、有料プランの機能であり、オープンソースでは利用できません。プラン名や、各プランに含まれる機能は変わるため、それを前提に設計する前に、metabase.com/pricing の比較ページで機能を確認してください。

価格を記憶に頼って引用しないでください。提案に費用を記載する前に、metabase.com/pricing を確認し、各プランの基本料金と含まれるユーザー数、ユーザーごとの料金、表示価格が年払いか月払いか（異なります）、ホスト型 AI のトークン料金と独自のプロバイダーキーを使う場合の違い、トランスフォームの利用枠と実行ごとの料金を記録してください。

ガードレール

• 一括で環境間の昇格を行う場合は Remote Sync または Metabase serialization を優先し、段階的なアップサートには直接 API を使用してください。
• 検出またはエンティティ ID／同期済みコンテンツの使用が可能な場合は、環境間で数値 ID をハードコードしないでください。
• METABASE_API_KEY、パスワード、セッショントークンを絶対にコミットしないでください。
• 専用の最小権限の自動化アカウントとコレクションを優先してください。
• 内部管理者向け通知エンドポイントは、通常の自動化とは分けて扱ってください。これらでは、ユーザー向けの METABASE_API_KEY ではなく、サーバー側の MB_API_KEY を使用します。
• ダッシュボードでタブ、フィルター、または複雑な dashcard の状態を使用している場合は、まずエクスポートし、記憶を頼りに再構築するのではなく、その構造を保持してください。

ナビゲーション

トピック	ファイル	読み込むタイミング
認証（API キー＋フォールバック）	references/api-auth.md	API 自動化タスク全般
レポート（カード）：作成／編集パターン	references/reports-cards.md	保存済みの質問を作成または更新するとき
ダッシュボードとカードの配置	references/dashboards.md	ダッシュボードを構築または複製するとき
チャートと visualization_settings	references/charts-settings.md	チャート表示または軸の設定を構成するとき
セマンティック BI 向けエージェント API	references/agent-api.md	AI 分析アプリまたはヘッドレス BI ワークフローを構築するとき
埋め込みと統合	references/embedding-integration.md	公開リンク、署名付き JWT、または SDK による埋め込み
テナント、埋め込み権限、ルーティング	references/tenants-routing.md	マルチテナントアプリまたはカスタマーポータルを分離するとき
権限とコレクション	references/permissions-collections.md	グループ設定、サンドボックス化、またはコレクション階層
ネイティブ SQL クエリパターン	references/native-query-patterns.md	SQL カードでテンプレートタグ、フィールドフィルター、キャッシュを扱うとき
Remote Sync と昇格ワークフロー	references/remote-sync.md	Git によるコンテンツの昇格、または環境間の移動
サーフェスマップとリリースアンカー	references/metabase-59-surface.md	リクエストがどの API レイヤーに該当するか、または機能がどのリリースで追加されたかを確認するとき
CLI：mb API クライアントと JAR 管理コマンド	references/metabase-cli.md	mb によるコンテンツのスクリプト化、またはサーバー管理（移行、dump-to-h2、シリアル化）

アセット

テンプレート	ファイル
カード仕様のひな形	assets/card-spec.template.json
ダッシュボード仕様のひな形	assets/dashboard-spec.template.json
Dashcard レイアウトのひな形	assets/dashcards-layout.template.json
埋め込み JWT の例	assets/embed-jwt-example.md

スクリプト

scripts/metabase_api.py は、認証、検出、コンテンツの CRUD、ダッシュボードのレイアウト作業、クエリ実行、スキーマ更新を行う、依存関係のないヘルパーです。ダッシュボードの配置を書き込むには、明示的な配列と一意のゼロ以外の整数 ID が必要です。不正な形式で取得されたリストがある場合、指定されていない配置が削除されるため、書き込みは停止します。このスキルディレクトリから python3 -m pytest scripts/test_metabase_api.py を実行して、オフラインで回帰テストを行ってください。

例：

# Print authenticated user (tries API key, then session)
python3 skills/universal/data-metabase/scripts/metabase_api.py whoami

# Discover IDs before scripting
python3 skills/universal/data-metabase/scripts/metabase_api.py list-collections --tree
python3 skills/universal/data-metabase/scripts/metabase_api.py list-databases
python3 skills/universal/data-metabase/scripts/metabase_api.py database-metadata --id 2
python3 skills/universal/data-metabase/scripts/metabase_api.py list-fields --database-id 2

# Export an existing card JSON (use as a template for visualization_settings)
python3 skills/universal/data-metabase/scripts/metabase_api.py export-card --id 123 --out card.json

# Export an existing dashboard JSON (use as a template for layout)
python3 skills/universal/data-metabase/scripts/metabase_api.py export-dashboard --id 5 --out dashboard.json

# Create/update a card from a JSON spec (see references/reports-cards.md)
python3 skills/universal/data-metabase/scripts/metabase_api.py upsert-card --spec card-spec.json

# Create/update a dashboard from a JSON spec
python3 skills/universal/data-metabase/scripts/metabase_api.py upsert-dashboard --spec dashboard-spec.json

# Add or update dashboard layout
python3 skills/universal/data-metabase/scripts/metabase_api.py add-dashcard --dashboard-id 5 --spec dashcard.json
python3 skills/universal/data-metabase/scripts/metabase_api.py update-dashcards --dashboard-id 5 --spec dashcards-layout.json

# Execute a query spec or export a saved card result
python3 skills/universal/data-metabase/scripts/metabase_api.py run-query --spec dataset-query.json
python3 skills/universal/data-metabase/scripts/metabase_api.py export-card-query --id 123 --format csv --out report.csv

# Refresh metadata after schema changes
python3 skills/universal/data-metabase/scripts/metabase_api.py sync-schema --id 2
python3 skills/universal/data-metabase/scripts/metabase_api.py rescan-values --id 2

既知の落とし穴

• メトリクス、結合、ビジネス定義が dbt、SQLMesh、生 SQL カード内で依然として揺れているのに、Metabase を正本となるセマンティックレイヤーとして扱うこと。
• シリアライズや同期の戦略を定めないまま、環境間でカードを手動コピーし、参照、権限、ダッシュボードのフィルター連携を気づかないうちに壊すこと。
• フィルターの意味がわずかに異なるダッシュボード間で同じ質問を再利用し、プロダクトの変更に見える、隠れた KPI の不一致を生じさせること。
• 厳格なパラメーター契約、コレクション分離モデル、署名付き埋め込みの検証手順を設けずに、テナントのダッシュボードを埋め込むこと。
• すべての作成でネイティブ SQL カードを既定の方法にし、その結果、チーム間での発見性、リネージ、再利用性を失うこと。
• 安定したフィールドマッピングではなく、見た目の利便性を優先してダッシュボードフィルターを設計し、スキーマやモデルの変更後に連動フィルターが壊れること。

よくあるアンチパターン

• バージョン管理された質問、文書化されたメトリクス、再現可能なモデル定義ではなく、ダッシュボードのスクリーンショットや PDF エクスポートを意思決定の根拠にすること。
• 生の探索用カード、本番 KPI、運用監視を同じ画面に混在させた、巨大な「経営ダッシュボード」を構築すること。
• 所有者と昇格ルールを定めたキュレーション済み共有コレクションではなく、個人用コレクションを本番配布の経路として使うこと。
• マイグレーションや自動化のワークフローに、環境固有のテーブル名、URL、カード ID をハードコードすること。
• 埋め込みパラメーター、行レベルのソースモデル、または別個のコレクションを使えばより明確に分離できるのに、カードを複製するだけでマルチテナント対応を解決しようとすること。
• データウェアハウスのモデリングやメトリクスガバナンスの上流で修正すべき、未解決のソースモデルの問題を補うために Metabase を使うこと。

関連スキル

• セマンティックモデリング、メトリクス、BI 対応のデータウェアハウス設計については、../data-analytics-engineering/SKILL.md を参照してください。
• クエリのチューニングとデータベースのパフォーマンス改善については、../data-sql-optimization/SKILL.md を参照してください。
• アプリケーション連携とサービスレイヤーの実装については、../software-backend/SKILL.md を参照してください。
• Metabase へのアクセスを場当たり的なスクリプトではなくツールとしてラップする場合は、../agents-mcp/SKILL.md を参照してください。
• LLM を MCP 経由で利用するパターンカタログについては、../agents-mcp/references/mcp-for-dwh.md を参照してください（形状 A のマネージド BI 向け MCP は Metabase に直接適用できます）。強制レイヤー（読み取り専用ロール、クエリ予算、仮名化の境界、監査ログ）は、形状にかかわらず適用されます。

学びのループ

過去の決定や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、またはそれが利用可能な代替手段である場合に限り、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、記憶に残す価値のあるパターン、未然に防ぐべきミス、または意外だったドメイン知識に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付付きの箇条書きを 1 つ learnings.md に追記してください。SKILL.md 自体は変更しないでください。