Neo4j 图数据质量检查实战：环路检测、孤立节点与连通分量，两条 Cypher 引出的数据体检清单（含变长路径性能陷阱）

用图数据库跑配置管理、资产依赖图谱的同学，大概率经历过这样的场景：做影响分析时依赖链"转圈"绕不出去，或者报表对账时发现一批资产在图里"人间蒸发"。关系型数据库里好歹还有外键、非空约束兜底，图数据库的很多写入路径（尤其是从 CMDB 之类的源头定时同步进来的数据）没有这层保险------脏数据进图的时候悄无声息，炸的时候是在业务查询里炸。

笔者在一次图数据库与检索引擎的联合压测准备阶段（检索侧的查询基准实测写在《Elasticsearch 查询性能实测》）做数据体检时，把图侧的问题收敛成了两条 Cypher：一条查环，一条查孤点。这两条查询短得像"一行代码"，但围绕它们展开的语义、性能陷阱和治理思路，值得单独写一篇。本文以资产依赖图谱为背景（数据模型已泛化为演示数据），把这套图数据体检清单完整展开：环路分级检测、孤立节点判定、重复节点、属性缺失、度分布、连通分量，外加 APOC / GDS 两个官方插件里真正好用的工具。

环境说明：查询在 Neo4j 4.4.x 上验证，语法兼容 5.x；涉及 2025.06 新语法（REPEATABLE ELEMENTS）处单独标注。演示数据为虚构的 Asset 节点 + DEPENDS_ON 关系，非任何真实环境数据。

一、先想清楚：图数据质量检查查什么

图模型 = 节点 + 关系，所以数据质量问题天然分三类：

问题类别	典型症状	危害
结构错误：环、孤点、断链	依赖分析转圈、资产"失踪"	影响分析/根因定位直接跑偏
实体错误：重复节点、属性缺失	同一资产两个身份、关键字段为空	统计口径错、下游同步幂等失效
分布异常：明星节点、连通分量碎裂	单点被上万节点依赖、图谱分崩离析	查询热点、图算法结果不可用

注意一个和关系型库不同的点：Neo4j 里不存在"悬垂关系"------关系的两端必须各挂一个真实存在的节点，存储引擎从结构上保证了这一点，所以这一项不用查（这算是图数据库少有的一层结构保险）。剩下的每一类，后面各有一节对应的 Cypher。

二、演示数据：十个节点埋好所有病灶

为了让每条查询的输出可预期，先构造一份刻意埋了病灶的演示图：10 个 Asset 节点、15 条 DEPENDS_ON 关系。

// 病灶清单：a1 自环；a2<->a3 二元互指；a4->a5->a6->a7->a4 四跳深层环；
// a8 孤点；a9 与 a2 重复（同 asset_code）；a0 是被 6 个节点依赖的明星节点
CREATE (a0:Asset {asset_code: 'AST-0000', name: '核心交换'}),
       (a1:Asset {asset_code: 'AST-0001', name: '订单网关'}),
       (a2:Asset {asset_code: 'AST-0002', name: '支付服务'}),
       (a3:Asset {asset_code: 'AST-0003', name: '账务服务'}),
       (a4:Asset {asset_code: 'AST-0004', name: '风控引擎'}),
       (a5:Asset {asset_code: 'AST-0005', name: '规则中心'}),
       (a6:Asset {asset_code: 'AST-0006', name: '模型平台'}),
       (a7:Asset {asset_code: 'AST-0007', name: '特征仓库'}),
       (a8:Asset {asset_code: 'AST-0008', name: '备份节点'}),
       (a9:Asset {asset_code: 'AST-0002', name: '支付服务-副本'})
CREATE (a1)-[:DEPENDS_ON]->(a1),
       (a2)-[:DEPENDS_ON]->(a3), (a3)-[:DEPENDS_ON]->(a2),
       (a4)-[:DEPENDS_ON]->(a5), (a5)-[:DEPENDS_ON]->(a6),
       (a6)-[:DEPENDS_ON]->(a7), (a7)-[:DEPENDS_ON]->(a4),
       (a9)-[:DEPENDS_ON]->(a3),
       (a1)-[:DEPENDS_ON]->(a0), (a2)-[:DEPENDS_ON]->(a0),
       (a4)-[:DEPENDS_ON]->(a0), (a5)-[:DEPENDS_ON]->(a0),
       (a6)-[:DEPENDS_ON]->(a0), (a7)-[:DEPENDS_ON]->(a0)

画出来是这样：

  a1──▶a1（自环）      a2⇄a3（二元互指）       a8（孤点，零关系）
   │                    │
   └──────┐      ┌──────┘
          ▼      ▼
         ┌────────────┐
         │ a0 核心交换  │◀── a4/a5/a6/a7 各 1 条边
         │ （明星节点）  │      （合计 6 条入边）
         └────────────┘
   a4 ──▶ a5 ──▶ a6 ──▶ a7
   ▲ ────────────────────┘   （a7 ──▶ a4：四跳深层环）

   a9（与 a2 同 asset_code 的重复节点）──▶ a3

十个节点里塞了六种病灶，后面每条体检查询都能在这份图上"验货"。

三、环路检测：一条变长路径查询的三层讲究

3.1 从最短的那条查询说起

体检清单里最核心的一条，查四跳及以上的深层环：

MATCH (a)-[*4..]->(a)
RETURN a

(a)-[*4..]->(a) 的含义是：从节点 a 出发，沿关系方向走至少 4 步、上不封顶 ，如果能回到 a 自己，就命中。这是典型的变长路径（variable-length path）模式，*4.. 里的 4 是下界。

为什么从 4 跳查起、而不是从 1 跳？因为浅层环和深层环的成因与查法不同，实战里要分级查：

// 一跳自环：节点依赖自己，多是同步任务的幂等 bug
MATCH (a)-[]->(a)
RETURN a.asset_code AS code

// 二跳互指：A 依赖 B、B 又依赖 A，建模时方向标反的典型症状
MATCH (a)-[*2]->(a)
RETURN a.asset_code AS code

// 四跳及以上深层环：多次增量同步叠加出来的"慢性病"，
// 应用层很难发现，等依赖分析转圈才暴露
MATCH path = (a)-[*4..]->(a)
RETURN path

在演示数据上，三条查询分别命中：AST-0001（自环）、AST-0002/AST-0003（互指）、a4→a5→a6→a7→a4 这条四跳环。浅层环肉眼排查容易，深层环往往藏在几十万关系里，这才是变长路径查询真正的用武之地。

3.2 第一个讲究：RETURN path，不要只 RETURN a

素材原句是 RETURN a------只返回环上的一个节点。排障时这是不够的：你知道 AST-0004 在环上，但不知道环怎么绕。把返回值换成 path，拿到完整路径再配 length(path)，环长一目了然：

MATCH path = (a:Asset)-[*4..]->(a)
RETURN [n IN nodes(path) | n.asset_code] AS cycle_nodes,
       length(path) AS hops
ORDER BY hops

输出形如 ["AST-0004","AST-0005","AST-0006","AST-0007"] | 4，直接可以拿去和源头系统对账。

3.3 第二个讲究：为什么它不会无限转圈------关系唯一性

很多同学的第一反应：[*4..] 上不封顶，查询会不会在环里无限绕下去？答案是不会，原因在 Cypher 的默认匹配语义------官方文档明确：默认情况下，同一条关系在单个匹配模式内只会被匹配一次（"By default, Cypher will only match a relationship once inside a single pattern"）。路径每前进一跳用的都是"没走过的新关系"，而图里关系总数有限，路径长度自然有上界，查询必然终止。

这个语义在 Neo4j 2025.06 的 Cypher 25 里有了显式开关：默认行为等价于"关系不可重复"，而新语法 REPEATABLE ELEMENTS 允许节点和关系在路径中重复出现。一旦开了可重复语义，官方文档直接警告：不带上界的量化路径可能产生无限多行结果，必须配合上界使用。理解了这层语义，才能解释清楚下面的性能陷阱。

3.4 第三个讲究：性能陷阱------"上不封顶"在生产上是事故候选

不会无限绕圈 ≠ 查询便宜。变长路径的搜索空间随跳数指数级 膨胀：一个平均出度 5 的图，走 8 跳的理论路径数就是 5 的 8 次方量级。在稠密图上跑无上界的 [*4..]，很容易把数据库内存打满。两个习惯能规避绝大多数事故：

// 习惯一：给上界。深层环极少超过 8~10 跳，按业务实际设上限
MATCH path = (a:Asset)-[*4..8]->(a)
RETURN path

// 习惯二：先收窄再查。加标签过滤、限定关系类型，
// 把搜索范围从"全图"缩到"业务子图"
MATCH path = (a:Asset)-[:DEPENDS_ON*4..8]->(a)
RETURN path

这两条加上 3.2 的"返回 path"，就是环路查询的生产版本。顺带一提，性能压测方法论本身（怎么对图查询做基准测试）我写在《Neo4j 性能测试报告》里，那次实测里深层环查询正是延迟最高的一类。

3.5 APOC 里的正规军：apoc.nodes.cycles

如果装了 APOC 插件（官方扩展库），环检测有现成过程可调：

MATCH (n:Asset)
WITH collect(n) AS nodes
CALL apoc.nodes.cycles(nodes)
YIELD path
RETURN path

apoc.nodes.cycles 接收节点列表，检测这些节点之间所有的路径环并逐条产出 path，还能用 config 参数限定关系范围，适合"按批次喂节点"的定期巡检。一个容易踩的坑 ：网上不少文章把环检测写成 apoc.algo.cycle------这个过账不存在，apoc.algo 命名空间下只有 A*、Dijkstra 这类寻路算法。查环请认准 apoc.nodes.cycles，以所装 APOC 版本的文档为准。

四、孤立节点检测：一条 WHERE NOT 里的方向语义

4.1 查询与语义拆解

体检清单第二条，查孤立节点（10 个字符的主体，和环检测那条并称"双进门查询"）：

MATCH (n)
WHERE NOT (n)--()
RETURN n

(n)--() 表示"n 与任何节点之间存在任意一条关系"（不限定方向、不限定类型），NOT 取反后命中的就是零度节点 ------一条关系都没挂的"孤岛"。演示数据上命中 AST-0008（备份节点）：它创建了，但没有任何资产依赖它、它也不依赖任何资产。

四个字符 --() 里藏着两个必须掰开的语义点：

第一，方向。 --() 是无向匹配，双向都算；如果写成 NOT (n)-->()，含义变成"n 没有任何出边"------一个只被依赖、不依赖别人的叶子资产就会被误判成孤岛。判断"孤立"必须用无向形态，这是这条查询最容易写错的地方。

第二，范围。 MATCH (n) 扫全图所有标签。生产库上通常只关心业务标签，按标签收窄既快又准：

// 分标签统计孤点数量，适合接进巡检报表
MATCH (n:Asset)
WHERE NOT (n)--()
RETURN count(n) AS isolated_assets

4.2 孤点从哪来，怎么治

孤点不是查询删掉就完事，得溯源。常见的三个来源与对策：

来源	特征	对策
采集任务只发了节点、漏发关系	批量出现，时间集中	补跑关系同步，采集侧加"节点/关系数量比"校验
手工建了节点忘了连线	零星出现，name 常带"测试"字样	定期清点 + 建模规范
上游软删除，图里只删了关系	name/属性完好但业务已下线	引入生命周期状态属性，孤点按状态归档

第三种最隐蔽：节点在图里"活着"，业务上已经退网，报表里却还在计数。这类"僵尸资产"比纯孤点更值得警惕。

五、体检清单其余项：重复、缺失、度分布、连通分量

环和孤点之外，四类扩展检查凑齐整套体检。所有查询都在第二节的演示图上验证过预期输出。

重复节点------同一业务键出现多个节点，下游同步按 ID 幂等就会失效（每个节点一个 ID，同一资产被处理两遍）：

MATCH (n:Asset)
RETURN n.asset_code AS code, count(*) AS cnt
ORDER BY cnt DESC
LIMIT 10

演示数据上 AST-0002 计数为 2，一眼锁定 a2 与 a9 这对重复节点。治理方向是在同步任务里以业务键做合并，并考虑给 asset_code 建唯一约束防增量。

关键属性缺失------依赖分析要用的字段为空，比缺关系还隐蔽：

MATCH (n:Asset)
WHERE n.asset_code IS NULL OR n.name IS NULL
RETURN count(n) AS incomplete_assets

度分布异常（明星节点）------单个节点被成千上万节点依赖，是查询热点，也是单点故障的图谱投影：

MATCH (n:Asset)<-[:DEPENDS_ON]-(m)
RETURN n.asset_code AS code, count(m) AS in_degree
ORDER BY in_degree DESC
LIMIT 10

演示数据上第一名是 AST-0000（入度 6），与刻画的"核心交换"角色吻合；真实图谱上要警惕的是那种入度数量级领先的节点------它们既是查询热点，也是"一挂全挂"的图谱投影。

连通分量 ------资产依赖图谱理想状态是少数几个大连通域；如果碎成成百上千个小分量，说明大量资产间的链路断了，影响分析会"走不过去"。原生 Cypher 写连通分量很低效，这是 GDS（Graph Data Science 官方插件）的 wcc 弱连通分量算法的主场：

// 先把业务子图投影进内存，再跑 wcc 统计
CALL gds.graph.project(
  'asset-graph', 'Asset', {DEPENDS_ON: {orientation: 'UNDIRECTED'}}
)
CALL gds.wcc.stats('asset-graph')
YIELD componentCount, componentDistribution
RETURN componentCount, componentDistribution

gds.wcc.stats 返回分量总数和分布（最小/最大/平均规模及分位数），还有 stream（逐节点吐分量 ID）、write（把分量 ID 落回节点属性）两种模式。演示数据上结果会是 componentCount = 2：九个业务节点构成一个连通域，孤点 a8 独占一个分量------连"孤点检测"的结果都被连通分量从另一个角度印证了。对依赖图谱来说，componentCount 突然变大本身就是一条告警信号。

六、把体检变成定时任务：一次性的检查等于没检查

所有查询零依赖、纯只读，天然适合脚本化。笔者的做法是把清单固化成一个巡检脚本（cypher-shell 逐条执行），每项输出一个数字 + 阈值：

检查项	输出指标	建议阈值
自环 / 互指 / 深层环	环数量	> 0 告警
孤立节点	孤点数	较上周新增即关注
重复业务键	最大重复计数	> 1 告警
关键属性缺失	缺失数	> 0 告警
明星节点 Top1 入度	度数	超历史均值 3 倍关注
连通分量数	分量数	环比突增告警

指标接入监控平台的方式，和《云原生日志采集与检索架构》里讲的日志型任务的接入思路一致：定时任务产出结构化结果，平台负责阈值判断与告警收敛。体检的价值在于趋势------单次的数字意义有限，"孤点数连续三周上涨"才是真正要动手的信号。

七、踩坑点小结

1. 无上界变长路径是生产事故候选 ：[*4..] 语义上必然终止（关系唯一性兜底），但搜索空间随跳数指数膨胀，稠密图上一条查询就能打满内存。生产版本永远写 [*4..8] 这种带上界、限定标签与关系类型的形态；用 2025.06 的 REPEATABLE ELEMENTS 语义时，官方明确要求必须配下界/上界，否则可能无限多行。
2. 环查询返回 path 而非节点 ：RETURN a 只知道谁在环上，RETURN path + length(path) 才知道环长与走向，对账全靠它。
3. 孤立判定必须用无向 NOT (n)--() ：写成 NOT (n)-->() 会把只有入边的叶子资产误判成孤岛。
4. 别信 apoc.algo.cycle ：环检测是 apoc.nodes.cycles，apoc.algo 命名空间只有寻路算法；网上以讹传讹的文章不少。
5. 孤点要溯源不要一删了之：软删除残留的"僵尸资产"（业务已下线、图谱还计数）比纯孤点危害更大，靠生命周期属性区分。
6. 体检脚本要进定时任务：一次性检查等于没检查，趋势比快照有价值。

写在最后

图数据库的数据质量治理，本质上是用一组廉价的只读查询，换取"图谱可信"这个前提。两条入门查询------MATCH (a)-[*4..]->(a) 查环、MATCH (n) WHERE NOT (n)--() 查孤点------加起来不到 60 个字符，却能拦住影响分析转圈、资产失踪这两类最伤业务的事故；再配上重复键、属性缺失、度分布、连通分量四项扩展和 APOC / GDS 两个插件，就是一套可以直接搬走的巡检清单。

这套检查所在的图谱服务，长期靠社区版单实例运行，相关的高可用方案（DRBD 块级复制 + Keepalived 冷备切换）见《Neo4j 社区版高可用实战》；如果还在选型阶段，服务端部署与 Java 内嵌模式（含各自的写入性能表现）的对比见《Neo4j 内嵌模式实战》。这个系列的全部文章（Elasticsearch / Kafka / Flink / ClickHouse / Hadoop 等 55+ 篇运维实战）整理在《大数据运维实战系列目录》。

你们的资产图谱多久做一次数据体检？有没有被深层环坑过影响分析的经历？评论区聊聊你的检查项。