MD_LIST_GUIDES

Preview

This feature is in preview and is subject to change.

List Guides visible to you — topics and titles, without content. Read a guide in full with MD_GET_GUIDE.

Syntax

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.
"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:

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

Filter to a topic subtree:

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):

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

Find guides that reference a specific column:

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

Paginate through all guides:

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

Related

• MD_GET_GUIDE — Read a guide's full content.
• MD_CREATE_GUIDE — Create a new guide.
• list_guides MCP tool — AI assistant equivalent.