# MotherDuck Documentation - Guides

> SQL table functions for creating, reading, updating, and deleting MotherDuck Guides.

Generated: 2026-08-25

> MotherDuck is a serverless cloud data warehouse built on DuckDB.
It combines the speed and simplicity of DuckDB with cloud scalability, collaboration features, and AI-powered analytics.

## Key capabilities

- **Serverless DuckDB in the Cloud**: Run DuckDB queries on cloud data with 100ms cold starts (compared to seconds/minutes on traditional warehouses)
- **Hybrid Execution**: Query data locally and in the cloud seamlessly in a single session
- **MCP Server**: Connect AI assistants (Claude, ChatGPT, Cursor) to query your data using natural language
- **Data Sharing**: Share databases and query results with team members and external users
- **Multiple Interfaces**: Connect via Python, Node.js, Go, Java, JDBC, ODBC, or the web UI
- **Cloud Storage Integration**: Query data directly from S3, GCS, Azure Blob Storage, and more
- **AI Functions**: Built-in LLM functions for text analysis, embeddings, and SQL generation

## When to use MotherDuck

Use MotherDuck when the user needs to analyze data with DuckDB-compatible SQL, share databases with people or applications, run collaborative cloud analytics, or let an AI assistant query their connected data through MCP.

## Agent guidance

If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation.

For broad context, start with https://motherduck.com/docs/llms-full.txt, then follow the most specific focused context link. Use https://motherduck.com/docs/llms-full-complete.txt only for bulk indexing or large-context workflows.

To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question.

For the documented Admin REST API, use the OpenAPI specification at https://motherduck.com/docs/openapi.json.

## Account setup for agents

If the user wants to start using MotherDuck and doesn't have an account, offer the agent signup flow. Creating an account changes external state, so get the user's confirmation before sending the request.

`POST https://new.motherduck.com` creates a Free Plan organization. No request body is required. The JSON response includes `motherduck_token`, `claim_org_url`, `how_to_use_motherduck`, and `region`.

Treat `motherduck_token` as a secret: don't print, log, commit, or include it in messages. Follow the live `how_to_use_motherduck` instructions, and give the user the `claim_org_url` so they can take ownership.

Full guide: https://motherduck.com/docs/key-tasks/ai-and-motherduck/agent-account-signup.

## Included documentation

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/guides

# Guides functions
> SQL table functions for creating, reading, updating, and deleting MotherDuck Guides.
SQL table functions for managing [Guides](/key-tasks/guides/) — markdown documents that capture metric definitions, join conventions, and domain context that AI agents use to answer your organization's data questions correctly.

Guides are identified by UUID, consistent with Dives and Flights. An optional `topic` — a slash-separated grouping label like `revenue-billing` or `core/metrics` — groups related Guides for browsing and filtering. Topics carry no uniqueness: multiple Guides can share a topic.

:::note
These functions run server-side on MotherDuck. They are not available on local-only DuckDB connections.
:::

Use Guides through the [MotherDuck MCP server](/sql-reference/mcp/) to let AI assistants read and write them automatically, or run the SQL functions directly from any MotherDuck connection.

```sql
-- List all guides visible to you
SELECT * FROM MD_LIST_GUIDES();

-- Read a guide by id
SELECT title, content FROM MD_GET_GUIDE(id = '<guide_uuid>');

-- Create a guide
SELECT id, topic, title, current_version
FROM MD_CREATE_GUIDE(
  topic = 'revenue-billing',
  title = 'MRR and ARR Definitions',
  content = '# MRR and ARR Definitions ...',
  access = 'organization'
);
```

## Available functions

## Included pages

- [MD_LIST_GUIDES](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-list-guides): List Guides visible to you, filtered by topic subtree or reference
- [MD_GET_GUIDE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-get-guide): Read a Guide's full content by id, optionally at a historical version
- [MD_CREATE_GUIDE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-create-guide): Create a new Guide — a markdown document capturing org-specific context for AI agents
- [MD_UPDATE_GUIDE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-update-guide): Append a version to an existing Guide with updated content or references
- [MD_UPDATE_GUIDE_METADATA](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-update-guide-metadata): Retitle or re-topic a Guide, or update its description, without creating a content version
- [MD_SET_GUIDE_ACCESS](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-set-guide-access): Change a Guide's visibility between private and org-wide
- [MD_LIST_GUIDE_VERSIONS](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-list-guide-versions): List a Guide's version history without content
- [MD_DELETE_GUIDE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-delete-guide): Soft-delete a Guide while preserving its version history

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-list-guides

# MD_LIST_GUIDES
> List Guides visible to you, filtered by topic subtree or reference
List [Guides](/key-tasks/guides/) visible to you — topics and titles, without content. Read a Guide in full with [`MD_GET_GUIDE`](../md-get-guide).

## Syntax

```sql
SELECT * FROM MD_LIST_GUIDES();

-- With optional filters
SELECT * FROM MD_LIST_GUIDES(
  topic = 'revenue-billing',
  "limit" = 10,
  "offset" = 0
);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `topic` | `VARCHAR` | No | Filter to a topic subtree — the topic itself and everything below it. `'core'` matches `core` and `core/metrics` but not `core-metrics`. An empty string matches everything. |
| `reference` | `STRUCT` | No | Reverse lookup: return only Guides that reference a specific object. See [reference struct](#reference-struct). |
| `"limit"` | `UINTEGER` | No | Maximum number of Guides to return. |
| `"offset"` | `UINTEGER` | No | Number of Guides to skip (for pagination). |

### Reference struct

The `reference` parameter accepts a struct with these fields:

| Field | Type | Description |
|-------|------|-------------|
| `type` | `VARCHAR` | Required. One of `'catalog'`, `'dive'`, `'flight'`, or `'guide'`. |
| `url` | `VARCHAR` | MotherDuck URL — required for `catalog` type (for example `'md:my_database'` or a `'md:_share/...'` URL). |
| `schema` | `VARCHAR` | Schema name — required when `table`, `view`, or `macro` is set. |
| `table` | `VARCHAR` | Table name (catalog only). |
| `column` | `VARCHAR` | Column name (catalog only, requires `table`). |
| `view` | `VARCHAR` | View name (catalog only, mutually exclusive with `table`/`macro`). |
| `macro` | `VARCHAR` | Macro name (catalog only, mutually exclusive with `table`/`view`). |
| `uuid` | `UUID` | UUID of the referenced Dive, Flight, or Guide. |
| `description` | `VARCHAR` | Why this reference exists. |

## Return columns

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` | Unique identifier of the Guide |
| `topic` | `VARCHAR` | Grouping label (`NULL` for Guides without a topic) |
| `title` | `VARCHAR` | Guide title |
| `description` | `VARCHAR` | One-line summary |
| `owner_id` | `UUID` | UUID of the Guide owner |
| `owner_name` | `VARCHAR` | Name of the Guide owner |
| `access` | `VARCHAR` | `'user'` (private) or `'organization'` (org-wide) |
| `current_version` | `UINTEGER` | Latest version number |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When the Guide was created |
| `updated_at` | `TIMESTAMP WITH TIME ZONE` | When the Guide was last updated |

Guides without a topic sort first.

## Examples

List all Guides visible to you:

```sql
SELECT id, topic, title, access FROM MD_LIST_GUIDES();
```

Filter to a topic subtree:

```sql
SELECT id, title, description
FROM MD_LIST_GUIDES(topic = 'revenue-billing')
ORDER BY topic, title;
```

Find Guides that reference a specific table (unset struct fields can be omitted):

```sql
SELECT id, title
FROM MD_LIST_GUIDES(
  reference = {
    'type': 'catalog',
    'url': 'md:billing',
    'schema': 'main',
    'table': 'subscriptions'
  }
);
```

Find Guides that reference a specific column:

```sql
SELECT id, title
FROM MD_LIST_GUIDES(
  reference = {
    'type': 'catalog',
    'url': 'md:billing',
    'schema': 'main',
    'table': 'subscriptions',
    'column': 'amount'
  }
);
```

Paginate through all Guides:

```sql
SELECT id, title
FROM MD_LIST_GUIDES("limit" = 20, "offset" = 40);
```

## Related

- [`MD_GET_GUIDE`](../md-get-guide) — Read a Guide's full content.
- [`MD_CREATE_GUIDE`](../md-create-guide) — Create a new Guide.
- [`list_guides` MCP tool](/sql-reference/mcp/guides/list-guides) — AI assistant equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-get-guide

# MD_GET_GUIDE
> Read a Guide's full content by id, optionally at a historical version
Read a [Guide](/key-tasks/guides/)'s full markdown content by ID, optionally at a specific historical version.

## Syntax

```sql
SELECT * FROM MD_GET_GUIDE(id = '<guide_uuid>');

-- Read a specific version
SELECT * FROM MD_GET_GUIDE(id = '<guide_uuid>', version = 2);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `UUID` | Yes | The Guide's UUID, as returned by `MD_LIST_GUIDES` or `MD_CREATE_GUIDE`. |
| `version` | `UINTEGER` | No | Historical version number to read. Defaults to the current version. |

## Return columns

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` | Unique identifier of the Guide |
| `topic` | `VARCHAR` | Grouping label (`NULL` for Guides without a topic) |
| `title` | `VARCHAR` | Guide title |
| `description` | `VARCHAR` | One-line summary |
| `owner_id` | `UUID` | UUID of the Guide owner |
| `owner_name` | `VARCHAR` | Name of the Guide owner |
| `access` | `VARCHAR` | `'user'` (private) or `'organization'` (org-wide) |
| `current_version` | `UINTEGER` | Latest version number |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When the Guide was created |
| `updated_at` | `TIMESTAMP WITH TIME ZONE` | When the Guide was last updated |
| `version` | `UINTEGER` | The version being read |
| `version_change_comment` | `VARCHAR` | Note for this version |
| `version_external_id` | `VARCHAR` | Caller-provided version ID |
| `version_created_at` | `TIMESTAMP WITH TIME ZONE` | When this version was created |
| `references` | `STRUCT[]` | Structured references attached to this version. Guide, Dive, and Flight references resolve to `guide_id`, `dive_id`, and `flight_id` UUIDs. |
| `content` | `VARCHAR` | Full markdown content |

## Examples

Read the current version of a Guide:

```sql
SELECT topic, title, content
FROM MD_GET_GUIDE(id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890');
```

Read version 2 of a Guide:

```sql
SELECT version, version_change_comment, content
FROM MD_GET_GUIDE(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  version = 2
);
```

## Related

- [`MD_LIST_GUIDES`](../md-list-guides) — Find a Guide's ID.
- [`MD_LIST_GUIDE_VERSIONS`](../md-list-guide-versions) — Browse a Guide's version history.
- [`MD_UPDATE_GUIDE`](../md-update-guide) — Append a version.
- [`get_guide` MCP tool](/sql-reference/mcp/guides/get-guide) — AI assistant equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-create-guide

# MD_CREATE_GUIDE
> Create a new Guide — a markdown document capturing org-specific context for AI agents
Create a new [Guide](/key-tasks/guides/), identified by a generated UUID. Returns the created Guide's metadata and initial version information.

## Syntax

```sql
SELECT * FROM MD_CREATE_GUIDE(
  topic = 'revenue-billing',
  title = 'MRR and ARR Definitions',
  content = '# MRR and ARR Definitions ...',
  description = 'How MRR and ARR are calculated',
  access = 'organization'
);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | `VARCHAR` | Yes | Human-readable title. Must not be empty. |
| `content` | `VARCHAR` | Yes | Full markdown body of the Guide. Maximum 1 MB. |
| `topic` | `VARCHAR` | No | Slash-separated grouping label — for example `'revenue-billing'` or `'core/metrics'`. No leading or trailing slash. Omit for no topic. |
| `description` | `VARCHAR` | No | Short one-line summary shown in `MD_LIST_GUIDES`. |
| `access` | `VARCHAR` | No | `'user'` (private, default) or `'organization'` (org-wide, admin-permission gated). |
| `change_comment` | `VARCHAR` | No | Note describing this initial version. |
| `external_id` | `VARCHAR` | No | Caller-provided ID for this version (for example a git SHA). |
| `"references"` | `STRUCT[]` | No | Structured references to the objects this Guide explains. See [reference struct](/sql-reference/motherduck-sql-reference/guides/md-list-guides#reference-struct). |

Topics are grouping labels only — they carry no uniqueness, so multiple Guides can share the same topic.

## Return columns

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` | Generated identifier of the created Guide |
| `topic` | `VARCHAR` | Grouping label (`NULL` if omitted) |
| `title` | `VARCHAR` | Guide title |
| `description` | `VARCHAR` | One-line summary |
| `owner_id` | `UUID` | UUID of the Guide owner |
| `owner_name` | `VARCHAR` | Name of the Guide owner |
| `access` | `VARCHAR` | `'user'` or `'organization'` |
| `current_version` | `UINTEGER` | Version number (1 for newly created Guides) |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When the Guide was created |
| `updated_at` | `TIMESTAMP WITH TIME ZONE` | When the Guide was last updated |
| `version_change_comment` | `VARCHAR` | Note for the initial version |
| `version_external_id` | `VARCHAR` | Caller-provided version ID |
| `version_created_at` | `TIMESTAMP WITH TIME ZONE` | When the initial version was created |
| `references` | `STRUCT[]` | Resolved references |

## Examples

Create an org-wide metric definition Guide:

```sql
SELECT id, topic, current_version
FROM MD_CREATE_GUIDE(
  topic = 'revenue-billing',
  title = 'MRR and ARR Definitions',
  description = 'How monthly and annual recurring revenue are calculated',
  content = '# MRR and ARR Definitions

MRR is the sum of all active subscription amounts normalized to a monthly value.

Key rules:
- Use the subscriptions table, not invoices
- Filter to status = active
- Exclude trial subscriptions (trial_end IS NULL)',
  access = 'organization',
  change_comment = 'Initial version'
);
```

Create a private Guide without a topic:

```sql
SELECT id, title
FROM MD_CREATE_GUIDE(
  title = 'My scratch notes',
  content = 'Always double-check the currency column.'
);
```

## Related

- [`MD_GET_GUIDE`](../md-get-guide) — Read a Guide's content.
- [`MD_UPDATE_GUIDE`](../md-update-guide) — Append a content version.
- [`MD_DELETE_GUIDE`](../md-delete-guide) — Delete a Guide.
- [`create_guide` MCP tool](/sql-reference/mcp/guides/create-guide) — AI assistant equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-update-guide

# MD_UPDATE_GUIDE
> Append a version to an existing Guide with updated content or references
Append a version to an existing [Guide](/key-tasks/guides/), identified by ID. Omit `content` to update only metadata such as references without changing the text.

## Syntax

```sql
SELECT * FROM MD_UPDATE_GUIDE(
  id = '<guide_uuid>',
  content = '# Updated content...',
  change_comment = 'Clarify trial subscription exclusion'
);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `UUID` | Yes | The Guide's UUID. |
| `content` | `VARCHAR` | No | New full markdown body. Omit to carry the current version's content forward. |
| `change_comment` | `VARCHAR` | No | Note describing this version's change. |
| `external_id` | `VARCHAR` | No | Caller-provided ID for this version (for example a git SHA). |
| `"references"` | `STRUCT[]` | No | Replaces the Guide's references. Pass an empty list (`[]`) to clear references; omit to carry them forward. See [reference struct](/sql-reference/motherduck-sql-reference/guides/md-list-guides#reference-struct). |

## Return columns

Same as [`MD_CREATE_GUIDE`](../md-create-guide#return-columns).

## Examples

Update the full content of a Guide:

```sql
SELECT id, current_version
FROM MD_UPDATE_GUIDE(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  content = '# MRR and ARR Definitions (Updated) ...',
  change_comment = 'Add ARR calculation section'
);
```

Add references without changing content:

```sql
SELECT current_version
FROM MD_UPDATE_GUIDE(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  "references" = [
    {
      'type': 'catalog',
      'url': 'md:billing',
      'schema': 'main',
      'table': 'subscriptions'
    }
  ]
);
```

Clear all references:

```sql
SELECT current_version
FROM MD_UPDATE_GUIDE(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  "references" = []
);
```

## Related

- [`MD_GET_GUIDE`](../md-get-guide) — Read the current content before updating.
- [`MD_LIST_GUIDE_VERSIONS`](../md-list-guide-versions) — Browse the version history.
- [`MD_UPDATE_GUIDE_METADATA`](../md-update-guide-metadata) — Retitle or re-topic without a content version.
- [`update_guide` MCP tool](/sql-reference/mcp/guides/update-guide) — AI assistant equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-update-guide-metadata

# MD_UPDATE_GUIDE_METADATA
> Retitle or re-topic a Guide, or update its description, without creating a content version
Change a [Guide](/key-tasks/guides/)'s title, description, or topic without appending a content version. The Guide keeps its ID and full version history.

## Syntax

```sql
SELECT * FROM MD_UPDATE_GUIDE_METADATA(
  id = '<guide_uuid>',
  topic = 'customer-orders',
  title = 'Updated Title'
);
```

## Parameters

Provide at least one of `title`, `description`, or `topic`.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `UUID` | Yes | The Guide's UUID. |
| `title` | `VARCHAR` | No | New human-readable title. Must not be empty when supplied. |
| `description` | `VARCHAR` | No | New one-line summary. Pass an empty string (`''`) to clear it. |
| `topic` | `VARCHAR` | No | New grouping label — for example `'revenue-billing'` or `'core/metrics'` (no leading or trailing slash). Pass an empty string (`''`) to remove the topic. |

## Return columns

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` | Guide UUID |
| `topic` | `VARCHAR` | Updated topic (`NULL` when cleared) |
| `title` | `VARCHAR` | Updated title |
| `description` | `VARCHAR` | Updated description |
| `owner_id` | `UUID` | UUID of the Guide owner |
| `owner_name` | `VARCHAR` | Name of the Guide owner |
| `access` | `VARCHAR` | `'user'` or `'organization'` |
| `current_version` | `UINTEGER` | Latest version number (unchanged) |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When the Guide was created |
| `updated_at` | `TIMESTAMP WITH TIME ZONE` | When the Guide was last updated |

## Examples

Move a Guide to a different topic:

```sql
SELECT id, topic, title
FROM MD_UPDATE_GUIDE_METADATA(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  topic = 'customer-orders',
  title = 'Customer Order Filters'
);
```

Update only the description:

```sql
SELECT description
FROM MD_UPDATE_GUIDE_METADATA(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  description = 'MRR and ARR definitions, including expansion and churn adjustments'
);
```

Remove the topic (move the Guide to the root level):

```sql
SELECT topic
FROM MD_UPDATE_GUIDE_METADATA(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  topic = ''
);
```

## Related

- [`MD_UPDATE_GUIDE`](../md-update-guide) — Append a content version.
- [`MD_SET_GUIDE_ACCESS`](../md-set-guide-access) — Change visibility.
- [`update_guide_metadata` MCP tool](/sql-reference/mcp/guides/update-guide-metadata) — AI assistant equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-set-guide-access

# MD_SET_GUIDE_ACCESS
> Change a Guide's visibility between private and org-wide
Change a [Guide](/key-tasks/guides/)'s visibility to `'user'` (private) or `'organization'` (visible to your whole org). Setting org-wide access is admin-permission gated.

## Syntax

```sql
SELECT * FROM MD_SET_GUIDE_ACCESS(
  id = '<guide_uuid>',
  access = 'organization'
);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `UUID` | Yes | The Guide's UUID. |
| `access` | `VARCHAR` | Yes | `'user'` (private) or `'organization'` (org-wide, admin-permission gated). |

## Return columns

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` | Guide UUID |
| `topic` | `VARCHAR` | Grouping label (`NULL` for Guides without a topic) |
| `title` | `VARCHAR` | Guide title |
| `description` | `VARCHAR` | One-line summary |
| `owner_id` | `UUID` | UUID of the Guide owner |
| `owner_name` | `VARCHAR` | Name of the Guide owner |
| `access` | `VARCHAR` | Updated access level |
| `current_version` | `UINTEGER` | Latest version number |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When the Guide was created |
| `updated_at` | `TIMESTAMP WITH TIME ZONE` | When the Guide was last updated |

## Examples

Publish a Guide to the whole org:

```sql
SELECT access
FROM MD_SET_GUIDE_ACCESS(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  access = 'organization'
);
```

Make a Guide private again:

```sql
SELECT access
FROM MD_SET_GUIDE_ACCESS(
  id = 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
  access = 'user'
);
```

## Related

- [`MD_UPDATE_GUIDE_METADATA`](../md-update-guide-metadata) — Change title, description, or topic.
- [`MD_CREATE_GUIDE`](../md-create-guide) — Set access at creation time.
- [`set_guide_access` MCP tool](/sql-reference/mcp/guides/set-guide-access) — AI assistant equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-list-guide-versions

# MD_LIST_GUIDE_VERSIONS
> List a Guide's version history without content
List a [Guide](/key-tasks/guides/)'s version history without content. Read a specific version's content with [`MD_GET_GUIDE`](../md-get-guide) and its `version` parameter.

## Syntax

```sql
SELECT * FROM MD_LIST_GUIDE_VERSIONS(id = '<guide_uuid>');

-- With pagination
SELECT * FROM MD_LIST_GUIDE_VERSIONS(
  id = '<guide_uuid>',
  "limit" = 10,
  "offset" = 0
);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `UUID` | Yes | The Guide's UUID. |
| `"limit"` | `UINTEGER` | No | Maximum number of versions to return. |
| `"offset"` | `UINTEGER` | No | Number of versions to skip (for pagination). |

## Return columns

| Column | Type | Description |
|--------|------|-------------|
| `version` | `UINTEGER` | Version number |
| `change_comment` | `VARCHAR` | Note describing this version's change |
| `external_id` | `VARCHAR` | Caller-provided version ID (for example a git SHA) |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When this version was created |

## Examples

Browse a Guide's history:

```sql
SELECT version, change_comment, created_at
FROM MD_LIST_GUIDE_VERSIONS(id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890')
ORDER BY version DESC;
```

Read the content of an older version found in the history:

```sql
SELECT content
FROM MD_GET_GUIDE(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  version = 2
);
```

## Related

- [`MD_GET_GUIDE`](../md-get-guide) — Read a specific version's content.
- [`MD_UPDATE_GUIDE`](../md-update-guide) — Append a version.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-delete-guide

# MD_DELETE_GUIDE
> Soft-delete a Guide while preserving its version history
Soft-delete a [Guide](/key-tasks/guides/), identified by ID. The version history is preserved internally. Only the Guide's owner can delete it.

## Syntax

```sql
SELECT * FROM MD_DELETE_GUIDE(id = '<guide_uuid>');
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `UUID` | Yes | The Guide's UUID. |

## Return columns

| Column | Type | Description |
|--------|------|-------------|
| `success` | `BOOLEAN` | `true` when the Guide was deleted, `false` otherwise |

References from other Guides to a deleted Guide are left dangling and resolve to not-found.

## Examples

Verify the Guide, then delete it:

```sql
-- Verify first
SELECT topic, title, current_version
FROM MD_GET_GUIDE(id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890');

-- Then delete
SELECT success
FROM MD_DELETE_GUIDE(id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890');
```

## Related

- [`MD_GET_GUIDE`](../md-get-guide) — Verify the Guide content before deleting.
- [`MD_LIST_GUIDES`](../md-list-guides) — Find the Guide's ID.
- [`delete_guide` MCP tool](/sql-reference/mcp/guides/delete-guide) — AI assistant equivalent.

---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fmotherduck-sql-reference%2Fguides%2F&page_title=MotherDuck%20Documentation%20-%20Guides&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.