MD_CREATE_DIVE

Creates a new Dive 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, 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 to produce content that renders in the Dive viewer.

Syntax

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:

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:

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 — Publish a new version of the component code.
• MD_UPDATE_DIVE_METADATA — Rename or re-describe a Dive.
• MD_DELETE_DIVE — Delete a Dive.
• save_dive MCP tool — AI-agent equivalent, with content validation.