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 编码 Agent	MCP 服务（v60+）	Claude、Cursor、VS Code——通过对话生成问题和仪表板
按组管理 AI 访问权限	Metabot AI 治理（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
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 或文档记录的管理员工作流恢复未涵盖的状态，然后重新导出并重新运行查询以证明恢复成功。

只有在查找键于该环境中唯一且稳定时，upsert 才是幂等的。如果有两个候选项匹配，请停止并指出歧义，而不是更新第一个结果。

核心概念

• UI 中的 “Question” == API card
• 图表配置位于卡片的 display + visualization_settings 中
• 大多数可视化键最容易通过导出现有卡片 JSON，然后编辑该载荷来管理
• Remote Sync 用于基于 Git 的晋级，而不是按请求执行的运行时自动化
• Agent API 是用于构建和执行语义查询的独立版本化接口；它会限制每个响应的行数（请从 Agent API 文档中读取上限），因此务必处理 continuation_token 分页
• MCP 服务（v60+）以经过身份验证的用户所拥有的相同权限，将 Metabase 连接到 Claude、Cursor、VS Code 和其他 MCP 客户端；可在 AI 终端中实现仪表板即代码；v62 增加了 SQL 执行、集合创建，以及在 AI 客户端本身中渲染的交互式图表
• 官方 Metabase CLI（npm install -g @metabase/cli；请查看 CLI README，了解最低 Metabase 版本要求，该要求因 API 密钥登录和浏览器登录而异；它不同于经典 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 令牌费率与自带服务商密钥的区别，以及 transforms 的额度和单次运行价格。

防护措施

• 批量跨环境推广时，优先使用 Remote Sync 或 Metabase 序列化；增量 upsert 则使用直接 API。
• 如果可以查询 ID 或使用实体 ID／同步内容，就不要在不同环境之间硬编码数字 ID。
• 切勿提交 METABASE_API_KEY、密码或会话令牌。
• 优先使用专用且权限最小化的自动化账户和集合。
• 将内部管理员通知端点与常规自动化分开处理。它们使用服务端的 MB_API_KEY，而非面向用户的 METABASE_API_KEY。
• 如果仪表板使用标签页、筛选器或复杂的 dashcard 状态，请先导出并保留其结构，不要凭记忆重建。

导航

主题	文件	何时加载
身份验证（API 密钥 + 备用方式）	references/api-auth.md	执行任何 API 自动化任务时
报表（卡片）：创建／编辑模式	references/reports-cards.md	创建或更新已保存的问题时
仪表板与卡片布局	references/dashboards.md	构建或复刻仪表板时
图表与 visualization_settings	references/charts-settings.md	配置图表显示或坐标轴设置时
用于语义 BI 的 Agent 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 编写内容脚本，或执行服务器管理操作（migrate、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 弥补尚未解决的源模型问题，而这些问题本应在上游数仓建模或指标治理中修复。

相关技能

• ../data-analytics-engineering/SKILL.md，用于语义建模、指标和适用于 BI 的数仓设计
• ../data-sql-optimization/SKILL.md，用于查询调优和数据库性能处理
• ../software-backend/SKILL.md，用于应用集成和服务层实现
• ../agents-mcp/SKILL.md，当 Metabase 访问应封装为工具而非临时脚本时参考
• ../agents-mcp/references/mcp-for-dwh.md，用于了解经由 MCP 调用大模型的模式目录（形态 A，即托管 BI MCP，直接适用于 Metabase）；无论采用何种形态，强制措施层（只读角色、查询预算、假名化边界、审计日志）均适用

经验总结循环

当以往的决策或陷阱与当前情况相关时，如果存在 learnings.consolidated.md，请查阅该文件；仅在需要了解历史或将其作为可用后备时才使用 learnings.md。否则跳过这两个文件。

应用这些经验后，如果你遇到了值得记住的模式、值得避免的错误或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 在 learnings.md 中追加一条带日期的条目。不要修改 SKILL.md 本身。