MD_UPDATE_DIVE_CONTENT

Publishes a new version of an existing Dive. Every call creates a fresh version with the supplied content and increments the Dive's current_version; earlier versions remain readable through MD_GET_DIVE_VERSION.

To change the Dive's title or description without creating a new version, use MD_UPDATE_DIVE_METADATA instead.

Syntax

SELECT * FROM MD_UPDATE_DIVE_CONTENT(
    id := '<dive_id>',
    content := '<updated_jsx_source>',
    description := 'What changed in this version',
    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
id	UUID	Yes	Identifier of the Dive to update.
content	VARCHAR	Yes	New JSX/React source for the Dive.
description	VARCHAR	No	Description attached to this version (separate from the Dive's own description). Useful as a change note.
required_resources	LIST(STRUCT(url VARCHAR, alias VARCHAR))	No	Databases and shares the new content queries. Replaces the previous version's list; resources are not carried forward, so pass the full list each time.
api_version	UINTEGER	No	Dive API version of the content. Defaults to 1.

Return columns

Returns the newly created version:

Column	Type	Description
id	UUID	Identifier of the new version (not the Dive).
version	UINTEGER	The new version number.
storage_url	VARCHAR	Internal storage location of the version's content.
description	VARCHAR	The version description, or NULL.
created_at	TIMESTAMP WITH TIME ZONE	When the version was created.
api_version	UINTEGER	Dive API version of the content.
required_resources	LIST(STRUCT(name VARCHAR, alias VARCHAR, url VARCHAR, id UUID, resource_type VARCHAR))	The resolved resources for this version.

Examples

Publish a new version with a change note:

SELECT version, created_at
FROM MD_UPDATE_DIVE_CONTENT(
    id := '<dive_id>',
    content := $$
import { useSQLQuery } from "@motherduck/react-sql-query";

export default function Dive() {
  const { data } = useSQLQuery(`SELECT COUNT(*) AS n FROM analytics.main.orders`);
  return <div>Orders: {data?.[0]?.n}</div>;
}
$$,
    description := 'Switch from daily breakdown to a single total',
    required_resources := [{'url': 'md:analytics', 'alias': 'analytics'}]
);

Related

• MD_CREATE_DIVE — Create a Dive.
• MD_LIST_DIVE_VERSIONS — Browse the version history.
• MD_GET_DIVE_VERSION — Read an older version's content.
• update_dive MCP tool — AI-agent equivalent, with content validation.