# 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.


---

## 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%2Fmd-update-guide%2F&page_title=MD_UPDATE_GUIDE&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.