save_dive

Public Preview

Dives are currently in public preview and functionality is subject to change.

Save a new Dive to MotherDuck. Returns a URL to the Dive in MotherDuck as a link that the user can click to view the Dive.

Description

The save_dive tool creates a new Dive in your MotherDuck workspace. It accepts a title, optional description, and the JSX/React component code. Before saving, the tool validates the code to check for common issues like invalid SQL queries or missing exports.

After saving, the tool analyzes which databases the Dive queries. If any referenced databases are not yet shared with your organization, it prompts you to use share_dive_data so others in your organization can view the Dive.

Call get_dive_guide first to learn the required JSX/React format.

Input Parameters

Parameter	Type	Required	Description
title	string	Yes	The title of the Dive
description	string	No	A brief description of the Dive
content	string	Yes	The JSX/React component code for the Dive

Output Schema

{
  "success": boolean,
  "dive": {                        // Created dive info (on success)
    "id": string,                  // Unique identifier (UUID)
    "title": string,               // Dive title
    "description": string | null   // Dive description
  },
  "dive_url": string,              // URL to view the Dive (on success)
  "warnings": string[],            // Validation warnings (if any)
  "database_warnings": string[],   // Warnings from database analysis (if any)
  "unshared_databases": string[],  // Database names not yet shared with the org (if any)
  "next_steps": string[],          // Ordered instructions for the AI to follow after saving
  "error": string,                 // Error message (on failure)
  "validationErrors": [            // Validation errors (on failure)
    {
      "type": string,              // Error type
      "message": string,           // Error description
      "details": string            // Additional details
    }
  ]
}

Example Usage

Create a new Dive:

Create a Dive showing monthly revenue trends for my analytics database

The AI assistant will first call get_dive_guide to load the instructions, then call save_dive:

{
  "title": "Monthly Revenue Trends",
  "description": "Line chart showing revenue by month with year-over-year comparison",
  "content": "import { useSQLQuery } from \"@motherduck/react-sql-query\";\nimport { LineChart, Line, XAxis, YAxis, Tooltip, ResponsiveContainer } from \"recharts\";\n\nexport default function Dive() {\n  const { data, isLoading, isError, error } = useSQLQuery(`\n    SELECT DATE_TRUNC('month', order_date) as month, SUM(revenue) as revenue\n    FROM analytics.sales\n    GROUP BY 1 ORDER BY 1\n  `);\n  // ... component code\n}"
}

Success Response Example

{
  "success": true,
  "dive": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Monthly Revenue Trends",
    "description": "Line chart showing revenue by month with year-over-year comparison"
  },
  "dive_url": "https://app.motherduck.com/dives/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "unshared_databases": ["analytics"],
  "next_steps": [
    "Regenerate the dive preview artifact with the updated banner...",
    "Show the dive to the user in chat as a markdown hyperlink: [Monthly Revenue Trends](https://app.motherduck.com/dives/a1b2c3d4-...)",
    "The dive references databases not yet shared with the organization: analytics. Ask the user if they want to share them."
  ]
}

Validation Error Response Example

{
  "success": false,
  "error": "Dive validation failed",
  "validationErrors": [
    {
      "type": "SQL_ERROR",
      "message": "Query validation failed: Table 'analytics.nonexistent_table' not found",
      "details": "SELECT * FROM analytics.nonexistent_table"
    }
  ],
  "hint": "Please fix the errors above and try again."
}