> Source: https://clickhouse.github.io/loom/ko/reference/operations/blacklist/ (Markdown: https://clickhouse.github.io/loom/ko/reference/operations/blacklist.md)

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

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

# `blacklist` 연산

각 `blacklist.*` 연산이 받고 반환하는 정확한 필드입니다.

<!-- 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)에서는 네임스페이스와 에이전트도 채워집니다. 자세한 내용은 [신원과 네임스페이스](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="blacklistadd"></a>

## `blacklist.add`

값이 패턴과 일치하는 이후의 메모리 쓰기를 거부합니다.

`POST /v1/blacklist.add` · MCP `loom_blacklist_add` · 역할 `writer` · 멱등 · 감사 대상

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(신원 튜플의 첫 번째 요소). |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. |
| `pattern` | `str` | 필수 | 거부할 텍스트. 저장된 값과 대소문자를 구분하여 비교하며, 부분 문자열 또는 256자 이하의 정규식으로 일치 여부를 판단합니다. |
| `pattern_type` | `Literal['substring', 'regex']` | `'substring'` | `substring`(일반 텍스트) 또는 `regex`(RE2, 쓰기와 스윕에서 사용하며 추가 시 길이가 제한됨). |
| `scope` | `Literal['namespace', 'org', 'global']` | `'namespace'` | 적용 범위: `namespace`(이 네임스페이스만), `org`(모든 네임스페이스, org 관리자 필요), `global`(모든 테넌트, 플랫폼 관리자 필요). |
| `reason` | `str` | `''` | 패턴이 존재하는 이유. 저장되고 목록에 표시됩니다. |
| `created_by` | `str` | `''` | 호출에 기록할 인증된 주체가 없을 때만 기록되는 작성자. |
| `sweep` | `bool` | `False` | 패턴이 이미 일치하는 활성 행도 함께 tombstone 처리합니다. 이 org 안에서 처리하며, 네임스페이스 범위 패턴은 해당 네임스페이스 안에서만 처리합니다. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `pattern_id` | `str` | 새 패턴의 id. `blacklist.sweep`과 `blacklist.remove`에서 사용합니다. |
| `created_at` | `datetime` | 패턴이 저장된 시각(UTC). |
| `swept` | `int` | 스윕이 tombstone 처리한 행 수. `sweep`이 없으면 0. |
| `swept_truncated` | `bool` | 한 번의 스윕이 처리할 수 있는 것보다 많은 행이 일치하면 True. `blacklist.sweep`을 호출하세요. |
| `sweep_error` | `str` | 스윕이 끝나면 "", 그렇지 않으면 이유(어느 쪽이든 패턴은 저장됨): `<code>: <message>`(blacklist.sweep으로 다시 실행), 정규식을 실행할 수 없을 때 RE2가 알려 주는 이유(쿼리는 실행되지 않음), 또는 일치 쿼리가 실패한 오류의 종류. |

<a id="blacklistlist"></a>

## `blacklist.list`

메모리 저장을 막는 패턴을 나열합니다.

`POST /v1/blacklist.list` · MCP `loom_blacklist_list` · 역할 `viewer` · 읽기 · MCP `all` 도구 세트에는 나열되지 않음

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(신원 튜플의 첫 번째 요소). |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. |
| `scope` | `Literal['namespace', 'org', 'global'] \| None` | `None` | scope=None이면 이 (org, namespace)에 적용되는 모든 패턴을 반환하며, 더 높은 범위(org 전체, global)의 패턴도 포함합니다. 즉 이 범위에 직접 지정된 패턴만이 아니라 실제로 적용되는 규칙 집합입니다. |
| `limit` | `int` | `100` | 최대 이 개수만큼의 패턴을 최신순으로 반환합니다(1-1000). |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `rows` | `list[_BlacklistRow]` | 범위 필터와 일치하는 활성 패턴, 최신순. |

<a id="blacklistremove"></a>

## `blacklist.remove`

이전에 추가한 blacklist 패턴을 제거합니다.

`POST /v1/blacklist.remove` · MCP `loom_blacklist_remove` · 역할 `admin` · 멱등 · 감사 대상 · MCP `all` 도구 세트에는 나열되지 않음

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(신원 튜플의 첫 번째 요소). |
| `pattern_id` | `str` | 필수 | tombstone 처리할 패턴. 호출자의 권한 범위 밖에 있는 네임스페이스 패턴은 `removed=false`로 응답합니다. |
| `removed_by` | `str` | `''` | 패턴 행이 아닌 blacklist 캐시의 버전 마커에만 기록됩니다. |
| `reason` | `str` | `''` | 받아들이지만 저장하지 않습니다. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `removed` | `bool` | 해당 id의 활성 패턴이 호출자에게 보이지 않으면 False. |
| `removed_at` | `datetime \| None` | 패턴이 tombstone 처리된 시각(UTC). 제거된 것이 없으면 null. |

<a id="blacklistsweep"></a>

## `blacklist.sweep`

기존 패턴과 일치하는 활성 행을 tombstone 처리합니다.

`POST /v1/blacklist.sweep` · MCP `loom_blacklist_sweep` · 역할 `writer` · 멱등 · 감사 대상 · MCP `all` 도구 세트에는 나열되지 않음

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(신원 튜플의 첫 번째 요소). |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. |
| `pattern_id` | `str` | 필수 | 스윕에 사용할 활성 패턴. 알 수 없는 id나 호출자의 권한 범위 밖의 id는 404로 응답합니다. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `pattern_id` | `str` | 스윕에 사용한 패턴(그대로 반환). |
| `matched` | `int` | 이번 호출에서 패턴과 일치한 활성 행: ClickHouse에서는 최대 5,000개이며, Postgres 권한 하에서는 이번 호출이 tombstone 처리한 보류 중인 헤드가 더해집니다. |
| `tombstoned` | `int` | 이번 호출이 tombstone 처리한 행 수. |
| `truncated` | `bool` | 한 번의 호출이 처리할 수 있는 것보다 많은 행이 일치하면 True. 다시 호출하세요. |
| `error` | `str` | 스윕이 끝나면 "", 그렇지 않으면 행이 이미 반영되었을 수 있는 경우 `<code>: <message>`(다시 호출), 정규식을 실행할 수 없을 때 RE2가 알려 주는 이유(쿼리는 실행되지 않음), 또는 일치 쿼리가 실패한 오류의 종류. 그 이전 단계의 실패는 호출 자체의 실패입니다. |

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