每天认识一个组件：JanusGraph

一、引言

传统关系型数据库擅长处理结构明确的表和事务，例如查询某个用户的信息只需要通过主键定位一行记录。但当问题变成下面这些形式时，查询重心已经从"实体"转向"关系"：

• 某个账户在三跳以内与哪些高风险账户存在资金往来？
• 两个用户之间经过了哪些设备、手机号或地址产生关联？
• 某个商品通过购买、浏览和收藏关系能够触达哪些潜在用户？
• 某台服务器故障后，会沿依赖关系影响哪些服务？
• 某个知识实体与其他实体之间存在哪些语义路径？

关系型数据库可以通过多表 JOIN、递归 CTE 或中间关系表回答这些问题，但随着路径深度、关系类型和数据规模增加，SQL 会变得复杂，执行成本也难以预测。

图数据库把实体表示为顶点、把关系表示为边，查询从"连接多张表"转变为"沿着边遍历"。

图数据库并不会自动让所有查询变快。它的优势主要体现在关系密集、多跳遍历和结构经常演化的数据上。

二、JanusGraph 到底是什么

JanusGraph 为上述场景提供了一套面向超大规模属性图的分布式存储与查询方案，JanusGraph 本身更像一个图数据库引擎，处于应用和底层存储之间，而不是包办所有能力的一体化数据库。

它主要负责：

• 属性图数据模型；
• 顶点、边和属性的序列化；
• Gremlin 查询执行与优化；
• Schema 和索引管理；
• 事务、缓存及 ID 分配；
• 对存储后端和索引后端的适配。

底层系统负责：

• 图数据持久化；
• 数据复制和故障恢复；
• 全文、范围与地理空间搜索；
• 分布式数据处理。

这种模块化设计让 JanusGraph 能复用成熟的大数据基础设施，但也提高了部署、索引一致性和运维管理的复杂度。

JanusGraph 支持两种常见使用方式：

• 嵌入式模式 ：把 JanusGraph 嵌入 Java 应用，同一个 JVM 内执行查询、管理事务和缓存；
• 服务模式 ：通过 Gremlin Server 接收本地或远程客户端提交的 Gremlin 查询。

生产环境更常见的是服务模式，应用不必与图数据库运行在同一个 JVM 中。

三、数据模型：属性图如何落到宽表存储

1.属性图模型

JanusGraph 使用 Apache TinkerPop 定义的属性图模型。核心元素包括：

• Vertex ：顶点，表示用户、商品、设备等实体；
• Edge ：边，表示购买、关注、登录等关系；
• Property ：属性，附着在顶点或边上；
• Label ：标签，用于描述顶点或边的类型。

与只能表达"边存在"的简单图模型相比，属性图可以直接在关系上记录金额、时间和渠道等信息。

2.邻接表存储

JanusGraph 使用邻接表保存图。每个顶点在底层存储中对应一行，顶点的属性和与其相连的边作为这一行中的单元格。

这种布局有两个直接结果。

第一，相邻关系读取集中：查询某个顶点的属性和邻接边时，JanusGraph 可以通过顶点 ID 定位一行，再读取指定列范围，不必对整张图做 JOIN。

第二，一条边通常存储两份：边会分别出现在两个端点的邻接表中，以便从任意方向遍历。这种额外存储开销也是作为邻接表设计的代价。

JanusGraph 还会按边标签定义的排序键维护邻接关系的顺序。对高出度顶点，可以利用这个顺序和顶点中心索引，只读取满足条件的边，而不是把所有边加载到内存再过滤。

3.为什么采用 Bigtable 风格模型

JanusGraph 要求底层后端支持宽行模型，并能按列排序和高效执行列范围读取。这与 Cassandra、HBase、ScyllaDB 等系统的数据访问模式相匹配。

一次典型的局部遍历可以抽象为：

顶点 ID
   |
   v
定位宽行
   |
   v
按 边标签 + 排序键 读取一段列
   |
   v
解析目标顶点 ID
   |
   v
继续下一跳

这也是 JanusGraph 更擅长局部、多跳遍历，而不适合无条件扫描全图的原因。

四、索引体系：图查询性能的关键

JanusGraph 的索引可以分为两层：

1.Composite Index：精确查询优先

组合索引由主存储后端维护，适合一个或多个属性的等值查询。

组合索引的特点：

• 对等值查询效率高；
• 多字段组合索引要求查询包含全部索引字段；
• 不需要 Elasticsearch 或 Solr；
• 可以定义唯一约束；
• 图数据和组合索引通过同一个存储后端写入，其原子性和一致性取决于后端能力。

例如，在(name, age) 上建立组合索引后：

// 可以完整使用组合索引
g.V().has('name', 'Alice').has('age', 30)

// 不能只靠该索引查询，因为缺少 name
g.V().has('age', 30)

2.Mixed Index：复杂检索优先

混合索引需要 Elasticsearch、Solr 或 Lucene 等索引后端，适合：

• 全文检索；
• 数值和时间范围查询；
• 地理空间查询；
• 多个已索引字段的灵活组合；
• 由外部索引完成排序。

g.V().
  has('description', textContains('graph database')).
  has('createTime', gte(startTime))

混合索引比组合索引灵活，但要承担额外成本：

• 需要部署和维护索引集群；
• 图存储与索引后端之间存在双写；
• 索引更新可能存在短暂可见性延迟；
• 混合索引不支持唯一性约束。

3.Vertex-centric Index：解决超级节点遍历

假设一个明星用户有数千万条关注关系：

g.V(starId).
  outE('follows').
  has('time', gte(startTime)).
  limit(100)

如果没有顶点中心索引，系统可能需要读取该顶点的大量follows 边，再按时间过滤。顶点中心索引可以按时间等排序键组织这些边，只读取目标范围。

超级节点 adjacency list

未经优化：
[2019][2020][2021][2022][2023][2024][2025][2026]
  ________________读取大量边，再过滤_______________/

按 time 建立顶点中心索引：
[2019][2020][2021][2022][2023][2024][2025][2026]
                                        __范围读取__/

4.索引选择原则

查询需求	推荐索引
用户 ID、订单号精确匹配	Composite Index
多字段联合等值且字段固定	Composite Index
唯一性约束	Unique Composite Index
全文、模糊、范围或地理查询	Mixed Index
高出度顶点的局部边过滤	Vertex-centric Index
外部索引结果排序	Mixed Index

生产环境建议设置query.force-index=true ，禁止未命中索引的全图扫描。否则一条看似普通的g.V().has(...)查询可能退化为扫描全部顶点。

五、事务与一致性：不能只看到"支持事务"

JanusGraph 的大部分操作都运行在事务中，但"支持事务"并不意味着所有后端都提供相同的 ACID 语义，因此，JanusGraph 的事务语义受底层存储后端影响。

应用事务
   |
   v
JanusGraph 事务层
   |
   +-- Schema 约束
   +-- 缓存与冲突检测
   +-- 可选锁机制
   |
   v
存储后端的一致性与原子写能力

1.事务必须显式结束

在默认 TinkerPop 事务语义下，线程执行第一个读写操作时自动开启事务，但 JanusGraph 不会替你确定业务边界。应用必须调用：

graph.tx().commit() 或者 graph.tx().rollback()

长期不关闭事务可能导致读取旧快照、缓存持续占用，以及客户端下一次请求仍看不到其他事务已经提交的数据。

2.最终一致后端上的约束

在 Cassandra、HBase 等最终一致后端上，JanusGraph 默认不会对所有写操作加锁。对唯一索引或存在并发冲突的 Schema 元素，需要按需配置ConsistencyModifier.LOCK 。

事务提交
   |
   v
获取约束元素的锁
   |
   v
重新读取并检查是否被其他事务修改
   |
   +-- 已变化 --> 提交失败
   |
   v
写入后端并释放锁

锁会增加写延迟，在高并发热点上还可能产生争用。建议只在一致性要求高、冲突概率较低的地方使用。需要频繁执行强一致约束的业务，应重新评估存储后端或业务模型。

3.图存储与混合索引不是天然原子双写

一次业务写入可能涉及：

              +--> Cassandra / HBase：写图数据
业务事务 -----|
              +--> Elasticsearch / Solr：写索引

如果第一步成功而第二步失败，索引可能落后于图数据。最终一致后端还可能出现短暂的陈旧索引项、半边或"幽灵顶点"。JanusGraph 提供事务日志、恢复和索引修复能力，但应用仍需监控失败、设计重试，并准备索引重建或清理流程。因此，不应把"事务已提交"等同于"所有混合索引查询立刻可见"。

六、JanusGraph 的主要特性与优势

• 面向大规模关系数据：JanusGraph 通过 Cassandra、HBase 等后端把图数据分散到多台机器，并依赖后端处理副本、扩容和故障恢复。它适合单机难以承载的图规模和高并发图访问。
• 存储与索引可插拔：用户可以根据已有基础设施选择复用适配。

组件	常见选择	作用
存储后端	Cassandra、HBase、ScyllaDB、Bigtable	保存顶点、边、属性及组合索引
本地后端	BerkeleyDB JE	本地开发、测试或单机应用
索引后端	Elasticsearch、Solr	分布式全文、范围、地理检索
本地索引	Lucene	单机嵌入式检索
查询接口	Gremlin Server	远程图查询
批量分析	Hadoop-Gremlin、Spark	OLAP 与批处理

• 原生支持 Gremlin：JanusGraph 原生集成 Apache TinkerPop，可使用 Gremlin 图遍历语言和 Gremlin Server。TinkerPop 同时面向图数据库 OLTP 和图分析 OLAP，JanusGraph 因而能复用相应生态。Gremlin 的优势是能直接表达"从哪里出发、沿什么关系、遍历几层、如何过滤"。
• Schema 可演进：JanusGraph 支持显式或隐式 Schema，但建议显式定义顶点标签、边标签和属性键，显式 Schema 有助于类型检查、协作开发和索引管理，并可在系统运行期间继续增加新的类型。已经提交的属性键、顶点标签或边标签定义不能直接修改；可以重命名旧类型，或创建新类型完成演进。
• 支持图事务和并发访问：JanusGraph 支持线程绑定事务，也支持由多个线程共同使用的 threaded transaction。事务失败可能来自网络异常、资源不足、锁争用或后端故障，调用方应具备提交失败处理和事务级重试能力。

七、适用场景与不适用场景

1.适用场景

• 风险控制与反欺诈：顶点可以表示账户、设备、IP、银行卡和手机号，边表示登录、转账、绑定和共享。图遍历可以识别团伙、环路、共享设备和多跳资金关系。
• 知识图谱：顶点表示实体，边表示语义关系。JanusGraph 适合保存结构持续演化、关系类型丰富且需要路径查询的知识网络。
• 推荐和用户关系网络：用户、商品、内容和标签组成异构图，可通过共同邻居、路径模式和相似关系生成候选集。最终的机器学习排序通常仍需由推荐系统完成。
• 网络与 IT 拓扑：设备、服务、接口和依赖关系天然构成图。运维系统可以沿依赖链分析故障影响范围。
• 数据血缘与权限分析：任务、表、字段、报表和用户之间形成复杂依赖。图查询适合回答字段来源、下游影响和权限传递问题。

2.不适用场景

• 数据关系简单，主要按主键查询；
• 强依赖跨多行、强隔离级别事务；
• 以大范围聚合、报表和列式扫描为主；
• 团队不具备 Cassandra、HBase、Elasticsearch 与 Gremlin 的运维经验；
• 数据量较小，单机图数据库已经满足需求；
• 查询主要是全图扫描，没有稳定的起点和局部遍历模式。

一个实用的判断方法是：

关系是否属于核心业务数据？
          |
      +---+---+
      |       |
     否       是
      |       |
优先考虑   是否经常需要多跳、
关系库/   路径或邻居查询？
文档库       |
          +--+--+
          |     |
         否     是
          |     |
    搜索/关系库  数据是否需要
                分布式扩展？
                   |
                +--+--+
                |     |
               否     是
                |     |
          单机图数据库  考虑 JanusGraph

八、部署与使用

//下载并解压对应版本
unzip janusgraph-1.1.0.zip
cd janusgraph-1.1.0

//启动 Gremlin Console
bin/gremlin.sh

//启动服务端
bin/janusgraph-server.sh start

//默认端口是`8182`。

生产部署拓扑建议如下：

上线前至少完成以下工作：

• 固定 JanusGraph、存储后端、索引后端和客户端版本；
• 显式定义 Schema 与索引；
• 设置query.force-index=true ；
• 设计合理的事务大小和超时；
• 监控事务成功率、后端调用失败率与响应时间；
• 规划数据、Schema 和索引备份；
• 演练节点故障、索引不可用与重建流程；
• 对热点顶点、长路径和大结果集做压力测试。

JanusGraph 可通过 Dropwizard Metrics 统计事务开始、提交、回滚次数，以及后端操作的次数、失败数和响应时间分布。

JanusGraph 提供storage.batch-loading 以提高批量写入速度。它会关闭一部分内部一致性检查，其中包括锁，因此导入程序必须自行保证数据一致性。

源数据
   |
   v
去重与一致性校验
   |
   v
预先创建 Schema 和索引
   |
   v
开启 batch-loading
   |
   v
先导入顶点并记录外部 ID -> JanusGraph ID 映射
   |
   v
根据映射并行导入边
   |
   v
关闭 batch-loading
   |
   v
检查数量、抽样路径和索引状态

启用批量模式时，建议设置：

schema.default=none
storage.batch-loading=true

这样可以避免多个导入任务并发自动创建类型，造成严重的数据完整性问题。

批量导入还要关注：

• ids.block-size ：过小会频繁申请 ID 块；
• storage.buffer-size ：增大可以减少请求次数，但也会提高单次请求延迟和失败影响；
• storage.read-attempts 、storage.write-attempts ：用于后端高负载时的重试；
• 超级节点：短时间向单个顶点写入数百万条边可能失败；
• 混合索引：同步写索引会成为导入瓶颈，可根据业务设计索引创建和重建流程。

九、常见问题

1.查询结果正确，但速度很慢

先执行 Gremlin 的explain() 或profile() ，检查查询是否命中索引。

常见原因：

• g.V().has(...) 没有全局索引；
• 组合索引缺少其中一个字段；
• 对高出度顶点没有建立顶点中心索引；
• 混合索引不包含排序字段，结果只能在内存排序；
• 一次查询返回的数据量过大。

治理原则：

先用全局索引找到少量起点
           |
           v
沿明确的边标签进行局部遍历
           |
           v
使用顶点中心索引限制超级节点的边集合
           |
           v
尽早 limit、dedup 和 project

2.刚写入的数据通过混合索引查不到

可能原因包括：

• Elasticsearch 或 Solr 尚未刷新；
• 索引后端写入失败；
• 图存储与索引之间出现不一致；
• 新增索引后没有对历史数据执行 reindex；
• 索引仍处于 REGISTERED 等非可用状态。

不要把"重新提交同一业务写入"作为首选修复方式，否则可能产生重复顶点或边。应先检查索引状态、索引后端日志和 JanusGraph 事务日志，再决定是否重建索引。

3.创建了索引，查询仍未使用

如果属性键在创建索引前已经有数据，需要执行索引生命周期操作和REINDEX 。只有在同一个管理事务中创建新属性键和索引时，索引才能直接用于之后写入的数据。

创建索引
   |
   v
等待索引状态达到 REGISTERED / ENABLED
   |
   v
对历史数据执行 REINDEX
   |
   v
检查最终状态
   |
   v
用 explain/profile 验证

4.唯一索引仍出现重复数据

在最终一致后端上，仅调用unique() 不足以覆盖所有并发场景。需要为唯一组合索引及相关 Schema 元素配置锁，并确认后端达到所需的一致性级别。

批量加载模式会禁用锁和部分一致性检查，因此开启该模式时更不能依赖 JanusGraph 自动保证唯一性。

5.事务提交失败

事务可能因为网络超时、资源不可用、锁冲突或后端故障而失败。JanusGraph 会对部分临时故障执行内部重试，但应用仍应把提交失败视为正常故障路径。

处理原则：

• 捕获异常；
• 回滚当前事务；
• 区分临时故障和永久故障；
• 只对满足幂等条件的完整业务事务重试；
• 监控重试次数，避免无限重试。

6.读不到其他线程刚提交的数据

检查当前线程是否一直持有旧事务。JanusGraph 会维持事务开始时的状态；一个长时间未结束的事务可能持续返回旧结果。完成一个业务单元后应及时commit() 或rollback() 。

7.超级节点读写异常

高出度顶点会带来：

• 邻接表过大；
• 单点热点；
• 边过滤成本高；
• 批量写入失败；
• 后端单行或分区压力。

应综合使用顶点中心索引、按时间或业务维度拆分节点、限制单次事务写入量，以及分阶段导入，一次或短时间内向单个顶点加载数百万条边可能在部分后端失败。