---
title: "Operações de `facts`"
---

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

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

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

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

Toda operação é um `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 fazer isso. Em uma chamada HTTP sem token em um servidor de usuário único, é usada a org da instalação em todas as operações, exceto `code.*` e `tracker.*` (que mantêm a do seu plano), e, em [algumas operações](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request), também o namespace e o agente. Veja [identidades e namespaces](/docs/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 listados em `ignored_args`.

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

<a id="factsexpire_by_adapter"></a>

## `facts.expire_by_adapter`

Marca como removidas (tombstone) as triplas em nível de grafo emitidas por um extrator específico (por exemplo, um adaptador com bug), sem tocar nas memórias de origem.

`POST /v1/facts.expire_by_adapter` · MCP `loom_facts_expire_by_adapter` · role `admin` · escrita · auditada · 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. |
| `adapter_name` | `str` | obrigatório | Adaptador extrator cujas triplas serão excluídas (correspondência exata em `adapter_name`). |
| `max_confidence` | `float` | `1.0` | Limite máximo de confiança: expira apenas triplas com confiança < limite. 1.0 = sem limite. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `expired_triples` | `int` | Linhas removidas de `loom.entity_triples`; 0 quando nenhuma correspondeu. |
| `expired_triple_memories` | `int` | Linhas removidas de `loom.entity_triple_memories` (vínculos de tripla -> chave de origem). |

<a id="factslist"></a>

## `facts.list`

Triplas sujeito-relação-objeto do grafo de entidades, filtradas por sujeito / objeto / relação / entidade; chaves de origem opcionais.

`POST /v1/facts.list` · MCP `loom_facts_list` · papel `viewer` · leitura

| 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. |
| `subject` | `str \| None` | `None` | Apenas triplas com este sujeito, canonicalizado como em uma escrita (ou como informado, em minúsculas); sujeito/objeto/relação se combinam com AND, e sem filtros retorna as triplas principais por co_occur. |
| `object` | `str \| None` | `None` | Apenas triplas com este objeto, canonicalizado como em uma escrita (ou como informado, em minúsculas); ignorado quando `entity` está definido. |
| `relation` | `str \| None` | `None` | Apenas triplas com esta relação, normalizada da forma como as escritas a armazenam (`works_at` -> `work_at`). |
| `entity` | `str \| None` | `None` | Triplas com esta entidade como sujeito ou objeto, canonicalizada como em uma escrita (ou como informada, em minúsculas). |
| `limit` | `int` | `50` | No máximo este número de triplas; o servidor limita em 500. |
| `sort_by` | `Literal['co_occur', 'recency']` | `'co_occur'` | `co_occur` ordena pela contagem de observações e depois pela recência; `recency` ordena primeiro por `last_seen`. |
| `include_sources` | `bool` | `False` | Expande cada tripla para as memory_keys de origem — uma ida e volta extra ao CH, desativada por padrão. |
| `include_source_status` | `bool` | `False` | Com as chaves, lê o status de cada linha de origem (mais uma ida e volta) e sinaliza uma tripla que está aberta enquanto todas as linhas por trás dela estão substituídas — o plano de triplas atrasado em relação a uma atualização de linha (as escritas fecham essas triplas no momento da escrita; esta leitura mostra qualquer que… |
| `min_co_occur` | `int` | `1` | Descarta triplas observadas menos vezes que este valor (somadas entre suas linhas). |
| `as_of` | `datetime \| None` | `None` | Apenas triplas cujo intervalo (valid_from, valid_to) contém este timestamp. |
| `provenance` | `list[Literal['extracted', 'inferred', 'facet']] \| None` | `None` | Camadas de proveniência a manter: qualquer uma entre "extracted", "inferred", "facet". |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `rows` | `list[FactRow]` | As triplas correspondentes na ordem de `sort_by`. |
| `truncated` | `bool` | True quando mais triplas corresponderam do que `limit`. |

<a id="factspath"></a>

## `facts.path`

Descobre como duas entidades estão conectadas: uma busca em largura bidirecional e limitada, sobre o mesmo conjunto de arestas filtradas por validade que `facts.traverse` percorre, encontrando-se no meio.

`POST /v1/facts.path` · MCP `loom_facts_path` · papel `viewer` · leitura · não listado 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 escreve. |
| `entity_a` | `str` | obrigatório | Uma extremidade do caminho; canonicalizada como no caminho de escrita antes da busca. |
| `entity_b` | `str` | obrigatório | A outra extremidade; canonicalizada da mesma forma. |
| `max_hops` | `int` | `3` | Maior caminho a procurar, contado de ponta a ponta (1–4). |
| `top_k_per_hop` | `int` | `20` | Vizinhos que cada entidade da fronteira mantém por salto, dos mais fortes aos mais fracos (1–100). |
| `min_co_occur` | `int` | `1` | Ignora arestas cuja contagem somada de observações seja menor que este valor. |
| `as_of` | `datetime \| None` | `None` | Somente arestas válidas neste instante; `None` mantém as arestas ainda válidas agora. |
| `relations` | `list[str]` | *(calculado)* | Grafo tipado (loom.entity_triples) em vez de coocorrência: `relations` restringe a esses rótulos, `labeled=True` percorre todas as arestas tipadas. |
| `labeled` | `bool` | `False` | True percorre todas as arestas tipadas (veja `relations` acima); False percorre a coocorrência. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `entity_a` | `str` | forma canônica buscada |
| `entity_b` | `str` | Forma canônica buscada para a outra extremidade. |
| `found` | `bool` | True quando existe um caminho dentro de `max_hops`; também True quando as duas extremidades têm a mesma forma canônica. |
| `path` | `list[str]` | entity_a ... entity_b quando encontrado; [] caso contrário |
| `edges` | `list[_PathEdge]` | len(path) - 1 quando encontrado |
| `hops` | `int` | len(edges) quando encontrado; saltos explorados quando não encontrado |
| `truncated` | `bool` | True quando a resposta pode estar incompleta: o orçamento de saltos acabou com fronteira não explorada, ou o corte top-k por salto descartou vizinhos pelo caminho. |

<a id="factsrelated"></a>

## `facts.related`

Retorna as entidades que co-ocorrem com `input.entity` por meio de qualquer relação, ordenadas pelo total de co_occur (DESC).

`POST /v1/facts.related` · MCP `loom_facts_related` · role `viewer` · leitura · não listado 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. |
| `entity` | `str` | obrigatório | A entidade cujos vizinhos serão listados, correspondida como sujeito ou objeto: como o caminho de escrita a armazena (canonicalizada) ou como foi informada, em minúsculas. |
| `top_k` | `int` | `20` | No máximo esta quantidade de vizinhos; o servidor limita o valor a 200. |
| `as_of` | `datetime \| None` | `None` | Somente arestas válidas neste momento; `None` mantém as arestas ainda válidas agora. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `entity` | `str` | `entity` canonicalizada como em uma escrita, ou "" quando não há forma canônica. |
| `related` | `list[_RelatedEntity]` | Vizinhos de `entity` por qualquer relação, ordenados pela soma de `co_occur` em ordem decrescente. |

<a id="factstraverse"></a>

## `facts.traverse`

Percorre o grafo de coocorrência de entidades até N saltos a partir de uma semente, com uma consulta limitada por salto.

`POST /v1/facts.traverse` · MCP `loom_facts_traverse` · role `viewer` · leitura

| 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. |
| `seed_entity` | `str` | obrigatório | Entidade de onde a caminhada parte; canonicalizada como no caminho de escrita (artigos, possessivos, plurais) antes da busca. |
| `max_hops` | `int` | `2` | Quantos saltos a partir da semente percorrer (1–4). |
| `top_k_per_hop` | `int` | `20` | Vizinhos que cada entidade da fronteira mantém por salto, dos mais fortes para os mais fracos (1–100). |
| `min_co_occur` | `int` | `1` | Ignora arestas cuja contagem somada de observações seja menor que este valor. |
| `max_nodes` | `int` | `400` | Limite máximo de nós retornados somando todos os saltos. |
| `as_of` | `datetime \| None` | `None` | Somente arestas válidas neste momento; `None` mantém as arestas ainda válidas agora. |
| `relations` | `list[str]` | *(calculado)* | Percorre o grafo TIPADO (loom.entity_triples: sujeito -relação-> objeto, com proveniência em entity_triple_memories) em vez da tabela de coocorrência. |
| `labeled` | `bool` | `False` | True percorre todas as arestas tipadas (veja `relations` acima); False percorre a coocorrência. |
| `hub_degree` | `int \| None` | `None` | Política de expansão de hubs. |
| `hub_share` | `float \| None` | `None` | Regra relativa de hub: um nó alcançado é um hub quando a aresta que o alcançou explica no máximo esta fração do grau do próprio nó — `via_co_occur / degree`, a probabilidade do pai dado o nó. |
| `rank_by` | `Literal['co_occur', 'specificity', 'cosine'] \| None` | `None` | Critério de ordenação usado na poda por salto. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `seed` | `str` | a entidade de onde a caminhada realmente partiu (canonicalizada; veja o handler) |
| `seed_community_id` | `int \| None` | Comunidade da semente na última passada de comunidades; `None` quando não está agrupada. |
| `nodes` | `list[_TraversalNode]` | ordenados por hop ASC e, depois, cumulative_weight DESC |
| `truncated` | `bool` | True quando `max_nodes` interrompeu a caminhada antes do fim. |
| `hubs` | `list[str]` | Entidades que a política de hubs reportou, mas não expandiu, na ordem em que a caminhada as encontrou; vazio quando a política está desativada ou nenhum nó ultrapassou o limite. |

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