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

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

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

# `insights` 오퍼레이션

각 `insights.*` 오퍼레이션이 받고 반환하는 정확한 필드입니다.

<!-- 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)은 role, kind, MCP `all` 목록을 설명합니다. 알 수 없는 입력 필드도 처리되며 `ignored_args`에 이름이 표시됩니다.

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

<a id="insightscatalog"></a>

## `insights.catalog`

`insights.query`가 읽을 수 있는 테이블을 나열합니다. 각 컬럼의 타입과 의미, 테이블을 올바르게 읽는 방법(키당 하나의 라이브 행인지, 이벤트당 하나의 행인지), 그리고 구문이 실행되는 제한을 보여 줍니다.

`POST /v1/insights.catalog` · MCP `loom_insights_catalog` · role `viewer` · read · MCP `all` 툴셋에는 나열되지 않음

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(신원 튜플의 첫 번째 요소). |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `tables` | `list[CatalogTable]` | insights.query가 읽는 테이블과 그 컬럼, 읽는 방법. |
| `max_result_rows` | `int` | 한 구문이 반환하는 최대 행 수. 이를 넘으면 응답이 잘립니다. |
| `max_execution_s` | `float` | ClickHouse가 중단하기 전까지 한 구문이 실행되는 최대 시간(이 레플리카의 제한이며, 롤링 업데이트 중에는 저장된 제한 프로필이 다를 수 있음). |
| `max_rows_to_read` | `int` | 한 구문이 읽을 수 있는 최대 행 수. 이를 넘으면 시간 또는 키 필터를 추가하세요. |

<a id="insightsquery"></a>

## `insights.query`

`insights.catalog`가 나열하는 테이블에 대해 읽기 전용 SQL SELECT(또는 WITH) 하나를 실행합니다. 다른 읽기 op로는 답할 수 없는 질문, 즉 메모리, 충돌, 사용량, 문서 등에 대한 집계, 순위, 추세에 쓰입니다…

`POST /v1/insights.query` · MCP `loom_insights_query` · role `viewer` · read · MCP `all` 툴셋에는 나열되지 않음

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(신원 튜플의 첫 번째 요소). |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. |
| `sql` | `str` | 필수 | insights.catalog가 나열하는 테이블에 대한 SELECT 또는 WITH 구문 하나. 이 네임스페이스의 행만 읽습니다. |
| `limit` | `int` | `100` | 반환할 최대 행 수(기본값 100). 배포의 상한(LOOM_CH_ANALYSIS_MAX_RESULT_ROWS)이 더 낮으면 그 값이 우선합니다. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `columns` | `list[AnalysisColumn]` | 구문의 결과 컬럼과 각 ClickHouse 타입. |
| `rows` | `list[list[Any]]` | 행당 하나의 리스트이며 `columns` 순서를 따릅니다. 날짜, UUID, 십진수는 문자열로 표현됩니다. |
| `row_count` | `int` | `rows`에 담긴 행 수이며 최대 `limit`입니다. |
| `truncated` | `bool` | `limit`보다 많은 행이 일치했습니다. 구문을 좁히거나 집계하세요. |
| `sql_digest` | `str` | 요청 원장이 `sql`에 대해 기록하는 다이제스트(`sha256:<hex>/<length>`)이며, 구문 인용은 이 값과 대조해 확인됩니다. |

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