MD_CREATE_GUIDE

Preview

This feature is in preview and is subject to change.

Create a new Guide, identified by a generated UUID. Returns the created Guide's metadata and initial version information.

Syntax

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.

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:

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:

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

Related

• MD_GET_GUIDE — Read a Guide's content.
• MD_UPDATE_GUIDE — Append a content version.
• MD_DELETE_GUIDE — Delete a Guide.
• create_guide MCP tool — AI assistant equivalent.