# MD_CREATE_DIVE
> Create a new Dive in your MotherDuck workspace.
Creates a new [Dive](/key-tasks/ai-and-motherduck/dives) and returns its summary along with the initial version. The initial version (version `1`) is captured from `content`, `description`, `api_version`, and `required_resources`.

Unlike the [`save_dive` MCP tool](/sql-reference/mcp/dives/save-dive), `MD_CREATE_DIVE` does not validate the component code or analyze which databases it queries — the content is stored as-is. Follow the component contract from [`get_dive_guide`](/sql-reference/mcp/dives/get-dive-guide) to produce content that renders in the Dive viewer.

## Syntax

```sql
SELECT * FROM MD_CREATE_DIVE(
    title := 'my_dive',
    content := '<jsx_source>',
    description := 'What this Dive shows',
    required_resources := [{'url': 'md:my_db', 'alias': 'my_db'}]
);
```

Function arguments accept literals and `getvariable()` calls. Subqueries and lateral column references are rejected, so store dynamic values with `SET VARIABLE` first.

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `title` | `VARCHAR` | Yes | Human-readable Dive title. |
| `content` | `VARCHAR` | Yes | JSX/React source for the Dive: a single component with a default export, using `useSQLQuery` for live queries. |
| `description` | `VARCHAR` | No | A brief description of the Dive. |
| `required_resources` | `LIST(STRUCT(url VARCHAR, alias VARCHAR))` | No | Databases and shares the Dive queries, so the Dive viewer can attach them. `url` is a database (`md:<database_name>`) or share (`md:_share/<name>/<uuid>`) URL; `alias` is the name the Dive's SQL uses to reference it. |
| `api_version` | `UINTEGER` | No | Dive API version of the content. Defaults to `1`. |

## Return columns

| Column | Type | Description |
|---|---|---|
| `id` | `UUID` | Unique identifier of the created Dive. |
| `title` | `VARCHAR` | The Dive title. |
| `description` | `VARCHAR` | The Dive description, or `NULL`. |
| `owner_id` | `UUID` | Identifier of the owning user. |
| `current_version` | `INTEGER` | Always `1` for a newly created Dive. |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | Creation timestamp. |
| `updated_at` | `TIMESTAMP WITH TIME ZONE` | Last update timestamp. |
| `owner_name` | `VARCHAR` | Username of the owner. |
| `version_id` | `UUID` | Identifier of the initial version. |
| `version_storage_url` | `VARCHAR` | Internal storage location of the version's content. |
| `version_description` | `VARCHAR` | Description attached to the version, or `NULL`. |
| `version_created_at` | `TIMESTAMP WITH TIME ZONE` | When the version was created. |
| `version_api_version` | `UINTEGER` | Dive API version of the content. |
| `version_required_resources` | `LIST(STRUCT(name VARCHAR, alias VARCHAR, url VARCHAR, id UUID, resource_type VARCHAR))` | The resolved resources: each input `url` is resolved to its `name`, `id`, and `resource_type` (`database` or `share`). |

## Examples

Minimal Dive:

```sql
SELECT id, title, current_version
FROM MD_CREATE_DIVE(
    title := 'Hello Dive',
    content := 'export default function Dive() {
  return <div>Hello from SQL</div>;
}'
);
```

A Dive querying a database, with the resource declared so viewers can attach it:

```sql
SELECT id
FROM MD_CREATE_DIVE(
    title := 'Daily orders',
    description := 'Order counts by day over the last 30 days',
    content := $$
import { useSQLQuery } from "@motherduck/react-sql-query";

export default function Dive() {
  const { data, isLoading } = useSQLQuery(`
    SELECT order_date, COUNT(*) AS orders
    FROM analytics.main.orders
    WHERE order_date > now() - INTERVAL 30 DAY
    GROUP BY ALL ORDER BY 1
  `);
  if (isLoading) return <div>Loading…</div>;
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}
$$,
    required_resources := [{'url': 'md:analytics', 'alias': 'analytics'}]
);
```

## Related

- [`MD_UPDATE_DIVE_CONTENT`](../md-update-dive-content) — Publish a new version of the component code.
- [`MD_UPDATE_DIVE_METADATA`](../md-update-dive-metadata) — Rename or re-describe a Dive.
- [`MD_DELETE_DIVE`](../md-delete-dive) — Delete a Dive.
- [`save_dive` MCP tool](/sql-reference/mcp/dives/save-dive) — AI-agent equivalent, with content validation.


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fmotherduck-sql-reference%2Fdives%2Fmd-create-dive%2F&page_title=MD_CREATE_DIVE&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.