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

# `facts` 操作

<!-- i18n: source=docs/reference/operations/facts.md blob=eab817783143344218c401283ce7b5b6f93399fc model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/facts.md)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/facts.md), which is authoritative.


每个 `facts.*` 操作接受和返回的确切字段。

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

每个操作在 HTTP 上都是 `POST /v1/<op>`，在 MCP 上是工具 `loom_<op>`。身份字段（`org`、`namespace`、`agent`、`user_id`、`session_id`）会在传输层能够提供时，由令牌和 MCP 会话自动填充；对于单用户服务器上不带令牌的 HTTP 调用，除 `code.*` 和 `tracker.*`（它们沿用各自所属平面的值）之外，所有操作都取该安装的 org，而[部分操作](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)的命名空间和 agent 也会自动取值；参见[身份与命名空间](/zh-CN/concepts/identities-and-namespaces)。[操作索引](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)解释了 role、kind 以及 MCP 的 `all` 列表。未知的输入字段仍会被处理，并在 `ignored_args` 中列出。

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

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

## `facts.expire_by_adapter`

将由特定抽取器（例如存在缺陷的 adapter）生成的图级三元组标记为已删除，同时不影响其所属的父记忆。

`POST /v1/facts.expire_by_adapter` · MCP `loom_facts_expire_by_adapter` · 角色 `admin` · 写入 · 已审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `adapter_name` | `str` | 必填 | 要删除其三元组的抽取器 adapter（与 `adapter_name` 精确匹配）。 |
| `max_confidence` | `float` | `1.0` | 置信度上限：只使置信度低于该阈值的三元组过期。1.0 表示无上限。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `expired_triples` | `int` | 从 `loom.entity_triples` 中删除的行数；没有匹配项时为 0。 |
| `expired_triple_memories` | `int` | 从 `loom.entity_triple_memories` 中删除的行数（三元组 -> 源键的链接）。 |

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

## `facts.list`

返回实体图中的主语-关系-宾语三元组，可按主语、宾语、关系或实体过滤，并可选返回来源 key。

`POST /v1/facts.list` · MCP `loom_facts_list` · 角色 `viewer` · 读取

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `subject` | `str \| None` | `None` | 只返回具有该主语的三元组，规范化方式与写入时相同（或按给定值转为小写）；subject、object、relation 之间为 AND 关系，不加过滤时按 co_occur 返回排名靠前的三元组。 |
| `object` | `str \| None` | `None` | 只返回具有该宾语的三元组，规范化方式与写入时相同（或按给定值转为小写）；设置 `entity` 时忽略此字段。 |
| `relation` | `str \| None` | `None` | 只返回具有该关系的三元组，按写入时存储的方式进行归一化（`works_at` -> `work_at`）。 |
| `entity` | `str \| None` | `None` | 返回主语或宾语为该实体的三元组，规范化方式与写入时相同（或按给定值转为小写）。 |
| `limit` | `int` | `50` | 最多返回这么多条三元组；服务器将其上限限制为 500。 |
| `sort_by` | `Literal['co_occur', 'recency']` | `'co_occur'` | `co_occur` 按观察次数排序，其次按时间新近度；`recency` 优先按 `last_seen` 排序。 |
| `include_sources` | `bool` | `False` | 将每个三元组展开为来源 memory_key，会额外增加一次 CH 往返，默认关闭。 |
| `include_source_status` | `bool` | `False` | 配合 key 使用，读取每个来源行的 status（再增加一次往返），并标记那些三元组仍为 open 而其背后所有行都已被取代（superseded）的情况，即三元组层落后于行更新（写入时会关闭这类三元组；此读取会显示任何仍存在的…… |
| `min_co_occur` | `int` | `1` | 丢弃观察次数少于该值的三元组（按其所有行累计）。 |
| `as_of` | `datetime \| None` | `None` | 只返回 (valid_from, valid_to) 区间包含该时间戳的三元组。 |
| `provenance` | `list[Literal['extracted', 'inferred', 'facet']] \| None` | `None` | 要保留的来源层级：可取 "extracted"、"inferred"、"facet" 中的任意几项。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rows` | `list[FactRow]` | 按 `sort_by` 顺序排列的匹配三元组。 |
| `truncated` | `bool` | 匹配的三元组多于 `limit` 时为 True。 |

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

## `facts.path`

查找两个实体之间的连接方式：在与 `facts.traverse` 遍历的相同的、经过有效期过滤的边集合上，进行有界的双向广度优先搜索，并在中间相遇。

`POST /v1/facts.path` · MCP `loom_facts_path` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `entity_a` | `str` | 必填 | 路径的一端；搜索前会按照与写入路径相同的方式规范化。 |
| `entity_b` | `str` | 必填 | 路径的另一端；以相同方式规范化。 |
| `max_hops` | `int` | `3` | 要查找的最长路径，按端到端计数（1–4）。 |
| `top_k_per_hop` | `int` | `20` | 每一跳中每个前沿实体保留的邻居数量，按强度从高到低（1–100）。 |
| `min_co_occur` | `int` | `1` | 忽略累计观测次数低于该值的边。 |
| `as_of` | `datetime \| None` | `None` | 只使用在此时间有效的边；`None` 表示保留当前仍然有效的边。 |
| `relations` | `list[str]` | *（计算得出）* | 使用带类型的图（loom.entity_triples）而不是共现关系：`relations` 将搜索限制在这些标签上，`labeled=True` 则遍历所有带类型的边。 |
| `labeled` | `bool` | `False` | 为 True 时遍历所有带类型的边（见上方 `relations`）；为 False 时遍历共现关系。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `entity_a` | `str` | 搜索所用的规范化形式 |
| `entity_b` | `str` | 另一端搜索所用的规范化形式。 |
| `found` | `bool` | 在 `max_hops` 范围内存在路径时为 True；两端规范化后相同时也为 True。 |
| `path` | `list[str]` | 找到时为 entity_a ... entity_b；否则为 [] |
| `edges` | `list[_PathEdge]` | 找到时为 len(path) - 1 |
| `hops` | `int` | 找到时为 len(edges)；未找到时为已探索的跳数 |
| `truncated` | `bool` | 结果可能不完整时为 True：跳数预算用尽但仍有未探索的前沿，或者每跳 top-k 裁剪在途中丢弃了邻居。 |

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

## `facts.related`

返回通过任意关系与 `input.entity` 共现的实体，按 co_occur 总和降序（DESC）排列。

`POST /v1/facts.related` · MCP `loom_facts_related` · 角色 `viewer` · 读操作 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（标识元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `entity` | `str` | 必填 | 要列出其邻居的实体，按主语或宾语匹配：采用写入路径存储的形式（已规范化），或采用给定值的小写形式。 |
| `top_k` | `int` | `20` | 最多返回这么多个邻居；服务器将其上限限制为 200。 |
| `as_of` | `datetime \| None` | `None` | 仅返回在此时间有效的边；`None` 表示保留当前仍有效的边。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `entity` | `str` | 按写入方式规范化后的 `entity`；若没有规范形式则为 ""。 |
| `related` | `list[_RelatedEntity]` | `entity` 通过任意关系得到的邻居，按 `co_occur` 总和降序排列。 |

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

## `facts.traverse`

从种子实体出发，沿实体共现图向外遍历 N 跳，每一跳执行一次有界查询。

`POST /v1/facts.traverse` · MCP `loom_facts_traverse` · 角色 `viewer` · 读取

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `seed_entity` | `str` | 必填 | 遍历的起始实体；查找之前会按写入路径的方式进行规范化（冠词、所有格、复数）。 |
| `max_hops` | `int` | `2` | 从种子向外遍历的跳数（1–4）。 |
| `top_k_per_hop` | `int` | `20` | 每一跳中每个前沿实体保留的邻居数量，按关联强度从高到低（1–100）。 |
| `min_co_occur` | `int` | `1` | 忽略观测次数之和低于此值的边。 |
| `max_nodes` | `int` | `400` | 所有跳数合计返回节点数的硬上限。 |
| `as_of` | `datetime \| None` | `None` | 只包含在此时间有效的边；`None` 表示保留当前仍然有效的边。 |
| `relations` | `list[str]` | *（计算得出）* | 遍历带类型的图（loom.entity_triples：subject -relation-> object，来源信息保存在 entity_triple_memories 中），而不是共现表。 |
| `labeled` | `bool` | `False` | 为 True 时遍历所有带类型的边（见上面的 `relations`）；为 False 时遍历共现关系。 |
| `hub_degree` | `int \| None` | `None` | 枢纽节点展开策略。 |
| `hub_share` | `float \| None` | `None` | 相对枢纽规则：如果到达某节点的那条边只解释了该节点自身度数中不超过此比例的部分，则该节点被视为枢纽，即 `via_co_occur / degree`，也就是在给定该节点的条件下父节点出现的概率。 |
| `rank_by` | `Literal['co_occur', 'specificity', 'cosine'] \| None` | `None` | 每一跳裁剪时所依据的排序方式。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `seed` | `str` | 实际用作遍历起点的实体（已规范化；参见 handler） |
| `seed_community_id` | `int \| None` | 种子在最近一次社区划分中所属的社区；未聚类时为 `None`。 |
| `nodes` | `list[_TraversalNode]` | 先按 hop 升序，再按 cumulative_weight 降序排列 |
| `truncated` | `bool` | 当 `max_nodes` 使遍历提前结束时为 True。 |
| `hubs` | `list[str]` | 枢纽策略报告但未展开的实体，按遍历遇到的顺序排列；策略关闭或没有节点超过阈值时为空。 |

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