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

# `collection` 오퍼레이션

<!-- i18n: source=docs/reference/operations/collection.md blob=c6923c62aee6e89e254a9af29040b8fc1740a6e7 model=claude-sonnet-5-5 -->
> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/collection.md)을 기계 번역한 것이며, 영어 원문이 기준입니다.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/collection.md), which is authoritative.


각 `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.*`(각자의 plane을 유지함)를 제외한 모든 op에서 설치의 org가 사용되며, [일부 op](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)에서는 네임스페이스와 에이전트도 채워집니다. 자세한 내용은 [아이덴티티와 네임스페이스](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`

컬렉션을 만듭니다. 컬렉션은 권한 부여(grant)를 통해서만 읽고 쓸 수 있는 네임스페이스입니다.

`POST /v1/collection.create` · MCP `loom_collection_create` · 역할 `viewer` · 멱등 · 감사 대상 · MCP `all` 툴셋에 나열되지 않음

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(아이덴티티 튜플의 첫 번째 요소). |
| `namespace` | `str` | `''` | 컬렉션의 이름이자 네임스페이스('col-' 다음에 소문자, 숫자, '-'). `derive_name`을 쓰면 무시됩니다. |
| `title` | `str` | `''` | 화면에 표시되는 컬렉션 이름(최대 200자, 제어 문자와 보이지 않는 문자 불가, 제목은 org 안에서 중복 가능). 없으면 ''. |
| `derive_name` | `bool` | `False` | `namespace` 대신 `title`에서 이름을 만듭니다. 상위 컬렉션 아래(최상위라면 호출자 본인의 것)에서 이미 쓰는 제목이면 그 컬렉션을 반환합니다. |
| `parent` | `str` | `''` | 컬렉션이 속하며 권한 부여를 상속받는 상위 컬렉션. 최상위 컬렉션이면 ''. |
| `description` | `str` | `''` | 컬렉션에 담긴 내용으로, 이름 옆에 표시됩니다(최대 2000자). 없으면 ''. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `namespace` | `str` | op가 읽거나 쓰는 네임스페이스. |
| `parent` | `str` | 컬렉션이 속한 상위 컬렉션. 최상위 컬렉션이면 ''. |
| `created` | `bool` | 컬렉션이 이미 있었으면 False. 호출자 본인의 같은 이름 컬렉션이거나, 그 위치에서 해당 제목이 이미 가리키는 컬렉션인 경우입니다. |
| `title` | `str` | 컬렉션의 제목. 없으면 ''. |

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

## `collection.delete`

컬렉션과 그 안의 내용을 삭제합니다. 네임스페이스를 영구 삭제(purging erasure)하여 문서, 청크, 원본, 메모리가 디스크에서 사라지고, 이후 디렉터리와 트리에서도 제거되며 그 이름은 다시 쓰이지 않습니다…

`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)의 ID. `erasure.status`로 진행 상황을 확인합니다. |
| `erasure_status` | `str` | 해당 삭제 작업의 결과. `completed`, 또는 복구 워커가 재시도하는 동안의 `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`. 첫 페이지에서는 없음. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `collections` | `list[_CollectionEntry]` | 이 페이지에서 호출자가 읽을 수 있는 컬렉션을 이름순으로 나열한 목록으로, 호출자의 역할과 컬렉션의 제목 및 설명을 포함합니다. |
| `next_cursor` | `str \| None` | 다음 페이지를 가져올 때 `cursor`로 전달합니다. 마지막 페이지에서는 없음. |

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