Skip to main content

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​