Graph 图数据库模块概述

Graph 模块为应用提供面向图数据（Graph Data）的统一能力。这里的“图数据”不是 MySQL 等传统关系型数据库中的表和关联查询，而是以实体（节点）、实体之间的关联（边）以及由它们组成的路径为核心的数据。它适合保存“谁与谁有什么关系、关系如何传播、关系是否发生变化”这类信息，并支持在多种图数据库之间使用相近的业务语义完成建模、写入、导入和查询。

当前 Graph 模块是图数据库的适配层 SDK，不是一个独立的图数据库产品，也不包含管理后台、图形化编辑器或面向最终用户的应用界面。开发者可以把它嵌入自己的服务，再根据业务需要建设知识库管理、数据导入、图探索和查询等产品功能。

为什么需要图数据

传统表结构擅长描述固定字段和明确的聚合关系，但在以下问题上往往需要大量关联表、连接查询和业务代码：

• 一个实体与哪些实体直接或间接相关？
• 两个实体之间经过哪些关系可以连通？
• 某个事件、人物或资源的影响范围是什么？
• 多份文档中提到的同一对象，如何合并成一个统一实体？
• 新增一种关系后，如何继续查询原有数据，而不大规模改造表结构？

图数据库把实体和实体之间的关联作为一等数据，使这些问题能够直接围绕“节点、边和路径”表达。它特别适合关联网络复杂、结构持续变化、需要多跳分析或需要解释数据来源的业务。

主要解决的问题

统一接入不同图数据库

应用不必把业务逻辑绑定在某一种图数据库的客户端和查询方言上。Graph 模块为常见的连接管理、数据模型、写入、导入和查询提供统一入口；在统一语义无法覆盖后端特性的地方，仍可以使用后端原生能力。

这样可以降低以下成本：

• 在不同环境、项目或客户部署不同图数据库时重复开发；
• 将业务代码、数据库连接细节和查询方言混在一起；
• 更换后端或同时维护多个后端时，难以识别能力差异；
• 应用直接依赖数据库异常文本，导致错误处理不稳定。

让图谱建设从数据模型开始

图谱建设不仅是把数据写入数据库，还需要明确实体类型、关系类型、属性、索引和演进规则。Graph 模块支持围绕一个 Graph Space 维护这些结构，使应用能够在导入数据前完成模型准备，在结构变化时进行检查、比较和迁移。

这里的 Graph Space 可以理解为一个相互隔离的图数据空间，作用类似传统数据库中的“库”或一个独立命名空间。不同租户、知识库、项目或环境通常应使用不同的 Space，避免数据和结构互相污染。

支持持续导入和长期维护

图谱通常不是一次性生成的：最初可能导入一批历史文件，之后还会不断接收新文件、业务事件和人工修订。Graph 模块覆盖节点和边的幂等写入、批量导入、异步导入、失败记录和恢复信息，便于上层实现：

• 首次全量建库；
• 按文件、批次或时间窗口增量更新；
• 重复导入时避免产生重复实体和关系；
• 大批量任务的进度展示、失败重试和断点续传；
• 结构升级后继续导入新数据。

任务调度、持久化、跨实例协调和业务级去重策略仍由上层应用负责，SDK 提供的是可组合的执行契约。

用统一语义表达关系查询

应用可以围绕实体、关系、属性、方向、路径、过滤、排序、聚合和分页构建查询，不必在每个业务模块中重复处理不同数据库的参数绑定、结果转换和能力差异。

典型查询包括：

• 查询某个实体的一跳或多跳邻居；
• 按关系类型、方向和属性筛选路径；
• 查找两个实体之间的关联链路；
• 查询某类实体的数量、分布和关联强度；
• 将多个查询结果合并后统一返回；
• 对大结果集进行分页、游标读取和数量限制。

对于最短路径、数据库专属函数、管理语句或其他后端特性，可以使用原生查询。统一查询保证的是业务语义和安全边界，不承诺不同数据库拥有完全相同的执行计划或全部高级特性。

适用场景

知识图谱与知识库

从小说、报告、网页、合同、技术文档等非结构化内容中识别人物、组织、地点、事件和它们之间的关系，形成可持续更新的知识网络，为问答、检索增强、事实核验和关系探索提供结构化数据。

在这一场景中，文档解析和大模型负责从文本中发现候选实体与关系，Graph 模块负责保存、维护、查询和演进这些结构化结果。两者职责分离，便于替换抽取模型或调整图谱存储后端。

推荐与关联发现

根据用户、商品、内容、标签、行为和相似关系，发现直接或间接关联，用于推荐候选、相似对象检索、兴趣扩展和关系解释。

风险、反欺诈与影响分析

将账户、设备、交易、地址、组织和事件连接起来，识别异常关系、共同来源、环路和影响范围，支持风险调查与审计追踪。

组织、权限与资源关系

描述用户、团队、角色、资源、数据集和操作之间的授权关系，用于权限继承、关系追溯和资源影响分析。具体的认证、授权决策和合规审计仍应由业务系统负责。

数据血缘与依赖分析

记录数据集、任务、服务、字段和版本之间的依赖，用于变更影响分析、故障定位、资产发现和治理。

事件网络与业务流程

将订单、客户、设备、工单、服务和事件按照时间或业务关系连接起来，分析流程经过、上下游影响和异常传播。

从数据到图谱的典型流程

一个完整的图谱业务通常经过以下阶段：

1. 确定业务对象：明确需要管理的实体、关系、属性和唯一标识。
2. 划分数据空间：为租户、项目、知识库或环境选择独立的 Graph Space。
3. 建立图模型：定义节点类型、边类型、属性和常用查询索引。
4. 准备数据来源：接入业务数据库、文件、消息、外部 API 或文档抽取结果。
5. 执行首次导入：批量写入节点和边，校验数量、关系完整性和数据质量。
6. 持续增量更新：根据新文件、业务事件或人工修订执行幂等更新。
7. 面向业务查询：提供邻居查询、路径分析、聚合统计、检索增强和图探索。
8. 持续治理：监控健康状态，处理失败任务，评估 Schema 变化，并根据后端能力调整查询。

Graph 模块负责其中与图数据库交互的统一执行能力；数据清洗、实体消歧、业务规则、审批流程和用户体验由上层系统决定。

SDK 的职责边界

Graph 模块适合被应用服务、知识库服务、数据管道或管理后台作为底层能力使用。它主要负责：

• 统一的图数据模型和后端适配；
• Space、Schema、索引和连接健康检查；
• 节点、边的写入、更新、删除和批量导入；
• 查询、分页、游标、执行计划和结果保护；
• 事务、能力声明、错误分类和后端限制提示；
• 为文档知识抽取结果提供可持续写入图谱的基础能力。

以下能力不属于 SDK 的产品职责，需要由使用者自行实现或组合其他组件：

• Web 管理后台、可视化图编辑器和图探索界面；
• 用户、租户、角色、权限和凭据管理；
• 文件上传、文档解析、分段、OCR 和数据清洗；
• 大模型提示词、实体消歧和业务规则编排；
• 分布式任务调度、消息队列和跨服务一致性；
• 图数据库部署、备份、高可用、扩缩容和运维治理。

后端选择的基本考虑

Neo4j 和 Nebula 都可以作为 Graph 模块的后端，但两者在数据库架构、查询语言、索引要求、事务和高级查询能力上存在差异。选择后端时，应结合数据规模、部署方式、查询类型、事务要求、运维能力和目标环境进行评估。

在应用设计中，建议优先使用统一能力，并通过能力检查和真实环境测试确认目标后端是否支持某项功能。需要后端专属能力时，应将原生查询集中在适配层或业务边界内，避免把方言扩散到整个应用。

文档导航

建议按以下顺序继续阅读：

1. 核心概念：理解节点、边、Space 和图模型；
2. 快速开始：完成连接、建模、写入和查询闭环；
3. 数据模型与Schema 定义：设计实体、关系和索引；
4. 节点与边写入、批量导入与异步导入：建设和维护图数据；
5. 查询概览与遍历查询：实现关系检索和路径分析；
6. 后端能力对比：评估 Neo4j 与 Nebula 的差异；
7. 知识抽取模块：从非结构化内容生成可审核、可追溯并可长期维护的图数据。

生产使用前，建议继续阅读测试指南、Docker 真实环境测试、故障排查和生产使用建议。