Metabase

---
name: metabase
description: "Metabase expert. Deep expertise in question design, models, dashboards, embedding (static, full-app, SDK), permissions and data sandboxing, caching, Data Studio semantic layer, Transforms, and Metabot AI. WHEN: \"Metabase\", \"Metabase question\", \"Metabase query builder\", \"Metabase SQL\", \"Metabase model\", \"Metabase dashboard\", \"Metabase embed\", \"Metabase SDK\", \"Metabase embedding\", \"static embedding\", \"guest embed\", \"full-app embedding\", \"Metabase permissions\", \"data sandboxing\", \"Metabase collection\", \"Metabase caching\", \"Metabase API\", \"Metabase Docker\", \"Metabase JAR\", \"Metabase Cloud\", \"Metabase Pro\", \"Metabase Enterprise\", \"Metabot\", \"Metabase Data Studio\", \"Metabase transform\", \"Metabase segment\", \"Metabase measure\", \"Metabase tenant\", \"Metabase remote sync\", \"Metabase filter\", \"Metabase subscription\"."
license: MIT
---

# Metabase

This skill covers Metabase, the open-source business intelligence and embedded analytics platform, in depth:

- Question types (graphical query builder, custom/advanced questions, native SQL with variables and snippets)
- Models and semantic layer (metadata enrichment, segments, measures, Data Studio, Transforms)
- Dashboard design (cards, filters, cross-filtering, tabs, click behavior, subscriptions, actions)
- Embedding (static/guest embeds, full-app embedding with SSO, Modular Embedding SDK for React)
- Permissions and security (group-based additive model, data sandboxing, row/column security, connection impersonation)
- Caching (duration, schedule, adaptive policies; cache hierarchy; automatic refresh)
- API (REST API with API keys or session tokens; Agent API for semantic layer access)
- Deployment (JAR, Docker, Metabase Cloud; application database selection; cluster scaling)
- AI features (Metabot -- Anthropic-powered SQL generation, chart summaries, semantic search)
- Version control (Remote Sync with Git, dependency checks)
- Data delivery (scheduled email/Slack, conditional delivery, CSV/XLSX subscriptions)

The current version is **Metabase v59** (March 2026), with v60 in beta. Metabase follows a regular release cadence. Guidance applies to the current platform.

## How to Approach Tasks

1. **Classify** the request:
   - **Question / query design** -- Load `references/best-practices.md` for question type selection, query performance, model design
   - **Dashboard design** -- Load `references/best-practices.md` for layout, filters, interactivity, performance limits
   - **Embedding** -- Load `references/architecture.md` for embedding methods, then `references/best-practices.md` for architecture patterns and auth
   - **Permissions / security** -- Load `references/architecture.md` for permission model, then `references/best-practices.md` for sandboxing and group management
   - **Performance / caching** -- Load `references/architecture.md` for caching mechanics, `references/best-practices.md` for caching strategy, `references/diagnostics.md` for bottleneck diagnosis
   - **Troubleshooting** -- Load `references/diagnostics.md` for diagnostic tools, common issues, upgrade procedures

2. **Determine scope** -- Identify the plan tier (Open Source, Starter, Pro, Enterprise) since many features are plan-gated. Also determine deployment method (Cloud vs self-hosted) and application database (H2 vs PostgreSQL/MySQL).

3. **Load context** -- Read the relevant reference file for deep technical detail.

4. **Analyze** -- Apply Metabase-specific reasoning. Consider plan tier limitations, permission additivity, caching hierarchy, and embedding method constraints.

5. **Recommend** -- Provide actionable guidance with configuration steps, API examples, permission setup, or embedding code.

6. **Verify** -- Suggest validation steps (server logs via Admin > Tools > Logs, diagnostic info via `Ctrl+F1`, browser console, database-side query analysis, Usage Analytics).

## Ecosystem

```
┌────────────────────────────────────────────────────────────────┐
│                    Metabase Platform                            │
│                                                                │
│  ┌──────────────────────────────────────────┐                  │
│  │           Data Studio (v59+)             │                  │
│  │  ┌───────────┐ ┌──────────┐ ┌────────┐  │                  │
│  │  │Transforms │ │ Library  │ │  Data   │  │                  │
│  │  │(SQL/Py)   │ │(curated) │ │Structure│  │                  │
│  │  └─────┬─────┘ └────┬─────┘ └────┬───┘  │                  │
│  │        └─────────────┴────────────┘      │                  │
│  └──────────────────────┬───────────────────┘                  │
│                         │                                      │
│     ┌───────────────────┼───────────────────┐                  │
│     │                   │                   │                   │
│  ┌──▼──────────┐ ┌──────▼──────┐ ┌─────────▼───┐              │
│  │  Questions  │ │   Models    │ │  Dashboards  │              │
│  │(builder/SQL)│ │ (semantic)  │ │(cards/filter)│              │
│  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘              │
│         └───────────────┼───────────────┘                      │
│                   ┌─────▼──────┐                               │
│                   │  Caching   │  Duration / Schedule / Adaptive│
│                   └─────┬──────┘                               │
│                         │                                      │
│              ┌──────────▼──────────┐                           │
│              │   Query Engine      │  SQL generation            │
│              └──────────┬──────────┘                           │
└─────────────────────────┼──────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────────┐
          │               │                   │
   ┌──────▼──────┐ ┌──────▼──────┐ ┌─────────▼────────┐
   │ PostgreSQL  │ │  BigQuery   │ │  18+ SQL DBs     │
   │ MySQL       │ │  Snowflake  │ │  MongoDB, etc.   │
   └─────────────┘ └─────────────┘ └──────────────────┘
```

| Component | Purpose |
|---|---|
| **Query Builder** | Graphical drag-and-drop query interface for business users |
| **SQL Editor** | Native SQL with variables, field filters, template tags, snippets |
| **Models** | Curated semantic layer datasets with metadata enrichment |
| **Data Studio** (v59+) | Analyst workbench: Transforms, Library, Data Structure, Diagnostics |
| **Dashboards** | Cards, filters, tabs, click behavior, subscriptions, cross-filtering |
| **Caching Layer** | Hierarchical caching with four policies (duration, schedule, adaptive, none) |
| **Embedding** | Static/guest embeds, full-app embedding, Modular SDK (React) |
| **REST API** | Full programmatic access via API keys or session tokens |
| **Metabot** | Anthropic-powered AI for SQL generation, chart summaries, semantic search |

## Question Types

| Type | Best For | Drill-Through | SQL Knowledge |
|---|---|---|---|
| **Query Builder (graphical)** | Business user self-service; exploratory analysis | Yes | None needed |
| **Custom Questions (advanced)** | Complex expressions, calculated columns, multi-table joins | Yes | Expression syntax |
| **Native SQL** | CTEs, window functions, database-specific syntax, performance-critical | No | Full SQL |

**Metabot AI** (v59+, Anthropic-powered): Single-prompt natural language to SQL conversion in the SQL editor. Available in open source with bring-your-own Anthropic API key.

## Models and Semantic Layer

Models are curated datasets that serve as the semantic layer:

- **Metadata enrichment** -- Display names, descriptions, semantic types (Currency, Category, FK), visibility settings per column
- **Segments** (v59+) -- Reusable predefined filters ("Active Users", "Last 30 Days")
- **Measures** (v59+) -- Reusable aggregation definitions ("Total Revenue", "Average Order Value")
- **Version history** -- Retains 15 previous versions with change tracking and reversion
- **Transforms** (v59+) -- SQL/Python transformations of raw data into analytics-ready tables; replacing model persistence

**Data Studio** (v59+): Analyst workbench providing Transforms, a curated Library, Data Structure metadata management, and Diagnostics for dependency tracking.

## Dashboard Design

**Components:** Question cards, text cards (Markdown with filter variables), link cards, heading cards, action cards (database writes)

**Filters:** Dashboard-level filters updating multiple cards; linked/cascading filters; cross-filtering (click chart to filter others); wired to text cards via variables

**Tabs:** Split content across tabs for organization and performance (each tab loads independently)

**Click behavior:** Navigate to dashboards/questions/URLs; pass clicked values as filter parameters; open modals or new tabs

**Subscriptions:** Schedule delivery via email or Slack (hourly/daily/weekly/monthly); CSV/XLSX-only option; conditional delivery based on filter results

**Performance limits:** Keep dashboards to 20-25 cards maximum per tab. More cards degrade load times.

## Embedding

| Method | Plan | Auth | Interactivity |
|---|---|---|---|
| **Static Embedding** | All (branded in OSS/Starter) | JWT-signed iframe | Limited (locked/editable params) |
| **Guest Embeds** (v58+) | Pro/Enterprise | JWT-signed | View-only with enhanced theming |
| **Full-App Embedding** | Pro/Enterprise | JWT SSO (recommended), SAML, LDAP | Full (explore, filter, drill) |
| **Modular Embedding SDK** | Pro/Enterprise | JWT SSO | Component-level React integration |

**Static embedding flow:** Server generates JWT with locked parameters (user/tenant-specific) -> signed URL loaded in iframe -> data restricted per locked params.

**Full-app embedding:** Embeds entire Metabase in iframe with SSO. Full permissions and data sandboxing. Multi-tenant support via Tenants feature (v58+).

**Modular SDK (React):**
- Available components: charts, dashboards, query builder, AI chat, collections
- Requirements: React 18/19, Node.js 20.x+, Metabase 1.52+
- **SDK version must match Metabase instance version exactly** (`@metabase/embedding-sdk-react@56-stable`)
- Configure CORS origins in Metabase admin
- SSR not supported (auto-skipped as of v57)

## Permissions Model

Permissions are **group-based** and **additive** (most permissive group wins).

### Data Access Levels

| Level | Description | Plan |
|---|---|---|
| **Can view** | Full access to all data in the source | All |
| **Granular** | Per-table or per-schema configuration | Pro/Enterprise |
| **Sandboxed** (row/column security) | Row/column restrictions based on user attributes | Pro/Enterprise |
| **Impersonated** | Uses database roles to determine access | Pro/Enterprise |
| **Blocked** | No access regardless of collection permissions | Pro/Enterprise |

**Critical rules:**
- Restrict the "All Users" group **first** -- it is the baseline for all users
- If any table is blocked/sandboxed, native SQL access is disabled for the entire database
- Collection permissions are separate from data permissions
- Download permissions can bypass row-level security if not configured correctly

## Caching

### Cache Invalidation Policies

| Policy | Description | Plan |
|---|---|---|
| **Duration** | Cache for N hours | Pro/Enterprise |
| **Schedule** | Invalidate hourly/daily/weekly/monthly | Pro/Enterprise |
| **Adaptive** | Duration = avg query time x multiplier (e.g., 10s avg x 100 = 1000s cache) | All |
| **Don't cache** | Disable caching | All |

### Configuration Hierarchy (highest priority wins)

1. Question-level policy
2. Dashboard-level policy
3. Database-level policy
4. Default site-wide policy

**Automatic cache refresh** (Pro/Enterprise): Reruns queries immediately upon invalidation so users always see cached results. Incompatible with row/column security, connection impersonation, database routing.

**Parameter caching:** Caches results for up to 10 most frequently used parameter value combinations.

## Licensing

| Plan | Cost | Key Capabilities |
|---|---|---|
| **Open Source** | Free | Query builder, SQL editor, dashboards, documents, static embedding (branded), basic permissions, REST API, AI SQL (BYOK Anthropic) |
| **Starter** | $100/mo + $6/user | Cloud-hosted, 5 users included, basic support |
| **Pro** | $575/mo + $12/user | Row/column security, SSO (SAML/LDAP/JWT/SCIM), white-labeling, SDK, full-app embedding, advanced caching, remote sync, audit logs, tenants |
| **Enterprise** | $20k+/year custom | Priority support, dedicated engineer, SOC2, air-gapping, single-tenant option |

**Add-ons:** Metabot AI ($100/mo), Advanced Transforms ($250/mo), Additional Storage ($40/mo per 500k rows)

## Deployment

| Method | Application DB | Best For |
|---|---|---|
| **Metabase Cloud** | Managed | Most deployments; zero DevOps; automatic upgrades |
| **Docker** (`metabase/metabase`) | PostgreSQL (recommended) | Self-hosted production |
| **JAR file** | PostgreSQL (recommended) | Self-hosted; JDK 21+ required |
| **H2 (embedded)** | Built-in | Development/demo **only** -- NOT for production |

**Critical:** H2 is the default application database but is unsuitable for production (corruption risk, performance limitations). Migrate to PostgreSQL before production deployment.

**Cluster scaling:** Multiple Metabase nodes can share a PostgreSQL application database for horizontal scaling. Reduce to a single node during upgrades (migrations must run on one node).

## REST API

**Authentication:**
- API keys: `x-api-key` header (preferred for programmatic access)
- Session tokens: `X-Metabase-Session` header from `POST /api/session`

**Key endpoints:**
- `/api/card` -- Question/card CRUD
- `/api/dashboard` -- Dashboard management
- `/api/database` -- Database connections
- `/api/user` -- User management
- `/api/permissions` -- Group and permission management
- `/api/collection` -- Collection management

**Agent API** (v59+): Programmatic semantic layer access for automation and integration.

## Recent Version Highlights

| Version | Key Features |
|---|---|
| **v59** (Mar 2026) | Data Studio, Transforms (SQL/Python), boxplots, AI SQL in OSS, Agent API, conditional number formatting, segments/measures |
| **v58** (Jan 2026) | Tenants for multi-tenant analytics, Guest Embeds, Documents for all, Metabot GA, AWS IAM auth |
| **v57** (Nov 2025) | Dark mode, Remote Sync (git), Documents, parameterizable snippets, automatic dependency checks, inline editing |
| **v60** (beta) | Series panel splitting (separate panels within same visualization) |

## Anti-Patterns

| Anti-Pattern | Problem | Correct Approach |
|---|---|---|
| H2 in production | Corruption risk, file-level locking, no concurrent access | PostgreSQL for production; migrate before going live |
| 30+ cards on a single dashboard tab | Each card generates a query; cumulative load degrades performance | Limit to 20-25 cards; use tabs; split into focused dashboards |
| "All Users" group unrestricted | Granular permissions ineffective because additive model grants the broadest access | Restrict "All Users" first, then add specific group permissions |
| Native SQL on sandboxed databases | Bypasses row/column security entirely | Restrict sandboxed users to query builder only |
| Mismatched SDK version | Embedding components fail to load or behave unpredictably | Match SDK npm package version to Metabase instance version exactly |
| Embedding secret key in client code | Exposes JWT signing secret; anyone can forge embed tokens | Keep secret server-side; generate signed URLs on the server |
| No default filters on dashboards | Every card runs an unbounded query on initial load | Set default filter values (especially time ranges) to limit data |
| Ignoring cache hierarchy | Expensive queries re-execute unnecessarily | Set site-wide adaptive default; override at database/dashboard/question level for hot queries |
| Skipping application DB backup before upgrade | Migration failures can corrupt the application database | Always back up before upgrade; test in staging first |
| Interrupting database migrations | Corrupts application database; may require restore from backup | Never interrupt; plan for downtime during upgrades |
| Forgetting download permissions | Users can download full datasets, bypassing row-level security | Align download permissions with data access restrictions |
| JSON unfolding left enabled | Dramatically slows database sync for tables with JSON columns | Disable JSON unfolding if not needed |

## Cross-References

- `overview` skill, this plugin -- technology comparison and selection guidance across BI tools

## Reference Files

- `references/architecture.md` -- Application server, application database, question types, models, dashboards, embedding methods (static, full-app, SDK), permission model, caching mechanics, database connectivity, REST API
- `references/best-practices.md` -- Question design (when to use each type), model design and metadata enrichment, dashboard layout and filter patterns, embedding architecture patterns (static, full-app, SDK), permissions and group management, caching strategy, database optimization, performance tuning
- `references/diagnostics.md` -- Diagnostic tools (built-in diagnostics, server logs, HAR files, JMX), slow query/dashboard diagnosis, connection troubleshooting, permission errors, embedding issues (CORS, JWT, SDK version), sync/scan problems, upgrade procedures and rollback