# Dives functions
> SQL table functions for creating, updating, versioning, and deleting MotherDuck Dives.
SQL table functions for managing [Dives](/key-tasks/ai-and-motherduck/dives), MotherDuck's interactive visualizations. Use these functions from any MotherDuck client (DuckDB CLI, a CI pipeline, or a [Flight](/concepts/flights)) to create, update, version, and delete Dives without leaving SQL — the foundation of a [Dives-as-code workflow](/key-tasks/ai-and-motherduck/dives/managing-dives-as-code).

The MCP server exposes the same operations to AI agents through `save_dive`, `update_dive`, `list_dives`, and so on. The MCP tools also validate the Dive content and analyze which databases it queries before saving; the SQL functions store content as-is. See the [MCP reference](/sql-reference/mcp/) for the agent-facing tools.

:::note
These functions execute server-side on MotherDuck. They are not available on local-only DuckDB connections.
:::

A minimal end-to-end Dive from SQL:

```sql
-- Create the Dive
SELECT id, current_version
FROM MD_CREATE_DIVE(
    title := 'Revenue overview',
    content := $$
import { useSQLQuery } from "@motherduck/react-sql-query";

export default function Dive() {
  const { data } = useSQLQuery(`SELECT SUM(revenue) AS total FROM analytics.sales`);
  return <div>Total revenue: {data?.[0]?.total}</div>;
}
$$
);

-- Publish a new version of the component code
SELECT version
FROM MD_UPDATE_DIVE_CONTENT(
    id := '<dive_id>',
    content := '<updated_jsx_source>'
);

-- Inspect the version history
SELECT version, created_at
FROM MD_LIST_DIVE_VERSIONS(id := '<dive_id>');
```

## Available functions

## Included pages

- [MD_CREATE_DIVE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/dives/md-create-dive): Create a new Dive in your MotherDuck workspace.
- [MD_LIST_DIVES](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/dives/md-list-dives): List all Dives in your MotherDuck account with pagination support.
- [MD_GET_DIVE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/dives/md-get-dive): Retrieve a Dive by ID including its full React component content.
- [MD_UPDATE_DIVE_CONTENT](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/dives/md-update-dive-content): Publish a new version of a Dive's component code.
- [MD_UPDATE_DIVE_METADATA](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/dives/md-update-dive-metadata): Update a Dive's title or description without creating a new version.
- [MD_DELETE_DIVE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/dives/md-delete-dive): Delete a Dive and its version history.
- [MD_UPDATE_DIVE_STATUS](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/dives/md-update-dive-status): Set a Dive's governance status (draft, ready, endorsed, or archived).
- [MD_GET_DIVE_VERSION](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/dives/md-get-dive-version): Fetch the content of a specific Dive version.
- [MD_LIST_DIVE_VERSIONS](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/dives/md-list-dive-versions): List the version history of a Dive.
- [useSQLQuery hook](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/dives/use-sql-query): React hook for querying MotherDuck data from within Dives.
- [useDiveState hook](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/dives/use-dive-state): React hook for storing shareable UI state in MotherDuck Dives.


---

## 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%2F&page_title=Dives%20functions&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.