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

<!-- i18n: source=docs/reference/operations/insights.md blob=e9bec66357b14346f32afbb1ad6f0a50b74bb290 model=claude-sonnet-5-5 -->
> Esta página é uma tradução automática da [página em inglês](https://clickhouse.github.io/loom/reference/operations/insights/), que prevalece.
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/insights/), which is authoritative.

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

# Operações `insights`

Os campos exatos que cada operação `insights.*` recebe e retorna.

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

Toda op é `POST /v1/<op>` via HTTP e a ferramenta MCP `loom_<op>`. Os campos de identidade (`org`, `namespace`, `agent`, `user_id`, `session_id`) são preenchidos a partir do token e da sessão MCP quando o transporte consegue; em uma chamada HTTP sem token em um servidor de usuário único, vale a org da instalação em todas as ops, exceto `code.*` e `tracker.*` (que mantêm a do seu plano), e, em [algumas ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request), o namespace e o agente; veja [identidades e namespaces](https://clickhouse.github.io/loom/pt-BR/concepts/identities-and-namespaces/). O [índice de operações](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica role, kind e a listagem `all` do MCP. Campos de entrada desconhecidos são atendidos e nomeados em `ignored_args`.

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

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

## `insights.catalog`

Lista as tabelas que `insights.query` pode ler: cada coluna com seu tipo e significado, como ler a tabela corretamente (uma linha ativa por chave, ou uma linha por evento) e os limites sob os quais uma instrução é executada.

`POST /v1/insights.catalog` · MCP `loom_insights_catalog` · role `viewer` · read · não listada no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `tables` | `list[CatalogTable]` | As tabelas que insights.query lê, com suas colunas e como lê-las. |
| `max_result_rows` | `int` | O máximo de linhas que uma instrução retorna; além disso, a resposta é truncada. |
| `max_execution_s` | `float` | O maior tempo que uma instrução roda antes de o ClickHouse interrompê-la (limite desta réplica; durante um roll, o perfil de limites armazenado pode ser diferente). |
| `max_rows_to_read` | `int` | O máximo de linhas que uma instrução pode ler; acima disso, adicione um filtro de tempo ou de chave. |

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

## `insights.query`

Executa uma única instrução SQL SELECT (ou WITH) somente leitura sobre as tabelas que `insights.catalog` lista, para perguntas que nenhuma outra leitura responde: contagens, rankings e tendências sobre memórias, conflitos, uso, documentos e o…

`POST /v1/insights.query` · MCP `loom_insights_query` · role `viewer` · read · não listada no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `sql` | `str` | obrigatório | Uma instrução SELECT ou WITH sobre as tabelas que insights.catalog lista; ela lê apenas as linhas deste namespace. |
| `limit` | `int` | `100` | O máximo de linhas a retornar (padrão 100); o limite do deployment (LOOM_CH_ANALYSIS_MAX_RESULT_ROWS) prevalece quando for menor. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `columns` | `list[AnalysisColumn]` | As colunas de resultado da instrução, cada uma com seu tipo no ClickHouse. |
| `rows` | `list[list[Any]]` | Uma lista por linha, na ordem de `columns`; datas, UUIDs e decimais como strings. |
| `row_count` | `int` | Quantas linhas `rows` contém, no máximo `limit`. |
| `truncated` | `bool` | Mais linhas correspondem do que `limit`; restrinja a instrução ou agregue. |
| `sql_digest` | `str` | O digest que o ledger de requisições registra para `sql` (`sha256:<hex>/<length>`), contra o qual a citação da instrução é verificada. |

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