---
sidebar_position: 3
title: Creating Visualizations with Dives
description: Build interactive visualizations from natural language using AI agents and the MotherDuck MCP Server
feature_stage: preview
---
import VideoPlayer from '@site/src/components/VideoPlayer';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Dives are interactive visualizations you create with natural language, directly on top of your data in MotherDuck. Ask a question to your AI agent, and MotherDuck generates a persistent, interactive component that lives in your workspace alongside your SQL.
Think of Dives as a bridge between one-off questions and always-up-to-date dashboards. Instead of building a full dashboard or writing complex queries, you can ask a question and save the answer as a Dive that stays current with your data.
## How Dives work
When you create a Dive with the [MotherDuck MCP](/sql-reference/mcp/) through an AI agent:
1. You ask a question in natural language (e.g., "Show me monthly revenue trends by product category")
2. The AI agent queries your MotherDuck database through the [MCP Server](/sql-reference/mcp/) to understand the data
3. The agent creates an interactive visualization, with the necessary SQL to query the data
4. MotherDuck saves the Dive to your workspace
Dives use MotherDuck's [hypertenancy](/concepts/hypertenancy) architecture to serve sub-second queries. Every user gets dedicated compute, so there's no slowdown when your whole team explores data at once.
## Prerequisites
To create a Dive, you will need:
- A MotherDuck account with at least one database
- An [AI client](/docs/getting-started/mcp-getting-started/) connected to the [MotherDuck MCP Server](/key-tasks/ai-and-motherduck/mcp-setup/) (Claude, ChatGPT, Cursor, or others)
Dives are available on all MotherDuck plans at no additional charge.
## Creating a Dive
Connect your AI assistant to the MotherDuck MCP Server, then ask it to create a visualization. The key is to ask for a "Dive" specifically as this tells the agent to persist the visualization in your MotherDuck workspace.
**Example prompts:**
- *"Create a Dive showing monthly revenue trends for the last 12 months"*
- *"Make a Dive that breaks down customer sign-ups by region"*
- *"Build a Dive with a chart of our top 10 products by sales volume. Use MotherDuck's brand colors"*
The AI agent handles the SQL, chart configuration, styling and saving. You just describe what you want to see.
### Iterating on a Dive
Once you have a Dive, you can refine it through conversation:
- *"Add a filter for the US region only"*
- *"Change the chart to a stacked bar chart"*
- *"Add a trend line to show the overall direction"*
Each update modifies the Dive in place, keeping your visualization current.
## Finding your Dives
Dives appear in two places in the MotherDuck UI:
### Object explorer
Your recent Dives appear in the left sidebar, above your Notebooks. Click any Dive to load it in the main view. The list shows your most recent Dives first.
### Settings page
For a complete list of all Dives in your organization, go to **Settings** → **Dives**. This view makes it easier to find Dives created by others in your team.
## Sharing Dives with your team
When you save a Dive, the AI agent checks whether the databases it queries are shared with your organization. If not, it will suggest sharing them so your team can view the Dive. You can also explicitly ask:
> *"Share the data for my revenue Dive with my team"*
This creates org-scoped shares for any private databases referenced in the Dive's queries and updates the Dive to use the shared references. See [`share_dive_data`](/sql-reference/mcp/share-dive-data) for details.
## Version history
Every time you update a Dive, MotherDuck saves a version. You can browse previous versions directly in the MotherDuck UI using the version picker in the top-right corner of a Dive. The dropdown shows each version with its description and when it was created.
Selecting a previous version lets you view what the Dive looked like at that point. Version browsing is read-only: switching to an older version does not overwrite the latest version.
You can also retrieve versions programmatically. Use [`list_dives`](/sql-reference/mcp/list-dives) to see the `current_version` for each Dive, and [`read_dive`](/sql-reference/mcp/read-dive) with the `version` parameter to inspect a specific version.
## What makes Dives different
Unlike traditional dashboards:
- **Natural language creation**: Describe what you want in plain English instead of clicking through a UI or writing visualization code
- **Always current**: Dives query live data—no manual refreshes or stale snapshots
- **Workspace-native**: Dives live alongside your SQL in MotherDuck, not in a separate tool
- **Instant exploration**: Filter, drill down, and explore without waiting for queries to run
Unlike one-off AI-generated charts:
- **Persistent**: Dives save to your workspace so you can return to them anytime
- **Shareable**: Team members can view and interact with Dives you create—[share the underlying data](/sql-reference/mcp/share-dive-data) to give them access
- **Interactive**: Filter and explore the data, not just view a static image
## Walkthrough: Building a Dive step by step
Connect the [MotherDuck MCP Server](/sql-reference/mcp/) to Claude for desktop or Claude on the web, then open a new conversation.
**Step 1: Explore your data**
Don't ask for a finished Dive right away. Start vague: *"Take a look at what tables I have in my analytics database."* Claude lists tables, reads column names, samples rows, and figures out how things connect. Doing this first saves you from chasing down SQL errors later.
When it reports back, keep asking questions. *"How do the orders and customers tables connect? What date range am I working with?"* The more Claude knows about your schema upfront, the fewer corrections you'll need.
**Step 2: Shape the analysis**
Point Claude at what you want to see.
If you're not sure what to look for, go open-ended: *"What are the most interesting patterns in this data?"* Claude runs queries and pulls out trends you might have missed.
If you already have something in mind, say so: *"I want to see how revenue breaks down by product category over the last 12 months."* You can also paste in a SQL query or a screenshot of a dashboard you want to recreate.
Mention specifics like calculated columns, filters, or date ranges before asking Claude to build the Dive.
**Step 3: Iterate on the artifact**
Claude shows a preview in the chat before publishing to MotherDuck.
Explain *why* you want a change, not just *what*. *"I want to spot outliers quickly"* gives Claude more to work with than *"make the dots bigger."* Group related tweaks into one message. Keep unrelated changes separate. If something isn't working after two or three rounds, try a different approach. If you know what you want to change specifically, go ahead and do it.
Even beyond the charts and visuals themselves, there are so many ways to enhance your Dive. Every type of custom interaction you've seen on the web is available to you. Ask for features like drill downs, cross-filtering, zooming, and more.
You don't have to finish in one sitting.
**Step 4: Publish to MotherDuck**
Tell Claude to save it: *"Save this as a Dive in MotherDuck."*
The Dive runs against live data. Find it in the [Object Explorer sidebar](#object-explorer) or on the [Settings page](#settings-page), share it with your team, and come back to Claude when you want to change anything.
Claude Code can allow you to iterate very quickly when building Dives. With Claude Code, you can preview your changes in a local environment for instant feedback loops - and Claude can get that environment set up for you!
To get started, connect the [MotherDuck MCP Server](/sql-reference/mcp/) to Claude Code, then open a new conversation.
**Step 1: Explore your data**
Don't ask for a finished Dive right away. Start vague: *"Take a look at what tables I have in my analytics database."* Claude lists tables, reads column names, samples rows, and figures out how things connect. Doing this first saves you from chasing down SQL errors later.
When it reports back, keep asking questions. *"How do the orders and customers tables connect? What date range am I working with?"* The more Claude knows about your schema upfront, the fewer corrections you'll need.
**Step 2: Shape the analysis**
Point Claude at what you want to see.
If you're not sure what to look for, go open-ended: *"What are the most interesting patterns in this data?"* Claude runs queries and pulls out trends you might have missed.
If you already have something in mind, say so: *"I want to see how revenue breaks down by product category over the last 12 months."* You can also paste in a SQL query or a screenshot of a dashboard you want to recreate.
Mention specifics like calculated columns, filters, or date ranges before asking Claude to build the Dive.
**Step 3: Create a Dive local preview**
Next, ask Claude to create a Dive based on your analysis thus far and any other open questions on your mind. Claude will ask if you would like to see a local preview, and if you accept, the MotherDuck MCP will give Claude the instructions to set up a preview on your local machine.
To set up the preview, Claude will make some local folders and run some npm commands, and after a moment your environment will be ready. You will receive a message like this:
> `The preview is running at http://localhost:5177/.`
> `Open that in your browser to see the Dive with live data from MotherDuck.`
So, cmd + click on that localhost URL (or ctrl + click if you are in Windows), and you'll have a live preview in your browser of the Dive you just created.
**Step 4: Iterate with the preview**
Now you get to tap into the power of Agents for follow up analysis and enhancing the visual.
Explain *why* you want a change, not just *what*. *"I want to spot outliers quickly"* gives Claude more to work with than *"make the dots bigger."* Group related tweaks into one message. Keep unrelated changes separate. If something isn't working after two or three rounds, try a different approach. If you know what you want to change specifically, go ahead and do it.
Feel free to keep questions open ended. Things like, *"What other columns are correlated with revenue? What other interesting patterns should I investigate?"* can let Claude uncover hidden patterns on your behalf.
Even beyond the charts and visuals themselves, there are so many ways to enhance your Dive. Every type of custom interaction you've seen on the web is available to you. Ask for features like drill downs, cross-filtering, zooming, and more.
**Step 5: Publish to MotherDuck**
Tell Claude to save it: *"Save this as a Dive in MotherDuck."*
The Dive runs against live data. Find it in the [Object Explorer sidebar](#object-explorer) or on the [Settings page](#settings-page), share it with your team, and come back to Claude when you want to change anything.
Connect the [MotherDuck MCP Server](/sql-reference/mcp/) to ChatGPT and follow the general steps in [Creating a Dive](#creating-a-dive). The workflow is similar to the Claude Desktop/Web tab: explore your data, shape the analysis, then ask ChatGPT to save the result as a Dive.
Connect the [MotherDuck MCP Server](/sql-reference/mcp/) to Cursor and follow the general steps in [Creating a Dive](#creating-a-dive). The workflow is similar to the Claude Code tab: explore your data, shape the analysis, preview locally, then publish the Dive to MotherDuck.
## Tips for better Dives
### Be specific about the visualization
Include details about chart type, time ranges, and groupings:
| Less effective | More effective |
|----------------|----------------|
| "Show me sales data" | "Create a Dive with a line chart of weekly sales for 2024, broken down by product category" |
| "Make a customer chart" | "Build a Dive showing customer count by signup month as a bar chart" |
### Use your schema knowledge
If you know your table and column names, include them:
> "Create a Dive from the `orders` table showing `total_amount` by `order_date`, grouped by month"
### Start simple, then iterate
Begin with a basic visualization, then add complexity:
1. *"Create a Dive showing revenue by month"*
2. *"Add a breakdown by region"*
3. *"Filter to show only the top 5 regions"*
## Troubleshooting
| Issue | Solution |
|-------|----------|
| AI creates a chart but doesn't save it as a Dive | Explicitly ask to "create a Dive" or "save this as a Dive in MotherDuck" |
| Dive shows unexpected data | Ask the AI to explain the query it used, then refine your request |
| Can't find a Dive | Check **Settings** → **Dives** for the complete list |
| Dive is slow to load | The underlying query may be scanning a lot of data—ask the AI to add filters or optimize |
## Declaring required databases
When your Dive queries a database that viewers might not have attached, export a `REQUIRED_DATABASES` constant from your component. MotherDuck automatically attaches these databases (including shared databases) before running any queries, so your teammates don't see "Catalog does not exist" errors.
```jsx
export const REQUIRED_DATABASES = [
{
type: 'share',
path: 'md:_share//',
alias: ''
}
];
```
Each entry describes one database:
| Field | Description |
|-------|-------------|
| `type` | `"share"` for shared databases, `"database"` for owned databases |
| `path` | The share URL (for example, `md:_share/galactic_coffee/af03aa17-...`) or database name |
| `alias` | The local alias used in your SQL queries |
You can find your share URLs by running `FROM MD_INFORMATION_SCHEMA.OWNED_SHARES;` or by asking the AI agent to use the [`share_dive_data`](/sql-reference/mcp/share-dive-data) tool.
This approach is preferred over calling `ATTACH` inside `useSQLQuery`, because it lets MotherDuck handle the attachment before any data queries fire.
## Related resources
- [Embedding Dives in your website](/key-tasks/ai-and-motherduck/dives/embedding-dives)
- [Dives SQL Functions](/sql-reference/motherduck-sql-reference/ai-functions/dives/) — Manage Dives directly from SQL
- [`useSQLQuery` hook](/sql-reference/motherduck-sql-reference/ai-functions/dives/use-sql-query) — React hook reference for querying data inside Dives
- [Connect to MCP Server](/key-tasks/ai-and-motherduck/mcp-setup/) — Set up the MCP server with your AI assistant
- [MCP Workflows](/key-tasks/ai-and-motherduck/mcp-workflows/) — Tips for effective AI-powered data analysis
- [AI Features in MotherDuck](/docs/key-tasks/ai-and-motherduck/ai-features-in-ui/) — Explore instant SQL and automatic SQL fixes.