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


---

## 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-list-guides%2F&page_title=MD_LIST_GUIDES&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.