diff --git a/_docs/v0.62/README.md b/_docs/v0.62/README.md index 166a5784c3..310310f046 100644 --- a/_docs/v0.62/README.md +++ b/_docs/v0.62/README.md @@ -60,7 +60,8 @@ Metabase's reference documentation. - [Development instances](./installation-and-operation/development-instance) - [Serialization](./installation-and-operation/serialization) - [Remote sync](./installation-and-operation/remote-sync) -- [Commands](./installation-and-operation/commands) +- [Metabase CLI](./installation-and-operation/metabase-cli) +- [Metabase JAR commands](./installation-and-operation/commands) - [Supported browsers](./installation-and-operation/supported-browsers) - [Privacy](./installation-and-operation/privacy) - [About the anonymous usage data we collect](./installation-and-operation/information-collection) diff --git a/_docs/v0.62/ai/file-based-development.md b/_docs/v0.62/ai/file-based-development.md index 62498f7289..9b2fdb8e50 100644 --- a/_docs/v0.62/ai/file-based-development.md +++ b/_docs/v0.62/ai/file-based-development.md @@ -7,34 +7,36 @@ category: Ai title: 'Agent-driven development' source_url: 'https://github.com/metabase/metabase/blob/master/docs/ai/file-based-development.md' layout: new-docs -summary: 'Use an agent with skills to create Metabase content on your local machine as YAML files, then upload the files to your Metabase.' +summary: 'Use a coding agent and the Metabase CLI to create Metabase content, then version that content as YAML files with Remote Sync.' --- # Agent-driven development {% include plans-blockquote.html feature="Agent-driven development" %} -Metabase content like questions and dashboards can be serialized as YAML files. You can edit those YAML files by hand, sure, but now that we have actual genies, you can just ask them to edit them for you (call it "lamp-rubbing development"). +Now that we have actual genies, you can just ask the genies to create the content for you (call it "lamp-rubbing development"). -Paired with some skills we've developed, you can export your Metabase as YAML files, ask your agent to create new questions and dashboards YAML files, then import that new content into your Metabase. It's a whole new way to work with Metabase. +Give an agent the [Metabase CLI](../installation-and-operation/metabase-cli), and it can create content for you. But since LLMs can be unpredictable, we recommend developing content in a dev instance of Metabase, then using [Remote Sync](../installation-and-operation/remote-sync) to get your changes into production. -## The agent-driven development toolkit - -To develop your Metabase content on your local filesystem, we've put together a set of tools, including a set of agent skills. - -- [**Metabase Representation Format**](https://github.com/metabase/representations): the YAML schema and spec for every Metabase entity (questions, dashboards, collections, transforms, and so on). -- **[Metabase Database Metadata Format](https://github.com/metabase/database-metadata)**: diff-friendly representations of synced databases, their tables, and their fields, as a tree of YAML files. -- **Export and Import** CLI and API endpoints to move serialized content between your local files and Metabase. -- [**Remote Sync**](../installation-and-operation/remote-sync) (Optional): push content from a Read-write Metabase into a git repo, and pull it into a Read-only Metabase in production. +With this set up, a typical workflow using an agent with a development instance of Metabase would be: -## How content moves between files and Metabase +1. Prompt the agent with `/metabase-cli Create a dashboard based on the sales table.` +2. Agent creates questions and a dashboard. +3. View the dashboard in your dev instance. +4. Iterate either in your Metabase or via the agent until you're happy with the dashboard. +5. Use Remote Sync to push your changes to a repo. +6. Create a PR. +7. Merge the changes. +8. Once merged, your production Metabase pulls in the changes via Remote Sync. -You'll need a way to get YAML files out of Metabase to edit and back into Metabase to verify and ship. There are two options: +## The agent-driven development toolkit -- **[Remote Sync](../installation-and-operation/remote-sync)** — push and pull from inside Metabase. Requires a Read-write development instance and a Read-only production instance. -- **Serialization API** — `curl`-based export and import against the `/api/ee/serialization/` endpoints. +To develop your Metabase content with an agent, we've put together a set of tools. -Pick one before you start the [Initial setup](#initial-setup); the setup steps differ slightly (Remote Sync doesn't need a separate API key in production). +- A Metabase instance to use for development. +- [**Metabase CLI**](../installation-and-operation/metabase-cli): a command-line client (`mb`) your agent uses to create content directly in your Metabase. Use the CLI with the [`/metabase-cli` skill](https://github.com/metabase/agent-skills/tree/main/skills/metabase-cli). +- [**Metabase Representation Format**](https://github.com/metabase/representations): the YAML schema and spec for every Metabase entity (questions, dashboards, collections, transforms, and so on). This is the format your content takes once you version it as files. +- [**Remote Sync**](../installation-and-operation/remote-sync): push content from a Read-write Metabase into a git repo, and pull it into a Read-only Metabase in production. ## Initial setup @@ -42,20 +44,19 @@ Some things to put into place to get a workflow going: 1. [Set up a development Metabase](#set-up-a-development-metabase) 2. [Set up a repository to version your YAML files](#set-up-a-repository-to-version-your-yaml-files) -3. [Add agent skills to your repository](#add-agent-skills-to-your-repository) -4. [Download the database metadata](#download-the-database-metadata) +3. [Install and authenticate the Metabase CLI](#install-and-authenticate-the-metabase-cli) +4. [Add the agent skill](#add-the-agent-skill) -Once you have these set up, you can step through one of the example workflows. +Once you have these set up, you can step through the example workflow. ### Set up a development Metabase 1. Set up a Metabase instance to check your work before pushing changes to production. This Metabase should connect to the same data warehouse(s) your production Metabase connects to. A [config file](../configuring-metabase/config-file) will come in handy here. -2. Create an [API key](../people-and-groups/api-keys#create-an-api-key) and assign it to the Admin group. The skills export and import all content and read database metadata, so they need Admin-level access. If you're using the [Serialization API workflow](#how-content-moves-between-files-and-metabase), you'll also need to create an API key in your production Metabase so you can import your files into it. +2. Create an [API key](../people-and-groups/api-keys#create-an-api-key) in this development Metabase and assign it to the Admin group, so the agent can create content and work with Remote Sync. 3. We also recommend turning off the sample content and usage analytics, so they don't pollute the data model. If you're using a [docker compose file](../installation-and-operation/running-metabase-on-docker), add these [environment variables](../configuring-metabase/environment-variables): - ``` MB_LOAD_SAMPLE_CONTENT: "false" MB_INSTALL_ANALYTICS_DATABASE: "false" @@ -63,271 +64,89 @@ MB_INSTALL_ANALYTICS_DATABASE: "false" ### Set up a repository to version your YAML files -1. Initialize a new repo. -2. Add a `.gitignore` file and add `.metabase/` and `.env`. -3. Add the following to your `.env`: - -``` - METABASE_URL={your-metabase-url} - METABASE_API_KEY={your-api-key} -``` - -### Add agent skills to your repository - -You should add the following skills to your agent so it has context it needs. If you commit the skills into `.claude/skills/` in your repo, for example, Claude loads them automatically whenever you run it from that directory. - -- [**`metabase-representation-format` agent skill**](https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/SKILL.md): teaches the agent the representation format and ships the schema checker. -- [**`metabase-database-metadata` agent skill**](https://github.com/metabase/agent-skills/blob/main/skills/metabase-database-metadata/SKILL.md): fetches database metadata from your Metabase into an on-disk YAML tree the agent can read while editing. -- [**`metabase-semantic-checker` agent skill**](https://github.com/metabase/agent-skills/blob/main/skills/metabase-semantic-checker/SKILL.md) (optional): runs Metabase's semantic checker in Docker to catch referential and query errors the schema check doesn't. - -### Download the database metadata - -Invoke the `metabase-database-metadata` skill and ask your agent to fetch the database metadata. The agent will: - -- Check that `.env` exists. If it doesn't, the agent will prompt you to create it. -- Verify that `.env` and `.metabase/` are in `.gitignore`, asking before adding them. -- Fetch `/api/database/metadata` into `.metabase/metadata.json` (raw API response; can be several GB on large warehouses). -- Extract a diff-friendly YAML tree to `.metabase/databases//schemas//tables/.yaml` by running `npx @metabase/database-metadata extract-metadata`. - -The agent can use the YAML extracted to your `.metabase` directory while creating and editing new questions and dashboards in YAML. That way your agent can refer to real column names, field types, and foreign-key relationships without making live API calls (which would be much slower). - -To refresh this database metadata, just ask your agent to re-fetch it. - -## Example workflows - -The workflows below both assume you've completed the [Initial setup](#initial-setup). - -### Example prompts - -Once your repo has the agent skills and a baseline of content, prompt the agent with a structured request: +Create a new git repository for your Metabase content. You'll point Remote Sync at this repo when you configure it, and clone the repo locally to review changes and open pull requests. -``` -Use the metabase-representation-format and metabase-database-metadata skills to create new YAML files in this directory: +### Install and authenticate the Metabase CLI -1. Create a new dashboard called "Support overview" in collections/main/. -2. Add questions showing total ticket volume, open tickets, and average satisfaction rating. -``` - -Or, depending on how capable your model is, try a more open-ended request: +Install the [Metabase CLI](../installation-and-operation/metabase-cli) globally: ``` -Use the metabase-representation-format and metabase-database-metadata skills to analyze our support data. Look at the tickets, customers, and interactions tables, and create a dashboard that gives an overview of our team's support workload. +npm install -g @metabase/cli ``` -The agent will read the representation format spec, check existing files for local conventions, consult `.metabase/databases/` for real column names, and write new YAML. - -## Example workflow with Remote Sync - -### 1. Configure Remote Sync on both instances - -In your development Metabase, configure [Remote Sync in Read-write mode](../installation-and-operation/remote-sync#setting-up-remote-sync) pointed at your repo. In production, configure a second Metabase in Read-only mode pointed at the same repo. - -### 2. Create a branch from the Metabase UI - -Switch branches in Metabase, as the Metabase UI is the source of truth for which branch the development instance pushes to and pulls from. - -In your development Metabase, click the **branch dropdown** at the top and [create a new branch](../installation-and-operation/remote-sync#creating-a-branch) for your work, like `feature/support-dashboard`. - -### 3. Push existing content to seed the repo - -Click the up arrow (**push**) icon to [commit and push](../installation-and-operation/remote-sync#committing-and-pushing-your-changes) your existing synced collections to the branch. +Then authenticate it against your development Metabase: -### 4. Clone the repo locally and check out the branch - -```sh -git clone your-metabase-repo -cd your-metabase-repo -git checkout feature/support-dashboard ``` - -### 5. Ask the agent to edit or create content - -See [Example prompts](#example-prompts) above for prompt patterns to use here. - -### 6. Validate the YAML files - -Run the [schema check](#schema-check) after every batch of edits, and optionally run the [semantic check](#semantic-checker-for-deeper-validation) at the end of the session. See [Validating YAML files](#validating-yaml-files) below. - -If anything fails, the agent should be able to fix the issue if you give it the error. - -### 7. Commit and open a pull request - -```sh -git add -A -git commit -m "Add support-overview dashboard" -git push origin feature/support-dashboard +mb auth login --url your-metabase-url-here ``` -Open a pull request so your team can review the YAML diff. - -### 8. Pull the branch into your development Metabase - -Click the **pull** (down arrow) icon in your development Metabase to load the agent's changes. Verify the dashboard renders correctly and the questions return expected results. +Authenticate with the API key you created in your Metabase instance. -### 9. Merge the PR so production picks up the changes +### Add the agent skill -If you've enabled [auto-sync](../installation-and-operation/remote-sync#pulling-changes-automatically), your production Metabase (in Read-only mode) will pull the new main branch automatically on its next interval. Otherwise, trigger a pull from production manually. +Add the [`/metabase-cli` skill](https://github.com/metabase/agent-skills/tree/main/skills/metabase-cli) to your agent so it knows how to use the CLI to create content directly in your Metabase. -## Example workflow with import and export endpoints +## Example prompts -### 1. Clone the empty repo and create a branch +These examples assume you've completed the [Initial setup](#initial-setup). Run the `/metabase-cli` skill and give the agent a structured request. The agent will run CLI commands to create the content directly in your development Metabase: -```sh -git clone https://github.com/your-org/your-repo.git -cd your-repo -git checkout -b feature/support-dashboard ``` - -### 2. Export existing content to seed the repo - -The agent does better work when the repo already holds your current Metabase content, so it can see real examples of the Representation Format and your collection conventions. Run the [serialization export](../installation-and-operation/serialization#serialization-workflow-example) from inside the clone: - -```sh -curl \ - -H 'X-API-Key: YOUR_API_KEY' \ - -X POST 'https://your-metabase-url/api/ee/serialization/export?data_model=false' \ - -o metabase_data.tgz -tar -xzf metabase_data.tgz -``` - -Set `data_model=false` to keep the export small. The agent should get its metadata from the `metabase-database-metadata` skill instead. For more on export options, see [Serialization](../installation-and-operation/serialization). - -Commit the extracted YAML so you have a baseline to revert to if the agent goes off the rails. - -### 3. Ask the agent to edit or create content - -See [Example prompts](#example-prompts) above for prompt patterns to use here. - -### 4. Validate the YAML files - -Run the [schema check](#schema-check) after every batch of edits, and optionally run the [semantic check](#semantic-checker-for-deeper-validation) at the end of the session. See [Validating YAML files](#validating-yaml-files) below. - -### 5. Commit and open a pull request - -```sh -git add -A -git commit -m "Add support-overview dashboard" -git push origin feature/support-dashboard +/metabase-cli Create a new dashboard called "Support overview". Add questions showing total ticket volume, open tickets, and average satisfaction rating. ``` -Then open open a pull request so your team can review the YAML diff. - -### 6. Import the YAML into your development Metabase - -Re-bundle the YAML and import it: +Or, depending on how capable your model is, try a more open-ended request: -```sh -tar -czf metabase_data.tgz metabase_data -curl -X POST \ - -H 'X-API-Key: YOUR_API_KEY' \ - -F 'file=@metabase_data.tgz' \ - 'https://your-metabase-url/api/ee/serialization/import' \ - -o - ``` - -The `-o -` flag writes the import response to stdout, so you can see whether the import succeeded and check any warnings. You can ask the agent to generate `export.sh` and `import.sh` wrappers so you're running a single command each time. - -Verify the dashboard renders correctly and the questions return expected results. - -### 7. Repeat the import against production - -Once you're confident in the changes, run the same `tar` + `curl` import against your production Metabase, using its API key. - -## Undoing the agent's changes - -If you want to undo the agent's changes, use `git` to revert your YAML files to the last known-good commit before pushing or re-importing. - -If you're using Remote Sync, don't try to fix things by re-pushing from Metabase: Metabase's push only reflects its current state and won't delete any new files the agent created locally. - -## Validating YAML files - -Run both checks locally before pushing. The same checks belong in CI — see [CI example](#ci-example) below. - -### Schema check - -You can run a quick schema check: - -```sh -npx --yes @metabase/representations validate-schema +/metabase-cli Analyze our support data. Look at the tickets, customers, and interactions tables, and build a dashboard that gives an overview of our team's support workload. ``` -The check validates the shape of every YAML file against the Representation Format spec. The `metabase-representation-format` skill should run this check for you automatically after the agent makes any edits. +The agent writes the CLI commands and creates the questions and dashboard for you—just describe what you want. -### Semantic checker for deeper validation +## Example workflow -> The semantic checker is only available in the Pro/Enterprise plans. +### 1. Configure Remote Sync on both Metabase instances -The **semantic checker** catches things like references to tables that don't exist or columns the agent invented. +In your development Metabase, configure [Remote Sync in Read-write mode](../installation-and-operation/remote-sync#setting-up-remote-sync) pointed at your repo. -What it validates beyond schema: +Set up Remote Sync in your production Metabase in Read-only mode pointed at the same repo. -- Cross-entity references: `collection_id`, `dashboard_id`, `parent_id`, snippet names, transform tags, card embeddings. -- MBQL query compilation: `source-table`, field references, joins, segments, measures, expressions. -- Native-query references: tables, columns, and snippets named in SQL. - -If you've installed the `metabase-semantic-checker` skill, just ask the agent to run the semantic checker; the skill picks the right image, passes the right flags, and summarizes the findings. +### 2. Create a branch from the Metabase UI -You can manually run the semantic checker via Docker like so: +Switch branches in Metabase, as the Metabase UI is the source of truth for which branch the development instance pushes to and pulls from. -```sh -docker pull metabase/metabase-enterprise:latest +In your development Metabase, click the **branch dropdown** at the top and [create a new branch](../installation-and-operation/remote-sync#creating-a-branch) for your work, like `feature/support-dashboard`. -docker run --rm \ - -v "$PWD:/workspace" \ - --entrypoint "" \ - -w /app \ - metabase/metabase-enterprise:latest \ - java -jar metabase.jar \ - --mode checker \ - --export /workspace \ - --schema-dir /workspace/.metabase/metadata.json \ - --schema-format concise -``` +### 3. Ask the agent to create content -Match the image tag (`:latest`) to your Metabase build. +Run the `/metabase-cli` skill and prompt the agent to build your questions and dashboards. The agent creates the content directly in your development Metabase. -### CI example +### 4. Verify the content in your development Metabase -You can hook the schema check into GitHub Actions so your team catches problems on the PR, before anyone pulls the changes into Metabase: +Open your development Metabase and confirm the dashboard renders correctly and the questions return expected results. Make any changes you want, either in the UI or via the agent. -```yaml -# .github/workflows/schema-check.yml -name: Schema Check +### 5. If you make any changes in your Metabase, push the new content to the branch -on: - push: - branches: [main] - pull_request: +To commit the work, [push the change from your Metabase](../installation-and-operation/remote-sync#committing-and-pushing-your-changes). If you don't push your changes from your Metabase to your repo, you could lose work the next time you pull changes into that Metabase. -jobs: - schema-check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 +### 6. Open a pull request - - uses: actions/setup-node@v6.4.0 - with: - node-version: "20" +Open a pull request so your team can review the YAML diff. They can also use Remote Sync to pull the branch into a development Metabase and see the changes live. - - name: Validate representation YAML files - run: npx --yes @metabase/representations validate-schema -``` +### 7. Merge the PR so production picks up the changes -For the semantic check, add a second workflow that fetches `.metabase/metadata.json` from your Metabase and then runs the Docker command above against the checkout. If you run the semantic check in more than one workflow (for example, a semantic check and per-PR preview environments), you should probably factor the database metadata fetch to run and cache once a day so you don't hit the API on every push. +If you've enabled [auto-sync](../installation-and-operation/remote-sync#pulling-changes-automatically), your production Metabase (in Read-only mode) will pull the new main branch automatically on its next interval. -## Deleting content +## Undoing the agent's changes -Since imports and exports _don't_ delete content, you'll need to delete content in the Metabase application itself, then update the YAML files as well. +Since the agent uses the CLI to create content directly in Metabase, to undo changes, you could either: -1. Delete the content in your production Metabase (in the app's UI). -2. Push (with Remote Sync) or re-export (without) so the change is reflected in the repo. -3. Commit the deletion. That way Metabase won't recreate the deleted items the next time it pulls. +- **Revert to a commit and pull changes**: Revert to a previous commit, and pull that commit into your Metabase. Pulling that commit would overwrite any changes you or the agent had made. +- **Update Metabase and push changes**: Edit or archive the content in your Metabase (either manually or via an agent with the CLI), and push the changes to your repo. You may want to pick this approach if you want to keep some, but not all of the changes made by the AI, or if you've made additional changes via Metabase's handy UI that you want to keep. ## Further reading - [Remote Sync](../installation-and-operation/remote-sync) -- [Serialization](../installation-and-operation/serialization) +- [Metabase CLI](../installation-and-operation/metabase-cli) - [Metabase Representation Format](https://github.com/metabase/representations) -- [Metabase Database Metadata Format](https://github.com/metabase/database-metadata) - [Agent skills](https://github.com/metabase/agent-skills) -- [MCP server](./mcp) — for agents that need live metadata lookups outside the file-based workflow. +- [MCP server](./mcp): for agents that need live metadata lookups outside the file-based workflow. diff --git a/_docs/v0.62/ai/overview.md b/_docs/v0.62/ai/overview.md index de7dc8f52a..d5e9a46e2c 100644 --- a/_docs/v0.62/ai/overview.md +++ b/_docs/v0.62/ai/overview.md @@ -57,7 +57,7 @@ See [full docs for MCP server](mcp). **Best for: developers creating stuff that other people will use.** -Use a coding agent like Claude Code to understand your database's metadata, generate Metabase content as YAML files locally, verify the schema, then sync and import the generated content into your production Metabase. Sky's the limit on what you can accomplish. +Use a coding agent like Claude Code with the Metabase CLI to create Metabase content directly in a development instance, then version that content as YAML files and pull the changes into your production Metabase. **Controls**: Only admins can sync content to Metabase instances. diff --git a/_docs/v0.62/configuring-metabase/appearance.md b/_docs/v0.62/configuring-metabase/appearance.md index a53e14bc74..f0deb76336 100644 --- a/_docs/v0.62/configuring-metabase/appearance.md +++ b/_docs/v0.62/configuring-metabase/appearance.md @@ -169,7 +169,7 @@ What people see when Metabase prompts them to log in. ### Landing page -The landing page is what people will see whenever they login. You can set the URL to a collection, question, dashboard or whatever, just make sure that everyone has access to that URL. +The illustration people see on the landing page when they log in. To choose which page people land on, see [Homepage](./settings#homepage). - Lighthouse - No illustration diff --git a/_docs/v0.62/configuring-metabase/settings.md b/_docs/v0.62/configuring-metabase/settings.md index 2d060c5208..ee6b338cdb 100644 --- a/_docs/v0.62/configuring-metabase/settings.md +++ b/_docs/v0.62/configuring-metabase/settings.md @@ -36,11 +36,13 @@ For example, say you enable HTTPS redirect for a Metabase instance at the site U > Note: if you haven't set up HTTPS on your server, Metabase will not let you enable HTTPS redirect. Instead, you'll get a warning saying "It looks like HTTPS is not properly configured." -## Custom homepage +## Homepage -Admins can pick a dashboard to serve as the homepage. If people lack permissions to view the selected dashboard, Metabase will redirect them to the default homepage. +Set the page people see when they first log in to your Metabase. Choose between: -To revert to the default Metabase homepage, simply toggle off Custom homepage. +- **Default Metabase home**: The standard Metabase homepage. +- **Dashboard**: Pick a dashboard to serve as the homepage. If people lack permissions to view the selected dashboard, Metabase will redirect them to the default homepage. +- **Custom URL**: Send people to a specific URL (a collection, question, dashboard, or other page). Make sure people have access to the URL. This option is only available on Metabase [Pro](/product/pro) and [Enterprise](/product/enterprise) plans. ## Email address for help requests diff --git a/_docs/v0.62/data-studio/transforms/addons.md b/_docs/v0.62/data-studio/transforms/addons.md index fbfb865341..c299a808da 100644 --- a/_docs/v0.62/data-studio/transforms/addons.md +++ b/_docs/v0.62/data-studio/transforms/addons.md @@ -44,7 +44,7 @@ With basic transforms, you can: - **Metabase Cloud**: Basic transform functionality on Metabase Cloud - Starter, Pro, or Enterprise - comes with an additional small fee per successful transform run, see [Pricing](/pricing). - Only people logged in with an email of a [Metabase Store admins](../../cloud/accounts-and-billing#add-people-to-manage-your-metabase-store-account) (not just Metabase _instance_ admins) can enable basic transforms. To enable Basic transforms on Metabase Cloud, see [Enable transforms](./transforms-overview#enable-transforms). + Only people logged in with an email of a [Metabase Store admin](../../cloud/accounts-and-billing#add-managers) (not just Metabase _instance_ admins) can [enable basic transforms](./transforms-overview#enable-transforms). ### Cancel basic transforms @@ -76,7 +76,7 @@ There are two ways to enable Advanced transforms: - **From your Metabase instance**: you can navigate to a feature requiring advanced transforms (like Python transforms or transform inspector), and follow the prompts to upgrade. - To enable Advanced transforms from your Metabase instance, you need to be logged into the instance with the same email as a [Metabase Store admin](../../cloud/accounts-and-billing#add-people-to-manage-your-metabase-store-account), because Advanced transform incur an additional charge. + To enable Advanced transforms from your Metabase instance, you need to be logged into the instance with the same email as a [Metabase Store admin](../../cloud/accounts-and-billing#add-managers), because Advanced transform incur an additional charge. - **From [Metabase Store](https://store.metabase.com)**: diff --git a/_docs/v0.62/data-studio/transforms/transforms-overview.md b/_docs/v0.62/data-studio/transforms/transforms-overview.md index d8f13f00b3..1f82c29ab7 100644 --- a/_docs/v0.62/data-studio/transforms/transforms-overview.md +++ b/_docs/v0.62/data-studio/transforms/transforms-overview.md @@ -67,7 +67,7 @@ Permission configuration for transform depends on your plan. Before you can start writing transforms, you'll need to enable transforms in your Metabase instance. -If you are on a Metabase Cloud plan, only people logged in with an email of a [Metabase Store admins](../../cloud/accounts-and-billing#add-people-to-manage-your-metabase-store-account) (not just Metabase _instance_ admins) can enable basic transforms, because transforms incur a cost per run on Metabase Cloud. +If you're on a Metabase Cloud plan, only people logged in with an email of a [Metabase Store admin](../../cloud/accounts-and-billing#add-managers) (not just Metabase _instance_ admins) can enable basic transforms, because transforms incur a cost per run on Metabase Cloud. To enable transforms: diff --git a/_docs/v0.62/exploration-and-organization/x-rays.md b/_docs/v0.62/exploration-and-organization/x-rays.md index 95a84feae6..a0f0850507 100644 --- a/_docs/v0.62/exploration-and-organization/x-rays.md +++ b/_docs/v0.62/exploration-and-organization/x-rays.md @@ -71,4 +71,4 @@ If for some reason X-rays aren't a good fit for your team or your data, administ If you pin any dashboards in the "Our Analytics" collection, Metabase will hide the X-ray suggestions that appear on the homepage. -Admins can also manually remove these suggestions by clicking on the **Customize** button in the upper right and selecting a dashboard as your homepage. [Changing the home page](../configuring-metabase/settings#custom-homepage) won't disable the X-ray features in the rest of Metabase. +Admins can also manually remove these suggestions by clicking on the **Customize** button in the upper right and selecting a dashboard as your homepage. [Changing the home page](../configuring-metabase/settings#homepage) won't disable the X-ray features in the rest of Metabase. diff --git a/_docs/v0.62/installation-and-operation/commands.md b/_docs/v0.62/installation-and-operation/commands.md index f52dc4942f..1cd053ec31 100644 --- a/_docs/v0.62/installation-and-operation/commands.md +++ b/_docs/v0.62/installation-and-operation/commands.md @@ -4,15 +4,17 @@ has_magic_breadcrumbs: true show_category_breadcrumb: true show_title_breadcrumb: true category: 'Installation and Operation' -title: 'Metabase CLI' +title: 'Metabase JAR commands' source_url: 'https://github.com/metabase/metabase/blob/master/docs/installation-and-operation/commands.md' layout: new-docs -description: 'CLI commands for managing your Metabase instance, including database migrations, serialization, and administrative tasks.' +description: 'Commands built into the Metabase JAR for managing your instance, including database migrations, serialization, and administrative tasks.' --- -# Metabase CLI +# Metabase JAR commands -Metabase ships with some handy CLI commands for administration, maintenance, and automation tasks. These commands let you manage your Metabase instance, migrate databases, handle serialization, and generate documentation. +> Looking for the `mb` command-line client that drives a Metabase instance over its API, on its own or through an AI agent? Check out the [Metabase CLI](./metabase-cli). + +Metabase ships with some handy commands for administration, maintenance, and automation tasks. These commands run on the server, built into the Metabase JAR, and let you manage your Metabase instance, migrate databases, handle serialization, and generate documentation. To view a list of commands, run the Metabase jar followed by `help`. @@ -22,7 +24,6 @@ java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar help Metabase will print out the help text for available commands. - ## `api-documentation` Generate an HTML file and a JSON file for Scalar docs for the Metabase API. diff --git a/_docs/v0.62/installation-and-operation/metabase-cli.md b/_docs/v0.62/installation-and-operation/metabase-cli.md new file mode 100644 index 0000000000..d7f12ff07e --- /dev/null +++ b/_docs/v0.62/installation-and-operation/metabase-cli.md @@ -0,0 +1,84 @@ +--- +version: v0.62 +has_magic_breadcrumbs: true +show_category_breadcrumb: true +show_title_breadcrumb: true +category: 'Installation and Operation' +title: 'Metabase CLI' +source_url: 'https://github.com/metabase/metabase/blob/master/docs/installation-and-operation/metabase-cli.md' +layout: new-docs +summary: 'The Metabase CLI (mb) is a command-line client that drives a Metabase instance over its API. Use it yourself, or hand it to an AI agent with the metabase-cli skill.' +--- + +# Metabase CLI + +The Metabase CLI (`mb`) is a command-line client for Metabase. `mb` authenticates against a Metabase instance with an API key and lets you or an AI agent read and write content like questions, dashboards, collections, and transforms over the Metabase API. + +> Looking for the commands built into the Metabase JAR, like `migrate` or `load-from-h2`? Check out [Metabase JAR commands](./commands). + +## Requirements + +- Node.js, to install the CLI from npm. +- A Metabase instance on version 58 or later. +- An [API key](../people-and-groups/api-keys#create-an-api-key) to authenticate the CLI against your instance. +- A Pro or Enterprise plan for some command groups. For example, `git-sync` needs the premium [Remote sync](./remote-sync) feature. + +## Install the CLI + +``` +npm install -g @metabase/cli +``` + +The binary is `mb`. + +For commands, run: + +``` +mb --help +``` + +## Authenticate the CLI + +Log in once per Metabase instance. + +``` +mb auth login --url https://metabase.example.com +``` + +The CLI prompts for an API key, or reads it from the `METABASE_API_KEY` environment variable or stdin. To create a key, see [API keys](../people-and-groups/api-keys#create-an-api-key). + +Credentials are stored per profile, so you can manage more than one Metabase (like dev and prod Metabases): + +``` +mb auth login --profile prod --url https://prod.example.com +mb auth list +``` + +Add `--profile ` to any command to run it against that instance. + +## Use the CLI with an AI agent + +The CLI is built to be driven by an AI coding agent like Claude Code. Instead of running commands yourself, you install a skill and describe what you want in plain language; the agent works out the commands. + +### The metabase-cli skill + +The [metabase-cli skill](https://github.com/metabase/agent-skills/tree/main/skills/metabase-cli) teaches your agent the CLI's conventions. Once installed, you can run: + +``` +/metabase-cli Create a dashboard summarizing this month's signups by plan. +``` + +And your agent will go to work, creating content directly in your Metabase via the `mb` CLI. + +## Use the CLI for agent-driven development + +Pair the CLI with version control to build content with an agent in a development Metabase, commit the changes, and pull the changes into your production Metabase. Check out [Agent-driven development](../ai/file-based-development). + +## Further reading + +- [@metabase/cli on npm](https://www.npmjs.com/package/@metabase/cli) +- [Agent-driven development](../ai/file-based-development) +- [Agent skills](https://github.com/metabase/agent-skills) +- [Remote sync](./remote-sync) +- [Serialization](./serialization) +- [Metabase JAR commands](./commands) diff --git a/_docs/v0.62/installation-and-operation/start.md b/_docs/v0.62/installation-and-operation/start.md index 2403c8b971..becf355995 100644 --- a/_docs/v0.62/installation-and-operation/start.md +++ b/_docs/v0.62/installation-and-operation/start.md @@ -41,6 +41,10 @@ Try out your changes before deploying to production. Export your questions, dashboards, and more as YAML files that you can check into version control. +## [Metabase CLI](./metabase-cli) + +A command-line client that drives a Metabase instance over its API, on its own or through an AI agent. + ## [Monitoring your Metabase](./monitoring-metabase) Monitor your Metabase with JMX. @@ -61,9 +65,9 @@ We collect anonymous Metabase usage data to improve the product. We don't collec Notes on Metabase's accessibility. -## [Command line commands](./commands) +## [Metabase JAR commands](./commands) -Metabase's CLI. +Administrative commands built into the Metabase JAR. --- diff --git a/_docs/v0.62/questions/images/drill-through-column-header-menu.png b/_docs/v0.62/questions/images/drill-through-column-header-menu.png new file mode 100644 index 0000000000..58d0607cd3 Binary files /dev/null and b/_docs/v0.62/questions/images/drill-through-column-header-menu.png differ diff --git a/_docs/v0.62/questions/visualizations/drill-through.md b/_docs/v0.62/questions/visualizations/drill-through.md new file mode 100644 index 0000000000..855f73adb4 --- /dev/null +++ b/_docs/v0.62/questions/visualizations/drill-through.md @@ -0,0 +1,166 @@ +--- +version: v0.62 +has_magic_breadcrumbs: true +show_category_breadcrumb: true +show_title_breadcrumb: true +category: Questions +title: Drill-through +source_url: 'https://github.com/metabase/metabase/blob/master/docs/questions/visualizations/drill-through.md' +layout: new-docs +summary: 'Click on charts, column headers, and table cells to filter, zoom in, see underlying records, and break out by time, location, or category.' +--- + +# Drill-through + +Drill-through lets you explore data in your Metabase by clicking a chart, a column header, or a table cell. Each click opens a menu with options like **Filter by this value**, **See these records**, **Break out by**, and **Zoom in**. Selecting one of these options generates a new query and visualizes the result. + +![Drill-through menu](../images/drill-through-menu.png) + +## How drill-through works + +Every drill-through action creates a new query and visualizes the result. Metabase takes the original query and modifies it based on what you click. Switch to the editor to see and edit the new query. + +For example, say a bar chart shows order counts summarized by product category and month. Click the April bar in the Widgets series, then select **See these orders**. Metabase creates a new question that filters the orders to Widgets in April. + +Some things to keep in mind: + +- **Drill-through requires query-building permissions.** You must have permission to create queries on the underlying data to see the drill-through menu. +- **The drill-through does not modify the original question.** Drill-through creates a new question without overwriting or modifying your original question. +- **The menu options depend on the type of data you click.** Different options appear in the action menu depending on whether you click a chart, a column header, a table cell, or a point on a map. + +## Drill-through types + +There are two types of drill-through: + +- **Results-based drill-through:** Metabase takes the data in the query result and filters, distributes, or otherwise transforms it. Example options include **Filter by this value**, **Distribution**, and **Sort**. You can perform results-based drill-through on questions built with the query builder or native SQL. +- **Query-rewriting drill-through:** Metabase modifies your query. Example options include **See these records**, **Break out by**, and **Zoom in**. You can only perform query-rewriting drill-through on questions built with the query builder. + +## Drill-through options + +The drill-through menu options depend on what you click and on the underlying data. + +### Tables + +To drill-through a table, click either: + +* Column headers +* Table cells + +#### Column headers + +![Drill-through column header menu](../images/drill-through-column-header-menu.png) + +| Option | When it appears | +| --------------------------------------------------- | ------------------------------------------------------------------------ | +| **Filter by this column** | Any column | +| **Sort** | Any column except JSON | +| **Distribution** | Any column except primary keys, JSON, or description and comment fields | +| **Sum / Average** | Numeric columns when the query isn't summarized | +| **Distinct values** | Any column when the query isn't summarized | +| **Sum over time** | Numeric columns when the query has a date column and isn't summarized | +| **Extract domain, host…** / **Extract day, month…** | URL, email, and date columns | +| **Combine columns** | Text columns | + +#### Table cells + +| Option | When it appears | +| --------------------------------------------- | -------------------------------------------------------------------------------------------- | +| **Filter by this value** | Any column except primary keys and foreign keys | +| **View details** | Rows that have a primary key | +| **View this [related record]** | Foreign key values | +| **View these [related rows]** | Foreign key values | +| **View these records** | Aggregated values | +| **Break out by [time / location / category]** | Aggregated values | +| **Automatic insights** | Summarized queries, when [X-rays](../../exploration-and-organization/x-rays) are enabled | + +### Charts + +To drill-through a chart, click either: + +* Data points +* Legend items + +> [Pivoted tables](./table#pivoted-tables) behave like charts. Cells in pivoted tables offer the same options as data points. This is different from the [pivot table visualization](./pivot-table), which offers a smaller subset of drill-through options. + +#### Data points + +| Option | When it appears | +| --------------------------------------------- | -------------------------------------------------------------------------------------------- | +| **Filter by this value** | Any column except primary keys and foreign keys | +| **View these records** | Aggregated values | +| **Break out by [time / location / category]** | Aggregated values | +| **Automatic insights** | Summarized queries, when [X-rays](../../exploration-and-organization/x-rays) are enabled | +| **Zoom in** | Histograms, binned charts, and maps | +| **See this [period] by [smaller period]** | Time series | + +On a time series or other chart with a continuous axis, click and drag across a range to filter the question to those values. This works like **Filter by this value**, but for a range of data instead of a single data point. + +#### Legend items + +Clicking the colored circle on a legend item toggles the series on or off. Clicking the label on the legend item opens the drill-through menu. + +Drill-through on a legend item applies to the entire series, not just one data point. For example, clicking **View these records** on a legend item shows all the rows for that series across the whole chart. + +| Option | When it appears | +| --------------------------------------------- | -------------------------------------------------------------------------------------------- | +| **View these records** | Aggregated values | +| **Break out by [time / location / category]** | Aggregated values | +| **Automatic insights** | Summarized queries, when [X-rays](../../exploration-and-organization/x-rays) are enabled | +| **Zoom in** | Histograms, binned charts, and maps | +| **See this [period] by [smaller period]** | Time series | + +## Drill-through and native SQL + +When you create a query with the query builder, Metabase can read and modify your query for any drill-through action. + +When you write a query with the native SQL editor, Metabase runs your query but doesn't parse it. It can modify the results, but it can't modify the query itself. This means you can use results-based drill-through, but not query-rewriting drill-through. For example: + +| Works on native SQL questions | Doesn't work on native SQL questions | +| ----------------------------- | ------------------------------------ | +| **Filter by this value** | **See these records** | +| **Distribution** | **Break out by** | +| **Sort** | **Zoom in** | + +> To use drill-through on a native SQL question, you must save the question. + +For more information, see [drill-through types](#drill-through-types). + +### Make native SQL questions interactive + +Drill-through can't rewrite a native SQL query, but you can still make a native SQL chart interactive using [custom click behavior](../../dashboards/interactive#customizing-click-behavior). Add the question to a dashboard, and set a click behavior on the card. + +A custom click behavior replaces the drill-through menu with an action you define. It can send you to another question, dashboard, external URL, or update a filter on the current dashboard. Set a [dashboard filter](../../dashboards/filters) to the clicked value to scope the destination. + +### Combine native SQL with full drill-through + +If you need native SQL but also want to use the full drill-through menu, write your SQL query as a [transform](../../data-studio/transforms/transforms-overview) and build the user-facing question with the query builder. + +Write the transform's SQL to return the individual records, not summarized results. Build questions on the transform's table with the query builder. These questions support the full drill-through menu. + +Drill-through actions can only reach data that the transform's table contains. + +> To create transforms, you must have transform permissions. If you use Metabase Cloud, you must also have the [transform add-on](../../data-studio/transforms/addons). + +## Drill-through and embedding + +Drill-through behavior depends on the [embedding type](../../embedding/start), because drill-through requires a Metabase user with query permissions. + +| Embedding type | Drill-through | +| ----------------------------------- | ----------------------------------------------------- | +| **Authenticated modular embedding** | Full drill-through, scoped to the user's permissions | +| **Guest modular embeds** | No drill-through | +| **Full app embedding** | Full drill-through | +| **Public embeds** | No drill-through | + +To turn off drill-through in modular embedding, use the **Allow people to drill through on data points** setting when you create the embed. In a dashboard, override drill-through on a single card with [custom click behavior](../../dashboards/interactive). + +Use [modular embedding SDK plugins](../../embedding/sdk/introduction) to customize some drill-through menu options and click behavior in embedded apps. + +## Alternatives to drill-through + +On a dashboard, you can replace drill-through with a different click action: + +- **[Custom click behavior](../../dashboards/interactive#customizing-click-behavior):** Send users to another question, dashboard, external URL, or update a filter on the current dashboard +- **[Cross-filtering](../../dashboards/interactive#use-a-chart-to-filter-a-dashboard):** Update a filter on cards across a dashboard + +Setting one of these alternatives on a card replaces the drill-through menu for that card. diff --git a/_site/docs/v0.62/ai/file-based-development.html b/_site/docs/v0.62/ai/file-based-development.html index 5b4828aca8..f68177b97d 100644 --- a/_site/docs/v0.62/ai/file-based-development.html +++ b/_site/docs/v0.62/ai/file-based-development.html @@ -55,7 +55,7 @@ - + @@ -65,7 +65,7 @@ - + @@ -6234,32 +6234,34 @@

Agent-driven development

-

Metabase content like questions and dashboards can be serialized as YAML files. You can edit those YAML files by hand, sure, but now that we have actual genies, you can just ask them to edit them for you (call it “lamp-rubbing development”).

+

Now that we have actual genies, you can just ask the genies to create the content for you (call it “lamp-rubbing development”).

-

Paired with some skills we’ve developed, you can export your Metabase as YAML files, ask your agent to create new questions and dashboards YAML files, then import that new content into your Metabase. It’s a whole new way to work with Metabase.

+

Give an agent the Metabase CLI, and it can create content for you. But since LLMs can be unpredictable, we recommend developing content in a dev instance of Metabase, then using Remote Sync to get your changes into production.

-

The agent-driven development toolkit

- -

To develop your Metabase content on your local filesystem, we’ve put together a set of tools, including a set of agent skills.

+

With this set up, a typical workflow using an agent with a development instance of Metabase would be:

-
    -
  • Metabase Representation Format: the YAML schema and spec for every Metabase entity (questions, dashboards, collections, transforms, and so on).
    • -
  • Metabase Database Metadata Format: diff-friendly representations of synced databases, their tables, and their fields, as a tree of YAML files.
    • -
  • Export and Import CLI and API endpoints to move serialized content between your local files and Metabase.
    • -
  • Remote Sync (Optional): push content from a Read-write Metabase into a git repo, and pull it into a Read-only Metabase in production.
    • -
+
    +
  1. Prompt the agent with /metabase-cli Create a dashboard based on the sales table.
    2. +
  2. Agent creates questions and a dashboard.
    3. +
  3. View the dashboard in your dev instance.
    4. +
  4. Iterate either in your Metabase or via the agent until you’re happy with the dashboard.
    5. +
  5. Use Remote Sync to push your changes to a repo.
    6. +
  6. Create a PR.
    7. +
  7. Merge the changes.
    8. +
  8. Once merged, your production Metabase pulls in the changes via Remote Sync.
    9. +
-

How content moves between files and Metabase

+

The agent-driven development toolkit

-

You’ll need a way to get YAML files out of Metabase to edit and back into Metabase to verify and ship. There are two options:

+

To develop your Metabase content with an agent, we’ve put together a set of tools.

    -
  • Remote Sync — push and pull from inside Metabase. Requires a Read-write development instance and a Read-only production instance.
    • -
  • Serialization API — curl-based export and import against the /api/ee/serialization/ endpoints.
    • +
  • A Metabase instance to use for development.
    • +
  • Metabase CLI: a command-line client (mb) your agent uses to create content directly in your Metabase. Use the CLI with the /metabase-cli skill.
    • +
  • Metabase Representation Format: the YAML schema and spec for every Metabase entity (questions, dashboards, collections, transforms, and so on). This is the format your content takes once you version it as files.
    • +
  • Remote Sync: push content from a Read-write Metabase into a git repo, and pull it into a Read-only Metabase in production.
-

Pick one before you start the Initial setup; the setup steps differ slightly (Remote Sync doesn’t need a separate API key in production).

-

Initial setup

Some things to put into place to get a workflow going:

@@ -6267,11 +6269,11 @@

Initial setup

  1. Set up a development Metabase
  2. Set up a repository to version your YAML files
    3. -
  3. Add agent skills to your repository
    4. -
  4. Download the database metadata
    5. +
  5. Install and authenticate the Metabase CLI
    6. +
  6. Add the agent skill
-

Once you have these set up, you can step through one of the example workflows.

+

Once you have these set up, you can step through the example workflow.

Set up a development Metabase

@@ -6280,7 +6282,7 @@

Set up a development Metabase

Set up a Metabase instance to check your work before pushing changes to production. This Metabase should connect to the same data warehouse(s) your production Metabase connects to. A config file will come in handy here.

  • -

    Create an API key and assign it to the Admin group. The skills export and import all content and read database metadata, so they need Admin-level access. If you’re using the Serialization API workflow, you’ll also need to create an API key in your production Metabase so you can import your files into it.

    +

    Create an API key in this development Metabase and assign it to the Admin group, so the agent can create content and work with Remote Sync.

  • We also recommend turning off the sample content and usage analytics, so they don’t pollute the data model. If you’re using a docker compose file, add these environment variables:

    @@ -6293,67 +6295,47 @@

    Set up a development Metabase

    Set up a repository to version your YAML files

    -
      -
    1. Initialize a new repo.
      2. -
    2. Add a .gitignore file and add .metabase/ and .env.
      3. -
    3. Add the following to your .env:
      4. -
    - -
       METABASE_URL={your-metabase-url}
-   METABASE_API_KEY={your-api-key}
-
    - -

    Add agent skills to your repository

    - -

    You should add the following skills to your agent so it has context it needs. If you commit the skills into .claude/skills/ in your repo, for example, Claude loads them automatically whenever you run it from that directory.

    - - +

    Create a new git repository for your Metabase content. You’ll point Remote Sync at this repo when you configure it, and clone the repo locally to review changes and open pull requests.

    -

    Download the database metadata

    +

    Install and authenticate the Metabase CLI

    -

    Invoke the metabase-database-metadata skill and ask your agent to fetch the database metadata. The agent will:

    +

    Install the Metabase CLI globally:

    -
      -
    • Check that .env exists. If it doesn’t, the agent will prompt you to create it.
      • -
    • Verify that .env and .metabase/ are in .gitignore, asking before adding them.
      • -
    • Fetch /api/database/metadata into .metabase/metadata.json (raw API response; can be several GB on large warehouses).
      • -
    • Extract a diff-friendly YAML tree to .metabase/databases/<database>/schemas/<schema>/tables/<table>.yaml by running npx @metabase/database-metadata extract-metadata.
      • -
    +
    npm install -g @metabase/cli
+
    -

    The agent can use the YAML extracted to your .metabase directory while creating and editing new questions and dashboards in YAML. That way your agent can refer to real column names, field types, and foreign-key relationships without making live API calls (which would be much slower).

    +

    Then authenticate it against your development Metabase:

    -

    To refresh this database metadata, just ask your agent to re-fetch it.

    +
    mb auth login --url your-metabase-url-here
+
    -

    Example workflows

    +

    Authenticate with the API key you created in your Metabase instance.

    -

    The workflows below both assume you’ve completed the Initial setup.

    +

    Add the agent skill

    -

    Example prompts

    +

    Add the /metabase-cli skill to your agent so it knows how to use the CLI to create content directly in your Metabase.

    -

    Once your repo has the agent skills and a baseline of content, prompt the agent with a structured request:

    +

    Example prompts

    -
    Use the metabase-representation-format and metabase-database-metadata skills to create new YAML files in this directory:
+
    These examples assume you’ve completed the Initial setup. Run the /metabase-cli skill and give the agent a structured request. The agent will run CLI commands to create the content directly in your development Metabase:
    
 
-1. Create a new dashboard called "Support overview" in collections/main/.
-2. Add questions showing total ticket volume, open tickets, and average satisfaction rating.
+
    /metabase-cli Create a new dashboard called "Support overview". Add questions showing total ticket volume, open tickets, and average satisfaction rating.
 
    
 
 
    Or, depending on how capable your model is, try a more open-ended request:
    
 
-
    Use the metabase-representation-format and metabase-database-metadata skills to analyze our support data. Look at the tickets, customers, and interactions tables, and create a dashboard that gives an overview of our team's support workload.
+
    /metabase-cli Analyze our support data. Look at the tickets, customers, and interactions tables, and build a dashboard that gives an overview of our team's support workload.
 
    
 
-
    The agent will read the representation format spec, check existing files for local conventions, consult .metabase/databases/ for real column names, and write new YAML.
    
+
    The agent writes the CLI commands and creates the questions and dashboard for you—just describe what you want.
    
+
+
    Example workflow
    
 
-
    Example workflow with Remote Sync
    
+
    1. Configure Remote Sync on both Metabase instances
    
 
-
    1. Configure Remote Sync on both instances
    
+
    In your development Metabase, configure Remote Sync in Read-write mode pointed at your repo.
    
 
-
    In your development Metabase, configure Remote Sync in Read-write mode pointed at your repo. In production, configure a second Metabase in Read-only mode pointed at the same repo.
    
+
    Set up Remote Sync in your production Metabase in Read-only mode pointed at the same repo.
    
 
 
    2. Create a branch from the Metabase UI
    
 
@@ -6361,207 +6343,43 @@ 
    2. Create a branch from the Meta
 
 
    In your development Metabase, click the branch dropdown at the top and create a new branch for your work, like feature/support-dashboard.
    
 
-
    3. Push existing content to seed the repo
    
-
-
    Click the up arrow (push) icon to commit and push your existing synced collections to the branch.
    
-
-
    4. Clone the repo locally and check out the branch
    
-
-
    git clone your-metabase-repo
-cd your-metabase-repo
-git checkout feature/support-dashboard
-
    
-
-
    5. Ask the agent to edit or create content
    
-
-
    See Example prompts above for prompt patterns to use here.
    
-
-
    6. Validate the YAML files
    
-
-
    Run the schema check after every batch of edits, and optionally run the semantic check at the end of the session. See Validating YAML files below.
    
-
-
    If anything fails, the agent should be able to fix the issue if you give it the error.
    
-
-
    7. Commit and open a pull request
    
-
-
    git add -A
-git commit -m "Add support-overview dashboard"
-git push origin feature/support-dashboard
-
    
-
-
    Open a pull request so your team can review the YAML diff.
    
-
-
    8. Pull the branch into your development Metabase
    
-
-
    Click the pull (down arrow) icon in your development Metabase to load the agent’s changes. Verify the dashboard renders correctly and the questions return expected results.
    
-
-
    9. Merge the PR so production picks up the changes
    
-
-
    If you’ve enabled auto-sync, your production Metabase (in Read-only mode) will pull the new main branch automatically on its next interval. Otherwise, trigger a pull from production manually.
    
-
-
    Example workflow with import and export endpoints
    
-
-
    1. Clone the empty repo and create a branch
    
-
-
    git clone https://github.com/your-org/your-repo.git
-cd your-repo
-git checkout -b feature/support-dashboard
-
    
-
-
    2. Export existing content to seed the repo
    
+
    3. Ask the agent to create content
    
 
-
    The agent does better work when the repo already holds your current Metabase content, so it can see real examples of the Representation Format and your collection conventions. Run the serialization export from inside the clone:
    
+
    Run the /metabase-cli skill and prompt the agent to build your questions and dashboards. The agent creates the content directly in your development Metabase.
    
 
-
    curl \
-  -H 'X-API-Key: YOUR_API_KEY' \
-  -X POST 'https://your-metabase-url/api/ee/serialization/export?data_model=false' \
-  -o metabase_data.tgz
-tar -xzf metabase_data.tgz
-
    
-
-
    Set data_model=false to keep the export small. The agent should get its metadata from the metabase-database-metadata skill instead. For more on export options, see Serialization.
    
-
-
    Commit the extracted YAML so you have a baseline to revert to if the agent goes off the rails.
    
-
-
    3. Ask the agent to edit or create content
    
-
-
    See Example prompts above for prompt patterns to use here.
    
-
-
    4. Validate the YAML files
    
-
-
    Run the schema check after every batch of edits, and optionally run the semantic check at the end of the session. See Validating YAML files below.
    
-
-
    5. Commit and open a pull request
    
-
-
    git add -A
-git commit -m "Add support-overview dashboard"
-git push origin feature/support-dashboard
-
    
-
-
    Then open open a pull request so your team can review the YAML diff.
    
+
    4. Verify the content in your development Metabase
    
 
-
    6. Import the YAML into your development Metabase
    
+
    Open your development Metabase and confirm the dashboard renders correctly and the questions return expected results. Make any changes you want, either in the UI or via the agent.
    
 
-
    Re-bundle the YAML and import it:
    
+
    5. If you make any changes in your Metabase, push the new content to the branch
    
 
-
    tar -czf metabase_data.tgz metabase_data
-curl -X POST \
-  -H 'X-API-Key: YOUR_API_KEY' \
-  -F 'file=@metabase_data.tgz' \
-  'https://your-metabase-url/api/ee/serialization/import' \
-  -o -
-
    
+
    To commit the work, push the change from your Metabase. If you don’t push your changes from your Metabase to your repo, you could lose work the next time you pull changes into that Metabase.
    
 
-
    The -o - flag writes the import response to stdout, so you can see whether the import succeeded and check any warnings. You can ask the agent to generate export.sh and import.sh wrappers so you’re running a single command each time.
    
+
    6. Open a pull request
    
 
-
    Verify the dashboard renders correctly and the questions return expected results.
    
+
    Open a pull request so your team can review the YAML diff. They can also use Remote Sync to pull the branch into a development Metabase and see the changes live.
    
 
-
    7. Repeat the import against production
    
+
    7. Merge the PR so production picks up the changes
    
 
-
    Once you’re confident in the changes, run the same tar + curl import against your production Metabase, using its API key.
    
+
    If you’ve enabled auto-sync, your production Metabase (in Read-only mode) will pull the new main branch automatically on its next interval.
    
 
 
    Undoing the agent’s changes
    
 
-
    If you want to undo the agent’s changes, use git to revert your YAML files to the last known-good commit before pushing or re-importing.
    
-
-
    If you’re using Remote Sync, don’t try to fix things by re-pushing from Metabase: Metabase’s push only reflects its current state and won’t delete any new files the agent created locally.
    
-
-
    Validating YAML files
    
-
-
    Run both checks locally before pushing. The same checks belong in CI — see CI example below.
    
-
-
    Schema check
    
-
-
    You can run a quick schema check:
    
-
-
    npx --yes @metabase/representations validate-schema
-
    
-
-
    The check validates the shape of every YAML file against the Representation Format spec. The metabase-representation-format skill should run this check for you automatically after the agent makes any edits.
    
-
-
    Semantic checker for deeper validation
    
-
-
    
-  
    The semantic checker is only available in the Pro/Enterprise plans.
    
-
    
-
-
    The semantic checker catches things like references to tables that don’t exist or columns the agent invented.
    
-
-
    What it validates beyond schema:
    
+
    Since the agent uses the CLI to create content directly in Metabase, to undo changes, you could either:
    
 
 
      
-  
    • Cross-entity references: collection_id, dashboard_id, parent_id, snippet names, transform tags, card embeddings.
      • 
-  
    • MBQL query compilation: source-table, field references, joins, segments, measures, expressions.
      • 
-  
    • Native-query references: tables, columns, and snippets named in SQL.
      • 
+  
    • Revert to a commit and pull changes: Revert to a previous commit, and pull that commit into your Metabase. Pulling that commit would overwrite any changes you or the agent had made.
      • 
+  
    • Update Metabase and push changes: Edit or archive the content in your Metabase (either manually or via an agent with the CLI), and push the changes to your repo. You may want to pick this approach if you want to keep some, but not all of the changes made by the AI, or if you’ve made additional changes via Metabase’s handy UI that you want to keep.
      • 
 
    
 
-
    If you’ve installed the metabase-semantic-checker skill, just ask the agent to run the semantic checker; the skill picks the right image, passes the right flags, and summarizes the findings.
    
-
-
    You can manually run the semantic checker via Docker like so:
    
-
-
    docker pull metabase/metabase-enterprise:latest
-
-docker run --rm \
-  -v "$PWD:/workspace" \
-  --entrypoint "" \
-  -w /app \
-  metabase/metabase-enterprise:latest \
-  java -jar metabase.jar \
-    --mode checker \
-    --export /workspace \
-    --schema-dir /workspace/.metabase/metadata.json \
-    --schema-format concise
-
    
-
-
    Match the image tag (:latest) to your Metabase build.
    
-
-
    CI example
    
-
-
    You can hook the schema check into GitHub Actions so your team catches problems on the PR, before anyone pulls the changes into Metabase:
    
-
-
    # .github/workflows/schema-check.yml
-name: Schema Check
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-jobs:
-  schema-check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: actions/setup-node@v6.4.0
-        with:
-          node-version: "20"
-
-      - name: Validate representation YAML files
-        run: npx --yes @metabase/representations validate-schema
-
    
-
-
    For the semantic check, add a second workflow that fetches .metabase/metadata.json from your Metabase and then runs the Docker command above against the checkout. If you run the semantic check in more than one workflow (for example, a semantic check and per-PR preview environments), you should probably factor the database metadata fetch to run and cache once a day so you don’t hit the API on every push.
    
-
-
    Deleting content
    
-
-
    Since imports and exports don’t delete content, you’ll need to delete content in the Metabase application itself, then update the YAML files as well.
    
-
-
      
-  
    1. Delete the content in your production Metabase (in the app’s UI).
      2. 
-  
    2. Push (with Remote Sync) or re-export (without) so the change is reflected in the repo.
      3. 
-  
    3. Commit the deletion. That way Metabase won’t recreate the deleted items the next time it pulls.
      4. 
-
    
-
 
    Further reading
    
 
 
 
 
diff --git a/_site/docs/v0.62/ai/overview.html b/_site/docs/v0.62/ai/overview.html
index 89ea3b03a4..4086b8bc2d 100644
--- a/_site/docs/v0.62/ai/overview.html
+++ b/_site/docs/v0.62/ai/overview.html
@@ -6261,7 +6261,7 @@ 
    Agent-driven development workflow
    Best for: developers creating stuff that other people will use.
    
 
-
    Use a coding agent like Claude Code to understand your database’s metadata, generate Metabase content as YAML files locally, verify the schema, then sync and import the generated content into your production Metabase. Sky’s the limit on what you can accomplish.
    
+
    Use a coding agent like Claude Code with the Metabase CLI to create Metabase content directly in a development instance, then version that content as YAML files and pull the changes into your production Metabase.
    
 
 
    Controls: Only admins can sync content to Metabase instances.
    
 
diff --git a/_site/docs/v0.62/configuring-metabase/appearance.html b/_site/docs/v0.62/configuring-metabase/appearance.html
index 85f98dd643..858716ff81 100644
--- a/_site/docs/v0.62/configuring-metabase/appearance.html
+++ b/_site/docs/v0.62/configuring-metabase/appearance.html
@@ -6396,7 +6396,7 @@ 
    Login and unsubscribe pages
    
 
 
    Landing page
    
 
-
    The landing page is what people will see whenever they login. You can set the URL to a collection, question, dashboard or whatever, just make sure that everyone has access to that URL.
    
+
    The illustration people see on the landing page when they log in. To choose which page people land on, see Homepage.
    
 
 
      
   
    • Lighthouse
      • 
diff --git a/_site/docs/v0.62/configuring-metabase/settings.html b/_site/docs/v0.62/configuring-metabase/settings.html
index 04604c4a8b..19f75623af 100644
--- a/_site/docs/v0.62/configuring-metabase/settings.html
+++ b/_site/docs/v0.62/configuring-metabase/settings.html
@@ -6237,11 +6237,15 @@ 
      Redirect to HTTPS
      
   
      Note: if you haven’t set up HTTPS on your server, Metabase will not let you enable HTTPS redirect. Instead, you’ll get a warning saying “It looks like HTTPS is not properly configured.”
      
 
 
-
      Custom homepage
      
+
      Homepage
      
 
-
      Admins can pick a dashboard to serve as the homepage. If people lack permissions to view the selected dashboard, Metabase will redirect them to the default homepage.
      
+
      Set the page people see when they first log in to your Metabase. Choose between:
      
 
-
      To revert to the default Metabase homepage, simply toggle off Custom homepage.
      
+
        
+  
      • Default Metabase home: The standard Metabase homepage.
        • 
+  
      • Dashboard: Pick a dashboard to serve as the homepage. If people lack permissions to view the selected dashboard, Metabase will redirect them to the default homepage.
        • 
+  
      • Custom URL: Send people to a specific URL (a collection, question, dashboard, or other page). Make sure people have access to the URL. This option is only available on Metabase Pro and Enterprise plans.
        • 
+
      
 
 
      Email address for help requests
      
 
diff --git a/_site/docs/v0.62/data-studio/transforms/addons.html b/_site/docs/v0.62/data-studio/transforms/addons.html
index 92c66689b9..bd1360da16 100644
--- a/_site/docs/v0.62/data-studio/transforms/addons.html
+++ b/_site/docs/v0.62/data-studio/transforms/addons.html
@@ -6253,7 +6253,7 @@ 
      Enable basic transforms
      
   
    • 
     
      Metabase Cloud: Basic transform functionality on Metabase Cloud - Starter, Pro, or Enterprise - comes with an additional small fee per successful transform run, see Pricing.
      
 
-    
      Only people logged in with an email of a Metabase Store admins (not just Metabase instance admins) can enable basic transforms. To enable Basic transforms on Metabase Cloud, see Enable transforms.
      
+    
      Only people logged in with an email of a Metabase Store admin (not just Metabase instance admins) can enable basic transforms.
      
   
      • 
 
    
 
@@ -6295,7 +6295,7 @@ 
    Enable Advanced transforms
    
   
  • 
     
    From your Metabase instance: you can navigate to a feature requiring advanced transforms (like Python transforms or transform inspector), and follow the prompts to upgrade.
    
 
-    
    To enable Advanced transforms from your Metabase instance, you need to be logged into the instance with the same email as a Metabase Store admin, because Advanced transform incur an additional charge.
    
+    
    To enable Advanced transforms from your Metabase instance, you need to be logged into the instance with the same email as a Metabase Store admin, because Advanced transform incur an additional charge.
    
   
    • 
   
  • 
     
    From Metabase Store:
    
diff --git a/_site/docs/v0.62/data-studio/transforms/transforms-overview.html b/_site/docs/v0.62/data-studio/transforms/transforms-overview.html
index 02ddad21ca..67c99b8499 100644
--- a/_site/docs/v0.62/data-studio/transforms/transforms-overview.html
+++ b/_site/docs/v0.62/data-studio/transforms/transforms-overview.html
@@ -6283,7 +6283,7 @@ 
    Enable transforms
    
 
 
    Before you can start writing transforms, you’ll need to enable transforms in your Metabase instance.
    
 
-
    If you are on a Metabase Cloud plan, only people logged in with an email of a Metabase Store admins (not just Metabase instance admins) can enable basic transforms, because transforms incur a cost per run on Metabase Cloud.
    
+
    If you’re on a Metabase Cloud plan, only people logged in with an email of a Metabase Store admin (not just Metabase instance admins) can enable basic transforms, because transforms incur a cost per run on Metabase Cloud.
    
 
 
    To enable transforms:
    
 
diff --git a/_site/docs/v0.62/exploration-and-organization/x-rays.html b/_site/docs/v0.62/exploration-and-organization/x-rays.html
index c1965a94eb..5a13ebc892 100644
--- a/_site/docs/v0.62/exploration-and-organization/x-rays.html
+++ b/_site/docs/v0.62/exploration-and-organization/x-rays.html
@@ -6276,7 +6276,7 @@ 
    Disabling X-rays
    
 
 
    If you pin any dashboards in the “Our Analytics” collection, Metabase will hide the X-ray suggestions that appear on the homepage.
    
 
-
    Admins can also manually remove these suggestions by clicking on the Customize button in the upper right and selecting a dashboard as your homepage. Changing the home page won’t disable the X-ray features in the rest of Metabase.
    
+
    Admins can also manually remove these suggestions by clicking on the Customize button in the upper right and selecting a dashboard as your homepage. Changing the home page won’t disable the X-ray features in the rest of Metabase.
    
 
 
         
    
diff --git a/_site/docs/v0.62/index.html b/_site/docs/v0.62/index.html
index 1c1ef4b65c..50bc6a5edb 100644
--- a/_site/docs/v0.62/index.html
+++ b/_site/docs/v0.62/index.html
@@ -6319,7 +6319,8 @@ 
    Installation
    
   
  • Development instances
    • 
   
  • Serialization
    • 
   
  • Remote sync
    • 
-  
  • Commands
    • 
+  
  • Metabase CLI
    • 
+  
  • Metabase JAR commands
    • 
   
  • Supported browsers
    • 
   
  • Privacy
    • 
   
  • About the anonymous usage data we collect
    • 
diff --git a/_site/docs/v0.62/installation-and-operation/commands.html b/_site/docs/v0.62/installation-and-operation/commands.html
index a9d160855e..bacef8128d 100644
--- a/_site/docs/v0.62/installation-and-operation/commands.html
+++ b/_site/docs/v0.62/installation-and-operation/commands.html
@@ -50,12 +50,12 @@
 
 
 
-Metabase CLI | Metabase Documentation
+Metabase JAR commands | Metabase Documentation
 
 
 
-
-
+
+
 
 
 
@@ -64,8 +64,8 @@
 
 
 
-
-
+
+
 
 
 
@@ -6210,9 +6210,13 @@ 
    Other resources
    
 
    
 
 
-        
    Metabase CLI
    
+        
    Metabase JAR commands
    
 
-
    Metabase ships with some handy CLI commands for administration, maintenance, and automation tasks. These commands let you manage your Metabase instance, migrate databases, handle serialization, and generate documentation.
    
+
    
+  
    Looking for the mb command-line client that drives a Metabase instance over its API, on its own or through an AI agent? Check out the Metabase CLI.
    
+
    
+
+
    Metabase ships with some handy commands for administration, maintenance, and automation tasks. These commands run on the server, built into the Metabase JAR, and let you manage your Metabase instance, migrate databases, handle serialization, and generate documentation.
    
 
 
    To view a list of commands, run the Metabase jar followed by help.
    
 
@@ -6403,7 +6407,7 @@ 
    Thanks for your feedback!
    
 
 
 
+
+  
+  
+
+
+
+
+
+Metabase CLI | Metabase Documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+
+  
+
+ 
+
+
+  
+  
+  
+  
+  
+  
+  
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+
+   
+     
+
+
+
+
+
+  
+
+
+   
+
+  
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+    
+  
+
+
+
+  
+  
+  
+
+  
+  
+  
+  
+
+
+
+  
+    
+  
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    
+  
    
+    
+        
+
+
+    
+
+    
    
+      
    
+        
    
+          
+            
+              
+            
+          
+        
    
+
+        
+          
    
+
+          
+
+            
+            
+
+            
+
+            
+
+            
+
+            
    
+              Pricing
+            
    
+          
    
+        
+
+        
    
+          
+            Log in
+          
+
+          Get started
+          
    
+            
+              
+              
+              
+            
+          
    
+        
    
+      
    
+    
    
+    
+
+    
+
+  
    
+
    
+
+
+
+
+
+
+
+    
    
+      
+
+
+
+
    
+  
    
+    
    
+  
+
+  
+
+  
+  
+
+
+  
    Analytics
    
+
+  
+
+  
    Embedding
    
+
+  
+
+  
    Administration
    
+
+  
+
+  
    Other resources
    
+
+  
+
+
+
    
+
+
+    
    
+      
    
+  
    
+    
+      
    
+        
+          
+
+
+
+
+
+
+
+
    
+    
+    
+    
+
    
+
+        
+      
    
+    
+  
    
+
+  
    
+    
+      
+
+
    
+  
+    
+      v0.62
+    
+
+    
+
+
+
+  
+  
+
    
+
+        
+          
+
+          What’s new
+        
+    
+
+    
+      
+
    
+
+
+
+    
+  
    
+
    
+
+
+      
    
+        
+
+        
    
+  
+    
+      
    
+        These are the docs for Metabase v0.62.
+        Check out the docs for the current stable version, Metabase v0.61.
+      
    
+    
+  
+
    
+
+
+        
    Metabase CLI
    
+
+
    The Metabase CLI (mb) is a command-line client for Metabase. mb authenticates against a Metabase instance with an API key and lets you or an AI agent read and write content like questions, dashboards, collections, and transforms over the Metabase API.
    
+
+
    
+  
    Looking for the commands built into the Metabase JAR, like migrate or load-from-h2? Check out Metabase JAR commands.
    
+
    
+
+
    Requirements
    
+
+
      
+  
    • Node.js, to install the CLI from npm.
      • 
+  
    • A Metabase instance on version 58 or later.
      • 
+  
    • An API key to authenticate the CLI against your instance.
      • 
+  
    • A Pro or Enterprise plan for some command groups. For example, git-sync needs the premium Remote sync feature.
      • 
+
    
+
+
    Install the CLI
    
+
+
    npm install -g @metabase/cli
+
    
+
+
    The binary is mb.
    
+
+
    For commands, run:
    
+
+
    mb --help
+
    
+
+
    Authenticate the CLI
    
+
+
    Log in once per Metabase instance.
    
+
+
    mb auth login --url https://metabase.example.com
+
    
+
+
    The CLI prompts for an API key, or reads it from the METABASE_API_KEY environment variable or stdin. To create a key, see API keys.
    
+
+
    Credentials are stored per profile, so you can manage more than one Metabase (like dev and prod Metabases):
    
+
+
    mb auth login --profile prod --url https://prod.example.com
+mb auth list
+
    
+
+
    Add --profile <name> to any command to run it against that instance.
    
+
+
    Use the CLI with an AI agent
    
+
+
    The CLI is built to be driven by an AI coding agent like Claude Code. Instead of running commands yourself, you install a skill and describe what you want in plain language; the agent works out the commands.
    
+
+
    The metabase-cli skill
    
+
+
    The metabase-cli skill teaches your agent the CLI’s conventions. Once installed, you can run:
    
+
+
    /metabase-cli Create a dashboard summarizing this month's signups by plan.
+
    
+
+
    And your agent will go to work, creating content directly in your Metabase via the mb CLI.
    
+
+
    Use the CLI for agent-driven development
    
+
+
    Pair the CLI with version control to build content with an agent in a development Metabase, commit the changes, and pull the changes into your production Metabase. Check out Agent-driven development.
    
+
+
    Further reading
    
+
+
+
+
+        
    
+          
    
+          
+            
    
+              Read docs for other versions of Metabase.
+            
    
+          
+        
    
+      
    
+
+      
    
+        
    
+          
+        
    
+        
    
+  
    
+    
    Was this helpful?
    
+    
+    
+  
    
+
+  
    
+    
    
+
+    
    
+      
+
+      
+    
+  
    
+
+  
    
+    
    Thanks for your feedback!
    
+  
    
+
+  
+    
+      Want to improve these docs? Propose a change.
+    
+  
+
    
+
+
+
+      
    
+	  
    
+  
    
+
    
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+    
    
+
+    
+  
    
+  
+
    
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+
+  
+  
+  
+  
+  
+
+  
+
+
\ No newline at end of file
diff --git a/_site/docs/v0.62/installation-and-operation/start.html b/_site/docs/v0.62/installation-and-operation/start.html
index bb7390f518..eff05be5fa 100644
--- a/_site/docs/v0.62/installation-and-operation/start.html
+++ b/_site/docs/v0.62/installation-and-operation/start.html
@@ -6242,6 +6242,10 @@ 
    Serialization
    
 
 
    Export your questions, dashboards, and more as YAML files that you can check into version control.
    
 
+
    Metabase CLI
    
+
+
    A command-line client that drives a Metabase instance over its API, on its own or through an AI agent.
    
+
 
    Monitoring your Metabase
    
 
 
    Monitor your Metabase with JMX.
    
@@ -6262,9 +6266,9 @@ 
    Accessibility
    
 
 
    Notes on Metabase’s accessibility.
    
 
-
    Command line commands
    
+
    Metabase JAR commands
    
 
-
    Metabase’s CLI.
    
+
    Administrative commands built into the Metabase JAR.
    
 
 
    
 
diff --git a/_site/docs/v0.62/questions/images/drill-through-column-header-menu.png b/_site/docs/v0.62/questions/images/drill-through-column-header-menu.png
new file mode 100644
index 0000000000..58d0607cd3
Binary files /dev/null and b/_site/docs/v0.62/questions/images/drill-through-column-header-menu.png differ
diff --git a/_site/docs/v0.62/questions/visualizations/drill-through.html b/_site/docs/v0.62/questions/visualizations/drill-through.html
new file mode 100644
index 0000000000..c6804141fa
--- /dev/null
+++ b/_site/docs/v0.62/questions/visualizations/drill-through.html
@@ -0,0 +1,6912 @@
+
+  
+  
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+
+  
+  
+
+
+
+
+
+Drill-through | Metabase Documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+
+  
+
+ 
+
+
+  
+  
+  
+  
+  
+  
+  
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+
+   
+     
+
+
+
+
+
+  
+
+
+   
+
+  
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+    
+  
+
+  
+
+  
+
+  
+    
+  
+
+
+
+  
+  
+  
+
+  
+  
+  
+  
+
+
+
+  
+    
+  
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    
+  
    
+    
+        
+
+
+    
+
+    
    
+      
    
+        
    
+          
+            
+              
+            
+          
+        
    
+
+        
+          
    
+
+          
+
+            
+            
+
+            
+
+            
+
+            
+
+            
    
+              Pricing
+            
    
+          
    
+        
+
+        
    
+          
+            Log in
+          
+
+          Get started
+          
    
+            
+              
+              
+              
+            
+          
    
+        
    
+      
    
+    
    
+    
+
+    
+
+  
    
+
    
+
+
+
+
+
+
+
+    
    
+      
+
+
+
+
    
+  
    
+    
    
+  
+
+  
+
+  
+  
+
+
+  
    Analytics
    
+
+  
+
+  
    Embedding
    
+
+  
+
+  
    Administration
    
+
+  
+
+  
    Other resources
    
+
+  
+
+
+
    
+
+
+    
    
+      
    
+  
    
+    
+      
    
+        
+          
+
+
+
+
+
+
+
+
    
+    
+    
+    
+
    
+
+        
+      
    
+    
+  
    
+
+  
    
+    
+      
+
+
    
+  
+    
+      v0.62
+    
+
+    
+
+
+
+  
+  
+
    
+
+        
+          
+
+          What’s new
+        
+    
+
+    
+      
+
    
+
+
+
+    
+  
    
+
    
+
+
+      
    
+        
+
+        
    
+  
+    
+      
    
+        These are the docs for Metabase v0.62.
+        Check out the docs for the current stable version, Metabase v0.61.
+      
    
+    
+  
+
    
+
+
+        
    Drill-through
    
+
+
    Drill-through lets you explore data in your Metabase by clicking a chart, a column header, or a table cell. Each click opens a menu with options like Filter by this value, See these records, Break out by, and Zoom in. Selecting one of these options generates a new query and visualizes the result.
    
+
+
    Drill-through menu
    
+
+
    How drill-through works
    
+
+
    Every drill-through action creates a new query and visualizes the result. Metabase takes the original query and modifies it based on what you click. Switch to the editor to see and edit the new query.
    
+
+
    For example, say a bar chart shows order counts summarized by product category and month. Click the April bar in the Widgets series, then select See these orders. Metabase creates a new question that filters the orders to Widgets in April.
    
+
+
    Some things to keep in mind:
    
+
+
      
+  
    • Drill-through requires query-building permissions. You must have permission to create queries on the underlying data to see the drill-through menu.
      • 
+  
    • The drill-through does not modify the original question. Drill-through creates a new question without overwriting or modifying your original question.
      • 
+  
    • The menu options depend on the type of data you click. Different options appear in the action menu depending on whether you click a chart, a column header, a table cell, or a point on a map.
      • 
+
    
+
+
    Drill-through types
    
+
+
    There are two types of drill-through:
    
+
+
      
+  
    • Results-based drill-through: Metabase takes the data in the query result and filters, distributes, or otherwise transforms it. Example options include Filter by this value, Distribution, and Sort. You can perform results-based drill-through on questions built with the query builder or native SQL.
      • 
+  
    • Query-rewriting drill-through: Metabase modifies your query. Example options include See these records, Break out by, and Zoom in. You can only perform query-rewriting drill-through on questions built with the query builder.
      • 
+
    
+
+
    Drill-through options
    
+
+
    The drill-through menu options depend on what you click and on the underlying data.
    
+
+
    Tables
    
+
+
    To drill-through a table, click either:
    
+
+
      
+  
    • Column headers
      • 
+  
    • Table cells
      • 
+
    
+
+
    Column headers
    
+
+
    Drill-through column header menu
    
+
+
    • + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OptionWhen it appears
    Filter by this columnAny column
    SortAny column except JSON
    DistributionAny column except primary keys, JSON, or description and comment fields
    Sum / AverageNumeric columns when the query isn’t summarized
    Distinct valuesAny column when the query isn’t summarized
    Sum over timeNumeric columns when the query has a date column and isn’t summarized
    Extract domain, host… / Extract day, month…URL, email, and date columns
    Combine columnsText columns
    + +

    Table cells

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OptionWhen it appears
    Filter by this valueAny column except primary keys and foreign keys
    View detailsRows that have a primary key
    View this [related record]Foreign key values
    View these [related rows]Foreign key values
    View these recordsAggregated values
    Break out by [time / location / category]Aggregated values
    Automatic insightsSummarized queries, when X-rays are enabled
    + +

    Charts

    + +

    To drill-through a chart, click either:

    + +
      +
    • Data points
      • +
    • Legend items
      • +
    + +
    +

    Pivoted tables behave like charts. Cells in pivoted tables offer the same options as data points. This is different from the pivot table visualization, which offers a smaller subset of drill-through options.

    +
    + +

    Data points

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OptionWhen it appears
    Filter by this valueAny column except primary keys and foreign keys
    View these recordsAggregated values
    Break out by [time / location / category]Aggregated values
    Automatic insightsSummarized queries, when X-rays are enabled
    Zoom inHistograms, binned charts, and maps
    See this [period] by [smaller period]Time series
    + +

    On a time series or other chart with a continuous axis, click and drag across a range to filter the question to those values. This works like Filter by this value, but for a range of data instead of a single data point.

    + +

    Legend items

    + +

    Clicking the colored circle on a legend item toggles the series on or off. Clicking the label on the legend item opens the drill-through menu.

    + +

    Drill-through on a legend item applies to the entire series, not just one data point. For example, clicking View these records on a legend item shows all the rows for that series across the whole chart.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OptionWhen it appears
    View these recordsAggregated values
    Break out by [time / location / category]Aggregated values
    Automatic insightsSummarized queries, when X-rays are enabled
    Zoom inHistograms, binned charts, and maps
    See this [period] by [smaller period]Time series
    + +

    Drill-through and native SQL

    + +

    When you create a query with the query builder, Metabase can read and modify your query for any drill-through action.

    + +

    When you write a query with the native SQL editor, Metabase runs your query but doesn’t parse it. It can modify the results, but it can’t modify the query itself. This means you can use results-based drill-through, but not query-rewriting drill-through. For example:

    + + + + + + + + + + + + + + + + + + + + + + +
    Works on native SQL questionsDoesn’t work on native SQL questions
    Filter by this valueSee these records
    DistributionBreak out by
    SortZoom in
    + +
    +

    To use drill-through on a native SQL question, you must save the question.

    +
    + +

    For more information, see drill-through types.

    + +

    Make native SQL questions interactive

    + +

    Drill-through can’t rewrite a native SQL query, but you can still make a native SQL chart interactive using custom click behavior. Add the question to a dashboard, and set a click behavior on the card.

    + +

    A custom click behavior replaces the drill-through menu with an action you define. It can send you to another question, dashboard, external URL, or update a filter on the current dashboard. Set a dashboard filter to the clicked value to scope the destination.

    + +

    Combine native SQL with full drill-through

    + +

    If you need native SQL but also want to use the full drill-through menu, write your SQL query as a transform and build the user-facing question with the query builder.

    + +

    Write the transform’s SQL to return the individual records, not summarized results. Build questions on the transform’s table with the query builder. These questions support the full drill-through menu.

    + +

    Drill-through actions can only reach data that the transform’s table contains.

    + +
    +

    To create transforms, you must have transform permissions. If you use Metabase Cloud, you must also have the transform add-on.

    +
    + +

    Drill-through and embedding

    + +

    Drill-through behavior depends on the embedding type, because drill-through requires a Metabase user with query permissions.

    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Embedding typeDrill-through
    Authenticated modular embeddingFull drill-through, scoped to the user’s permissions
    Guest modular embedsNo drill-through
    Full app embeddingFull drill-through
    Public embedsNo drill-through
    + +

    To turn off drill-through in modular embedding, use the Allow people to drill through on data points setting when you create the embed. In a dashboard, override drill-through on a single card with custom click behavior.

    + +

    Use modular embedding SDK plugins to customize some drill-through menu options and click behavior in embedded apps.

    + +

    Alternatives to drill-through

    + +

    On a dashboard, you can replace drill-through with a different click action:

    + +
      +
    • Custom click behavior: Send users to another question, dashboard, external URL, or update a filter on the current dashboard
      • +
    • Cross-filtering: Update a filter on cards across a dashboard
      • +
    + +

    Setting one of these alternatives on a card replaces the drill-through menu for that card.

    + + +
    +
    + +

    + Read docs for other versions of Metabase. +

    + +
    + + +
    +
    + +
    +
    +
    +
    Was this helpful?
    + + +
    + +
    +

    + +
    + + + +
    +
    + +
    +
    Thanks for your feedback!
    +
    + + + + Want to improve these docs? Propose a change. + + +
    + + + +
    + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file