Neo4j 图数据库全景学习指南与 Cypher 语法深度解析

文档版本: v1.0.0
编写日期: 2026-09-05
适用技术栈: Python 3.13 / Neo4j 5.x~6.x (AuraDB 异步驱动) / FastAPI / Vue 3 / AntV G6 5.x
定位: 本文既是面向 Neo4j 初学者的 Cypher 查询语言从零到精通教程，也是本项目 知识图谱（Knowledge Graph）全套代码架构落地与前后端联动实战手册。

知识图谱拓扑网络全景与多跳语义关联 图 1：三维发光知识图谱语义拓扑网络与多跳关联推演

一、图数据库核心原理：为什么是 Neo4j？

1.1 关系型数据库 (RDBMS) 的“多跳之痛”

在关系型数据库（如 PostgreSQL / MySQL）中，表达“A 认识 B，B 认识 C，C 就职于公司 D”这种复杂关系时，通常需要设计两张表（Entity 表和 Relation 关联表）。

当我们要查询 “A 的 3 度关联好友有哪些，且他们都就职于什么公司” 时，SQL 需要进行多次 JOIN：

sql

-- 关系型数据库：多重 JOIN 导致“笛卡尔积爆炸”与索引反复扫描
SELECT e4.name, c.company_name
FROM Entity e1
JOIN Relation r1 ON e1.id = r1.source_id
JOIN Entity e2 ON r1.target_id = e2.id
JOIN Relation r2 ON e2.id = r2.source_id
JOIN Entity e3 ON r2.target_id = e3.id
JOIN Relation r3 ON e3.id = r3.source_id
JOIN Entity e4 ON r3.target_id = e4.id
JOIN Company c ON e4.company_id = c.id
WHERE e1.name = 'Alice';

随着数据量增长（上千万行时），多次 JOIN 的耗时呈指数级上升，数据库缓存被索引冲刷殆尽。

1.2 属性图模型 (Labeled Property Graph)

Neo4j 采用 属性图模型 (LPG)，其核心要素只有 4 个：

节点 (Node)：图中的实体（例如：人物、系统、组织、文档）。
标签 (Label)：节点的类型归类（例如：:KnowledgeEntity、:KnowledgeDocument），一个节点可拥有多个标签。
关系 (Relationship)：连接两个节点的有向边（例如：-[:RELATED_TO]->、-[:HAS_CHUNK]->）。
属性 (Property)：键值对（Key-Value），节点和关系都可以携带属性（例如节点的 name: "长城汽车"，关系的 weight: 0.85）。

 (长城汽车:KnowledgeEntity) ───[RELATED_TO {weight: 0.9}]──► (毫末智行:KnowledgeEntity)
         │                                                            │
   [HAS_CHUNK]                                                    [HAS_CHUNK]
         ▼                                                            ▼
  (分块 01:DocumentChunk)                                      (分块 02:DocumentChunk)

1.3 核心底层黑科技：无索引邻接 (Index-Free Adjacency)

传统数据库每次关联都需要通过 B-Tree 索引去查找匹配行（时间复杂度 $O(\log N)$）。

而 Neo4j 实现了 无索引邻接（Index-Free Adjacency）：

在物理磁盘和内存中，每个节点直接持有指向其所有相邻关系的物理内存双向链表指针。
从节点 A 遍历到相邻节点 B，直接解引用内存指针即可（时间复杂度 $O(1)$），完全与数据库的总数据量 $N$ 无关！
即使图中有 100 亿条边，从特定节点出发遍历 3 度关系的时间依然是毫秒级。

二、Cypher 查询语言完全手册 (语法详讲与实战)

Neo4j 图数据库内核与 Cypher 语法探索 图 2：Neo4j 高性能图遍历引擎与无索引邻接（Index-Free Adjacency）物理指针网络

Cypher 是 Neo4j 的声明式图查询语言（类似于 SQL 之于关系型数据库）。Cypher 的设计哲学是 “所见即所得”（ASCII-Art 风格）。

2.1 模式表示法 (ASCII-Art 哲学)

现实概念	Cypher 符号表示	说明
节点 (Node)	`()`、`(n)`、`(n:Entity)`	用圆括号代表一个圆球节点
关系 (Relationship)	`-->`、`--`、`-[r]->`	用破折号和箭头代表连线
带类型的关系	`-[r:RELATED_TO]->`	方括号内为关系变量名和关系类型
双向模式	`(a)-[:KNOWS]-(b)`	不指定箭头方向，匹配任意方向

2.2 基础读取语句 (`MATCH`, `WHERE`, `RETURN`)

语法格式

cypher

MATCH (变量:标签)
WHERE 条件
RETURN 结果字段 [AS 别名]
[ORDER BY 字段 [ASC | DESC]]
[SKIP 偏移量]
[LIMIT 最大条数]

实战范例

cypher

-- 1. 查询所有组织机构类型的实体
MATCH (e:KnowledgeEntity)
WHERE e.type = 'ORGANIZATION'
RETURN e.name AS entity_name, e.description AS desc
ORDER BY e.name ASC
LIMIT 10;

-- 2. 查询与“长城汽车”直接关联的所有实体及其关系
MATCH (a:KnowledgeEntity {name: '长城汽车'})-[r:RELATED_TO]->(b:KnowledgeEntity)
RETURN a.name AS source, r.relation AS relation, r.weight AS weight, b.name AS target;

2.3 节点的增删改 (`CREATE`, `MERGE`, `SET`, `REMOVE`)

`CREATE`（盲插，每次都会产生新节点）

cypher

CREATE (e:KnowledgeEntity {
  name: 'DriveGPT',
  type: 'PRODUCT',
  description: '自动驾驶认知大模型',
  createdAt: datetime()
})
RETURN e;

`MERGE`（根据主键存在性判断：存在则匹配，不存在则创建）

在构建知识图谱时，必须优先使用 MERGE 以保证幂等性：

cypher

MERGE (e:KnowledgeEntity {name: 'Coffee OS'})
ON CREATE SET 
  e.type = 'PRODUCT',
  e.description = '整车智能操作系统',
  e.createdAt = datetime()
ON MATCH SET 
  e.updatedAt = datetime(),
  e.accessCount = coalesce(e.accessCount, 0) + 1
RETURN e;

TIP

ON CREATE SET: 仅当节点初次被创建时触发（常用于记录创建时间戳）。
ON MATCH SET: 当节点已经存在被匹配到时触发（常用于累加计数或刷新更新时间）。

`SET` 与 `REMOVE`（属性修改与删除）

cypher

-- 修改属性
MATCH (e:KnowledgeEntity {name: 'Coffee OS'})
SET e.version = '3.0', e.status = 'ACTIVE';

-- 删除属性 (设为 NULL 或 REMOVE)
MATCH (e:KnowledgeEntity {name: 'Coffee OS'})
REMOVE e.old_field;

2.4 关系的创建、匹配与多跳遍历

创建带属性的关系

cypher

MATCH (a:KnowledgeEntity {name: '长城汽车'})
MATCH (b:KnowledgeEntity {name: 'Coffee OS'})
MERGE (a)-[r:RELATED_TO {relation: 'DEVELOPED'}]->(b)
ON CREATE SET r.weight = 0.95, r.createdAt = datetime()
RETURN r;

变长路径与多跳遍历 (`*1..N`)

这是图数据库最具威力的特性，用于多跳推理与路径发现：

cypher

-- 匹配从“长城汽车”出发，1 到 3 度以内的所有关联实体
MATCH p = (start:KnowledgeEntity {name: '长城汽车'})-[:RELATED_TO*1..3]->(target:KnowledgeEntity)
RETURN target.name, length(p) AS hops
LIMIT 20;

-- 最短路径查询：查找两个实体之间的最短依赖链
MATCH (a:KnowledgeEntity {name: '保定徐水智能制造基地'}), (b:KnowledgeEntity {name: '城市 NOH'})
MATCH p = shortestPath((a)-[:RELATED_TO*..5]-(b))
RETURN p;

2.5 常用内置函数

函数	功能说明	示例
`coalesce(a, b, ...)`	返回参数列表中第一个非空值（防空安全取值）	`coalesce(n.name, n.title, '未命名')`
`labels(n)`	获取节点的所有 Label 数组	`labels(n)[0]`
`type(r)`	获取关系的类型字符串	`type(r)` -> `'RELATED_TO'`
`toLower(str)`	转小写，常与 `CONTAINS` 配合做忽略大小写模糊搜索	`toLower(n.name) CONTAINS toLower('gpt')`
`substring(str, start, len)`	字符串截断（如生成摘要快照）	`substring(n.content, 0, 160)`
`id(n)` / `elementId(n)`	获取系统内置唯一 ID	`elementId(n)`

2.6 聚合与收集 (`count`, `collect`, `DISTINCT`)

统计实体的度数 (Degree)

cypher

MATCH (e:KnowledgeEntity)-[r:RELATED_TO]-()
RETURN e.name AS entity, count(r) AS degree
ORDER BY degree DESC
LIMIT 10;

将多行结果聚合为 JSON 数组 (`collect`)

cypher

-- 查询每个实体关联的所有邻居节点清单
MATCH (a:KnowledgeEntity)-[r:RELATED_TO]->(b:KnowledgeEntity)
RETURN a.name AS entity, 
       collect({ neighbor: b.name, rel: r.relation, weight: r.weight }) AS neighbors
LIMIT 5;

2.7 批量导入神器：`UNWIND`

在通过 API 或脚本批量导入数百上千条数据时，绝不能用循环执行单条 Cypher（网络 RTT 极高）。 Cypher 提供了 UNWIND 关键字，可将客户端传入的参数列表在数据库内部展开并行处理：

cypher

-- 客户端传入一个字典列表: $batch = [{source: 'A', target: 'B', rel: 'HAS'}, ...]
UNWIND $batch AS item
MERGE (a:KnowledgeEntity {name: item.source})
MERGE (b:KnowledgeEntity {name: item.target})
MERGE (a)-[r:RELATED_TO {relation: item.rel}]->(b)
SET r.weight = item.weight;

2.8 节点删除与级联清理 (`DELETE` vs `DETACH DELETE`)

CAUTION

在 Neo4j 中，如果一个节点上依然挂有边（无论入边还是出边），直接执行 DELETE n 会抛出约束异常报错！

cypher

-- 错误做法 (若有关系会报错):
MATCH (n:KnowledgeEntity {name: '测试节点'}) DELETE n;

-- 正确做法：先切断关系再删除节点 (DETACH DELETE)
MATCH (n:KnowledgeEntity {name: '测试节点'})
DETACH DELETE n;

孤儿实体（度数为 0）级联清理实战：

在文档重新发布或删除时，往往遗留下失去所有引用的废弃孤立实体。清理 Cypher 如下：

cypher

MATCH (e:KnowledgeEntity)
WHERE NOT ()-[:RELATED_TO]-(e) AND NOT ()-[:MENTIONS]->(e)
DELETE e;

2.9 索引与约束优化

没有索引时，MATCH (e:KnowledgeEntity {name: 'xxx'}) 会全表扫描所有节点。

1. 创建唯一主键约束 (强制唯一并自动建立高性能索引)

cypher

-- 实体名称唯一约束
CREATE CONSTRAINT c_entity_name IF NOT EXISTS
FOR (e:KnowledgeEntity) REQUIRE e.name IS UNIQUE;

-- 文档 ID 唯一约束
CREATE CONSTRAINT c_doc_id IF NOT EXISTS
FOR (d:KnowledgeDocument) REQUIRE d.id IS UNIQUE;

-- 切片 ChunkId 唯一约束
CREATE CONSTRAINT c_chunk_id IF NOT EXISTS
FOR (c:DocumentChunk) REQUIRE c.chunkId IS UNIQUE;

2. 分析执行计划 (`EXPLAIN` 与 `PROFILE`)

EXPLAIN <cypher>：查看执行计划，不实际执行。
PROFILE <cypher>：实际执行查询并打印详细的 DB Hits（数据库命中次数） 和内存消耗，优化慢查询必用。

三、本项目中 Neo4j 的代码架构与工程实现

从非结构化文档到三维知识图谱的提取跃升流水线 图 3：GraphRAG 核心流水线：非结构化文档解构与 LLM 知识图谱实体凝聚

本项目中的 Neo4j 图数据库模块位于 [app/modules/document/pipeline](file:///d:/self/agent-wll/app/modules/document/pipeline) 和 [app/modules/graph](file:///d:/self/agent-wll/app/modules/graph)。

3.1 连接池与云数据库适配 (`app/core/neo4j.py`)

系统封装了单例管理器 Neo4jClientManager：

异步驱动集成：基于官方推荐的 neo4j.AsyncGraphDatabase。
协议降级与自愈机制：
- 优先使用云端标准安全的 neo4j+s:// 路由协议。
- 若遇到企业内网代理阻拦路由发现时，自动无缝降级为 bolt+s:// 直连协议进行 TLS 握手。
Session 上下文管理：
- 通过 @asynccontextmanager 暴露 get_session()，确保每次请求用完自动安全归还连接池，避免连接泄漏。

python

# 核心查询调用示范
async with neo4j_manager.get_session() as session:
    result = await session.run(cypher_query, parameters)
    records = await result.data()

3.2 知识图谱图模型定义 (三层节点 + 两类关系)

(KnowledgeDocument) ──[:HAS_CHUNK]──► (DocumentChunk) ──[:MENTIONS]──► (KnowledgeEntity)
                                                                            │
                                                                    [:RELATED_TO]
                                                                            ▼
                                                                    (KnowledgeEntity)

KnowledgeDocument 节点：
- 代表一篇已发布的知识库文档。
- 属性：id, title, summary, status, createdAt, updatedAt。
DocumentChunk 节点：
- 代表文档结构化切片，与 RAG 向量检索共享相同分块粒度。
- 属性：chunkId, documentId, content, heading, chunkIndex。
KnowledgeEntity 节点：
- 由大模型在发布管线中自动从切片正文中提炼出的知识实体。
- 属性：name（主键）, type, description, aliases。
关系边：
- [:HAS_CHUNK]：文档包含分块（带 chunkIndex 顺序）。
- [:MENTIONS]：分块提及了实体（溯源核心）。
- [:RELATED_TO]：实体与实体之间的语义关联（带 relation, weight）。

3.3 图谱构建与清理管线 (`GraphBuildService`)

详见 [app/modules/document/pipeline/graph_build_service.py](file:///d:/self/agent-wll/app/modules/document/pipeline/graph_build_service.py)。

核心构建流程四步曲：

先清后建 (Clear Before Build)：
- 发布前先删除该文档在 Neo4j 中原有的所有旧节点、分块和旧关系，杜绝重复发布导致关系翻倍。
切片挂载：
- 循环写入分块节点，并建立 (d)-[:HAS_CHUNK]->(c)。
实体抽取与拓扑连接：
- 大模型提炼实体三元组：(c)-[:MENTIONS]->(e) 与 (e1)-[:RELATED_TO]->(e2)。
孤儿实体清理：
- 级联删除失去了任何文档引用的游离孤儿节点，防止图数据库无序膨胀。

3.4 图谱检索三剑客：接口 Cypher 逐行拆解

① 跨实体/文档/分块全文检索 (`search_graph`)

对应接口: GET /api/v1/graph/search?keyword=xxx

cypher

MATCH (n)
WHERE toLower(coalesce(n.name, '')) CONTAINS toLower($kw)
   OR toLower(coalesce(n.title, '')) CONTAINS toLower($kw)
   OR toLower(coalesce(n.heading, '')) CONTAINS toLower($kw)
   OR toLower(coalesce(n.description, '')) CONTAINS toLower($kw)
   OR toLower(coalesce(n.summary, '')) CONTAINS toLower($kw)
   OR toLower(coalesce(n.content, '')) CONTAINS toLower($kw)
RETURN labels(n)[0] AS label,
       coalesce(n.name, n.title, n.heading, n.id, n.chunkId) AS name,
       coalesce(n.id, n.chunkId, n.name) AS id,
       n.type AS type,
       n.title AS title,
       n.description AS description,
       n.documentId AS documentId,
       substring(n.content, 0, 160) AS snippet
ORDER BY label, name
LIMIT $limit

设计精髓：一条 Cypher 同时覆盖了实体节点、文档节点、段落分块三层数据，并使用 substring(..., 0, 160) 生成轻量高亮预览，支持前端点击穿透。

② 节点拓扑列表查询 (`list_nodes`)

对应接口: GET /api/v1/graph/nodes?type=PRODUCT

cypher

MATCH (e:KnowledgeEntity)
WHERE $type IS NULL OR $type = '' OR e.type = $type
RETURN e.name AS id, e.name AS name, e.type AS type,
       e.description AS description
LIMIT $limit

③ 实体间关系网络查询 (`list_edges`)

对应接口: GET /api/v1/graph/edges?limit=500

cypher

MATCH (a:KnowledgeEntity)-[r:RELATED_TO]->(b:KnowledgeEntity)
RETURN a.name AS source, b.name AS target,
       r.relation AS relation, r.relation AS relationship,
       r.weight AS weight
LIMIT $limit

设计精髓：返回标准有向边三元组 source -> target，同时返回 relation 与 relationship，提供双向防御兼容。

3.5 API 控制器与参数兼容 (`app/modules/graph/controller.py`)

python

@router.get("/search")
async def search_graph(query: GraphSearchDto = Depends(), ...):
    # 同时兼容 keyword 和 query 传参，消灭 422 异常
    kw = query.search_keyword
    if not kw:
        return []
    return await graph_build_service.search_graph(keyword=kw, limit=query.limit)

四、前端消费与可视化：AntV G6 5.x 交互式大屏集成

前端代码位于 [web/src/views/graph/GraphExplorerView.vue](file:///d:/self/agent-wll/web/src/views/graph/GraphExplorerView.vue)。

4.1 数据转换：从 SPO 三元组到 G6 渲染模型

后端返回的实体节点与关系边被转换为 G6 5.x 的规范格式：

typescript

const g6Data = {
  nodes: rawNodes.map((n) => ({
    id: n.name,
    data: { ...n, color: getNodeColor(n.type) },
  })),
  edges: rawEdges.map((e, idx) => ({
    id: `edge-${idx}`,
    source: e.source,
    target: e.target,
    data: { relationText: e.relationship || e.relation },
  })),
}

4.2 动力学布局调优 (彻底告别“节点挤在角落”)

针对最初力导向扎堆挤压在画布右下角的问题，通过以下四重调优彻底解决：

typescript

layout: {
  type: 'd3-force',
  center: [width / 2, height / 2], // 1. 显式绑定容器物理中心
  preventOverlap: true,
  nodeSize: 48,                    // 2. 预留充裕的防重叠碰撞体
  linkDistance: 240,               // 3. 显著拉长连线弹性距离 (从 150 增大到 240)
  nodeStrength: -900,              // 4. 强排斥力，节点相互均匀弹开扩散
  edgeStrength: 0.12,              // 5. 弱收拢力，防止过度聚集
  collideStrength: 1,
}

并且在渲染完成后调用：

typescript

await graphInstance.render()
await graphInstance.fitView() // 自动自适应视口尺寸居中

4.3 节点高亮、悬停与右侧抽屉穿透联动

悬停激活 (hover-activate)：鼠标悬停任意节点，非连通节点与连线透明度自动降至 20%，目标网络高亮发光。
连线白底胶囊标签：为关系文字增加 rgba(255, 255, 255, 0.9) 圆角背景，文字不再与线条重叠混淆。
无缝抽屉联动：点击任意节点触发 NodeEvent.CLICK，滑出右侧属性详情与一度邻居清单，支持在邻居之间无缝跳转。

五、生产环境高频 Cypher 调试与运维脚本备忘录

在日常开发与排查问题时，可直接在 Neo4j Browser 控制台或测试脚本中执行以下实用 Cypher：

1. 全库总览统计 (各类节点总数)

cypher

MATCH (n)
RETURN labels(n)[0] AS Label, count(n) AS Count
ORDER BY Count DESC;

2. 查看度数最高的 Top 10 核心实体 (中心度分析)

cypher

MATCH (e:KnowledgeEntity)-[r:RELATED_TO]-()
RETURN e.name AS Entity, e.type AS Type, count(r) AS Degree
ORDER BY Degree DESC
LIMIT 10;

3. 查看特定实体连接的完整一度子图

cypher

MATCH (a:KnowledgeEntity {name: '长城汽车'})-[r:RELATED_TO]-(b:KnowledgeEntity)
RETURN a, r, b;

4. 排查所有孤儿实体 (没有连通任何关系)

cypher

MATCH (e:KnowledgeEntity)
WHERE NOT (e)-[:RELATED_TO]-()
RETURN e.name, e.type, e.description;

5. 清理单篇文档及其专属分块 (开发调试回滚用)

cypher

MATCH (d:KnowledgeDocument {id: 'YOUR_DOC_ID'})
OPTIONAL MATCH (d)-[:HAS_CHUNK]->(c:DocumentChunk)
DETACH DELETE d, c;

6. 清理整个知识图谱全库数据 (慎用！)

cypher

MATCH (n)
DETACH DELETE n;

六、总结

通过本架构，系统将非结构化的 Markdown 文档解析为高密度的知识实体网络，不仅通过 Neo4j + Cypher 提供了毫秒级跨文档关系检索能力，还通过 AntV G6 5.x 在前端实现了工业级力导向交互可视化，打通了“文档发布 ➔ 实体抽取 ➔ 图谱存储 ➔ API 检索 ➔ 前端拓扑可视化”的完整工程闭环！

Neo4j 图数据库全景学习指南与 Cypher 语法深度解析 ​

一、图数据库核心原理：为什么是 Neo4j？ ​

1.1 关系型数据库 (RDBMS) 的“多跳之痛” ​

1.2 属性图模型 (Labeled Property Graph) ​

1.3 核心底层黑科技：无索引邻接 (Index-Free Adjacency) ​

二、Cypher 查询语言完全手册 (语法详讲与实战) ​

2.1 模式表示法 (ASCII-Art 哲学) ​

2.2 基础读取语句 (MATCH, WHERE, RETURN) ​

语法格式 ​

实战范例 ​

2.3 节点的增删改 (CREATE, MERGE, SET, REMOVE) ​

CREATE（盲插，每次都会产生新节点） ​

MERGE（根据主键存在性判断：存在则匹配，不存在则创建） ​

SET 与 REMOVE（属性修改与删除） ​

2.4 关系的创建、匹配与多跳遍历 ​

创建带属性的关系 ​

变长路径与多跳遍历 (*1..N) ​

2.5 常用内置函数 ​

2.6 聚合与收集 (count, collect, DISTINCT) ​

统计实体的度数 (Degree) ​

将多行结果聚合为 JSON 数组 (collect) ​

2.7 批量导入神器：UNWIND ​

2.8 节点删除与级联清理 (DELETE vs DETACH DELETE) ​

孤儿实体（度数为 0）级联清理实战： ​

2.9 索引与约束优化 ​

1. 创建唯一主键约束 (强制唯一并自动建立高性能索引) ​

2. 分析执行计划 (EXPLAIN 与 PROFILE) ​

三、本项目中 Neo4j 的代码架构与工程实现 ​

3.1 连接池与云数据库适配 (app/core/neo4j.py) ​

3.2 知识图谱图模型定义 (三层节点 + 两类关系) ​

3.3 图谱构建与清理管线 (GraphBuildService) ​

核心构建流程四步曲： ​

3.4 图谱检索三剑客：接口 Cypher 逐行拆解 ​

① 跨实体/文档/分块全文检索 (search_graph) ​

② 节点拓扑列表查询 (list_nodes) ​

③ 实体间关系网络查询 (list_edges) ​

3.5 API 控制器与参数兼容 (app/modules/graph/controller.py) ​

四、前端消费与可视化：AntV G6 5.x 交互式大屏集成 ​

4.1 数据转换：从 SPO 三元组到 G6 渲染模型 ​

4.2 动力学布局调优 (彻底告别“节点挤在角落”) ​

4.3 节点高亮、悬停与右侧抽屉穿透联动 ​

五、生产环境高频 Cypher 调试与运维脚本备忘录 ​

1. 全库总览统计 (各类节点总数) ​

2. 查看度数最高的 Top 10 核心实体 (中心度分析) ​

3. 查看特定实体连接的完整一度子图 ​

4. 排查所有孤儿实体 (没有连通任何关系) ​

5. 清理单篇文档及其专属分块 (开发调试回滚用) ​

6. 清理整个知识图谱全库数据 (慎用！) ​

六、总结 ​

Neo4j 图数据库全景学习指南与 Cypher 语法深度解析

一、图数据库核心原理：为什么是 Neo4j？

1.1 关系型数据库 (RDBMS) 的“多跳之痛”

1.2 属性图模型 (Labeled Property Graph)

1.3 核心底层黑科技：无索引邻接 (Index-Free Adjacency)

二、Cypher 查询语言完全手册 (语法详讲与实战)

2.1 模式表示法 (ASCII-Art 哲学)

2.2 基础读取语句 (`MATCH`, `WHERE`, `RETURN`)

语法格式

实战范例

2.3 节点的增删改 (`CREATE`, `MERGE`, `SET`, `REMOVE`)

`CREATE`（盲插，每次都会产生新节点）

`MERGE`（根据主键存在性判断：存在则匹配，不存在则创建）

`SET` 与 `REMOVE`（属性修改与删除）

2.4 关系的创建、匹配与多跳遍历

创建带属性的关系

变长路径与多跳遍历 (`*1..N`)

2.5 常用内置函数

2.6 聚合与收集 (`count`, `collect`, `DISTINCT`)

统计实体的度数 (Degree)

将多行结果聚合为 JSON 数组 (`collect`)

2.7 批量导入神器：`UNWIND`

2.8 节点删除与级联清理 (`DELETE` vs `DETACH DELETE`)

孤儿实体（度数为 0）级联清理实战：

2.9 索引与约束优化

1. 创建唯一主键约束 (强制唯一并自动建立高性能索引)

2. 分析执行计划 (`EXPLAIN` 与 `PROFILE`)

三、本项目中 Neo4j 的代码架构与工程实现

3.1 连接池与云数据库适配 (`app/core/neo4j.py`)

3.2 知识图谱图模型定义 (三层节点 + 两类关系)

3.3 图谱构建与清理管线 (`GraphBuildService`)

核心构建流程四步曲：

3.4 图谱检索三剑客：接口 Cypher 逐行拆解

① 跨实体/文档/分块全文检索 (`search_graph`)

② 节点拓扑列表查询 (`list_nodes`)

③ 实体间关系网络查询 (`list_edges`)

3.5 API 控制器与参数兼容 (`app/modules/graph/controller.py`)

四、前端消费与可视化：AntV G6 5.x 交互式大屏集成

4.1 数据转换：从 SPO 三元组到 G6 渲染模型

4.2 动力学布局调优 (彻底告别“节点挤在角落”)

4.3 节点高亮、悬停与右侧抽屉穿透联动

五、生产环境高频 Cypher 调试与运维脚本备忘录

1. 全库总览统计 (各类节点总数)

2. 查看度数最高的 Top 10 核心实体 (中心度分析)

3. 查看特定实体连接的完整一度子图

4. 排查所有孤儿实体 (没有连通任何关系)

5. 清理单篇文档及其专属分块 (开发调试回滚用)

6. 清理整个知识图谱全库数据 (慎用！)

六、总结