> Source: https://clickhouse.github.io/loom/zh-CN/reference/operations/collection/ (Markdown: https://clickhouse.github.io/loom/zh-CN/reference/operations/collection.md)

<!-- i18n: source=docs/reference/operations/collection.md blob=c6923c62aee6e89e254a9af29040b8fc1740a6e7 model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://clickhouse.github.io/loom/reference/operations/collection/)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/collection/), which is authoritative.

<a id="collection-operations"></a>

# `collection` 操作

每个 `collection.*` 操作接受和返回的确切字段。

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

每个 op 都是 HTTP 上的 `POST /v1/<op>`，同时也是 MCP 工具 `loom_<op>`。身份字段（`org`、`namespace`、`agent`、`user_id`、`session_id`）在传输层能够提供时，由令牌和 MCP 会话填充；对于单用户服务器上不带令牌的 HTTP 调用，除 `code.*` 和 `tracker.*`（它们沿用各自平面的组织）之外的所有 op 都使用该安装的 org，而[部分 op](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)还会填充其命名空间和 agent；参见[身份与命名空间](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)。[操作索引](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)说明了角色、类型以及 MCP `all` 列表。未知的输入字段照常处理，并列在 `ignored_args` 中。

<!-- prettier-ignore-start -->

<a id="collectioncreate"></a>

## `collection.create`

创建集合：一个只能通过授权读写的命名空间。

`POST /v1/collection.create` · MCP `loom_collection_create` · 角色 `viewer` · 幂等 · 已审计 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | `''` | 集合的名称，同时也是它的命名空间（以 'col-' 开头，后接小写字母、数字和 '-'），使用 `derive_name` 时被忽略。 |
| `title` | `str` | `''` | 集合在屏幕上显示的名称（最多 200 个字符，不含控制字符或不可见字符；标题在组织内可以重复）；'' 表示没有。 |
| `derive_name` | `bool` | `False` | 从 `title` 而不是 `namespace` 派生名称；如果父集合下（顶层则为调用者自己的集合）已使用该标题，则返回那个集合。 |
| `parent` | `str` | `''` | 它所在并继承授权的集合；'' 表示顶层集合。 |
| `description` | `str` | `''` | 集合所包含的内容，显示在名称旁边（最多 2000 个字符）；'' 表示没有。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `namespace` | `str` | 该 op 读写的命名空间。 |
| `parent` | `str` | 它所在的集合；'' 表示顶层集合。 |
| `created` | `bool` | 集合已存在时为 False：即调用者自己的同名集合，或该处已以此标题命名的集合。 |
| `title` | `str` | 集合的标题；'' 表示没有。 |

<a id="collectiondelete"></a>

## `collection.delete`

删除集合及其所含内容：对命名空间执行清除式擦除（文档、分块、原始文件、记忆都会从磁盘上移除），随后它会离开目录和树，其名称不再被使用……

`POST /v1/collection.delete` · MCP `loom_collection_delete` · 角色 `admin` · 幂等 · 已审计 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该 op 读写的命名空间。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `namespace` | `str` | 该 op 读写的命名空间。 |
| `deleted` | `bool` | 已被删除过时为 False |
| `erasure_id` | `str` | 对该集合所含内容的擦除；可用 `erasure.status` 跟踪。 |
| `erasure_status` | `str` | 该擦除的结果：`completed`，或在恢复 worker 重试期间为 `failed`。 |

<a id="collectionlist"></a>

## `collection.list`

按名称列出调用者可以读取的集合。

`POST /v1/collection.list` · MCP `loom_collection_list` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `limit` | `int` | `500` | 每页的集合数。 |
| `include_document_counts` | `bool` | `False` | 在每个集合中直接包含当前文档数；默认为 false。 |
| `cursor` | `str \| None` | `None` | 上一页的 `next_cursor`；第一页为 none。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `collections` | `list[_CollectionEntry]` | 本页中调用者可以读取的集合，按名称排列，附带调用者的角色以及集合的标题和描述。 |
| `next_cursor` | `str \| None` | 作为 `cursor` 传入以获取下一页；最后一页为 none。 |

<a id="collectionmove"></a>

## `collection.move`

将集合放到另一个集合之下，或将其分离。

`POST /v1/collection.move` · MCP `loom_collection_move` · 角色 `admin` · 幂等 · 已审计 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该 op 读写的命名空间。 |
| `parent` | `str` | `''` | 新的父集合；'' 表示分离，只保留它自己的授权。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `namespace` | `str` | 该 op 读写的命名空间。 |
| `parent` | `str` | 它现在所在的集合；分离后为 ''。 |
| `moved` | `bool` | 它本来就在该处时为 False |

<!-- prettier-ignore-end -->
