Pular para o conteúdo
ClickHouse Loom
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

Operações de facts

Operações de facts

Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.

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

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, também o namespace e o agente. Veja identidades e namespaces. O índice de operações explica role, kind e a listagem all do MCP. Campos de entrada desconhecidos são atendidos e listados em ignored_args.

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

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.

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.

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.

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.

Esta página foi útil?