Dives functions

SQL table functions for managing Dives, MotherDuck's interactive visualizations. Use these functions from any MotherDuck client (DuckDB CLI, a CI pipeline, or a Flight) to create, update, version, and delete Dives without leaving SQL — the foundation of a Dives-as-code workflow.

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 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:

-- 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

MD_CREATE_DIVE

Create a new Dive in your MotherDuck workspace.

MD_LIST_DIVES

List all Dives in your MotherDuck account with pagination support.

MD_GET_DIVE

Retrieve a Dive by ID including its full React component content.

MD_UPDATE_DIVE_CONTENT

Publish a new version of a Dive's component code.

MD_UPDATE_DIVE_METADATA

Update a Dive's title or description without creating a new version.

MD_DELETE_DIVE

Delete a Dive and its version history.

MD_UPDATE_DIVE_STATUS

Set a Dive's governance status (draft, ready, endorsed, or archived).

MD_GET_DIVE_VERSION

Fetch the content of a specific Dive version.

MD_LIST_DIVE_VERSIONS

List the version history of a Dive.

useSQLQuery hook

React hook for querying MotherDuck data from within Dives.

useDiveState hook

React hook for storing shareable UI state in MotherDuck Dives.