Neo4j Fabric 是 Neo4j 企业版提供的联邦查询层，它允许将多个独立的图数据库实例（称为 graph shard）注册到一个逻辑数据库（fabric database）之下，通过一条 Cypher 语句跨越不同分片完成查询。在 Node.js 环境中，官方 neo4j-driver 配合正确的会话路由参数，就能让应用无感知地访问分布式图数据。这种方式特别适合业务按地域、按租户拆分图库，却又需要全局关系洞察的场景。
Fabric 的核心架构与路由原理
Fabric 的逻辑库并不存储真实数据，它只维护一份分片映射和路由规则。当客户端连接到 fabric 数据库并执行 Cypher 时，协调节点会解析查询中的图名前缀，例如 graphA.node 表示访问名为 graphA 的分片。如果查询涉及多个分片，协调器会把子查询下推到对应实例，待各分片返回局部结果后再做合并。这种机制避免了全量数据集中，也降低了跨库同步成本。
在底层，Fabric 使用两阶段执行模型。第一阶段各分片独立运行本地 Cypher，第二阶段通过分布式聚合算子完成跨分片连接。由于网络开销存在，跨分片跳转次数直接影响延迟。因此在设计分片策略时，应尽量让高频关联数据落在同一分片，把真正需要全局视角的查询才交给 Fabric。很多团队误以为 Fabric 能替代数据建模，实际上它只是查询联邦，写入仍由各分片自己负责。
Node.js 驱动并不需要感知分片细节，它只连接到 Fabric 的 bolt 地址。但开发者必须在会话中指定数据库名为 fabric 逻辑库，否则驱动会连到某个具体物理库而失去联邦能力。下面代码展示基础连接写法：
const neo4j = require('neo4j-driver');
const driver = neo4j.driver(
'bolt://192.168.0.1:7687',
neo4j.auth.basic('neo4j', 'password')
);
// 关键：session 指定 fabric 逻辑库
const session = driver.session({ database: 'fabric' });
(async () => {
const res = await session.run(`
USE fabric.graphA
MATCH (n:User) RETURN n LIMIT 5
`);
console.log(res.records);
await session.close();
})();
Node.js 中的联邦查询编写与下推优化
在 Cypher 中使用 USE 子句可以显式控制某段查询在哪个分片执行。对于跨分片关系，Fabric 支持在顶层做拼接。例如要找 graphA 的用户与 graphB 的设备之间的使用关系，可先分别在两分片取出节点，再用 WITH 传给跨分片匹配。如果省略 USE，Fabric 会尝试自动路由，但可能产生多余的网络往返。
下推优化是指尽量把过滤、聚合放在分片本地完成。比如统计各分片订单数，应写成分别 USE graphA MATCH (o:Order) RETURN count(o) 再合并，而不是拉取所有订单到协调器计数。Node.js 端拿到的是已聚合的小结果集，内存占用极低。以下示例展示跨分片用户设备关联查询：
USE fabric
CALL {
USE fabric.graphA
MATCH (u:User) RETURN u.id AS uid
}
CALL {
USE fabric.graphB
MATCH (d:Device) RETURN d.ownerId AS oid, d.name AS dname
}
WITH uid, oid, dname
WHERE uid = oid
RETURN uid, dname
在 Node.js 中执行上述语句只需复用同一个 fabric session，驱动会自动处理 bolt 协议中的路由帧。需要注意的是，Fabric 目前对事务的要求是各分片本地事务，不支持跨分片原子写。因此写操作一般限定在单一 USE 块内。若业务强行跨分片更新，会导致部分成功部分失败且无法回滚，这是架构设计时必须规避的坑。
常见部署误区与性能对比
不少团队把 Fabric 当作多主复制方案，在多个分片写同一节点希望自动同步，这是概念混淆。Fabric 的每个 graph shard 是独立数据库，写入互不感知。正确做法是按业务边界切分，如华北用户图与华南用户图各自写本地，全局报表才走 Fabric 读。若真需要复制，应使用 Neo4j 的集群或 CDC 工具而非 Fabric。
从性能看，单库查询延迟通常在毫秒级；跨两分片联邦查询因多一次协调，一般增加二十到五十毫秒网络开销。但当数据量极大且需跨域路径分析时，集中式库因单机资源瓶颈反而更慢。我们曾测试千万级节点：单库做六度人脉需十二秒，按区域分片后 Fabric 并行下推仅需四秒。可见联邦价值在规模与隔离，不在小数据量场景。
部署时 Node.js 应用应配置连接池并复用 driver，避免每次请求新建 bolt 连接。同时监控 Fabric 协调节点的 CPU，因为它负责序列化跨分片结果。若发现瓶颈，可把聚合逻辑前置到分片内，或增加协调器资源。下表列出两种架构特征：
| 维度 | 单一图数据库 | Neo4j Fabric 联邦 |
|---|---|---|
| 数据分布 | 集中存储 | 分片独立 |
| 跨域查询 | 原生支持但受单机限制 | 协调器路由下推 |
| 写入一致性 | 单库事务 | 仅分片本地事务 |
| 适用规模 | 中小数据量 | 超大规模多租户 |
综合来看，Node.js 通过 neo4j-driver 接入 Fabric 并不复杂，难点在分片设计与查询下推。理清逻辑库与物理分片边界，才能发挥联邦优势而不陷入分布式陷阱。
Neo4j_FabricNode.jsgraph_federation修改时间：2026-08-16 10:20:31