本文详解如何在 java 应用中通过 neo4j 官方驱动（v5+）正确执行 fabric 跨图查询，重点解决 `use fabric` 语法不被支持、多图 `union` 报错及连接超时等典型问题，并提供可运行的配置示例与最佳实践。
Neo4j Fabric 是 Neo4j 5.x 引入的企业级多图联邦查询能力，允许将多个独立图数据库（如 fabric.graph1、fabric.graph2）逻辑聚合为统一查询入口。但需注意：Fabric 并非运行时指令，而是一种特殊的数据库模式（fabric database）——它必须作为连接的目标数据库显式指定，而非通过 Cypher 中的 USE 命令动态切换。
✅ 正确做法：连接时指定 fabric 为默认数据库
Java 驱动（neo4j-java-driver ≥ 5.0）不支持在 Cypher 查询中使用 USE fabric 或 :USE fabric（后者是浏览器专属命令，非标准 Cypher）。Fabric 查询的前提是：客户端必须直接连接到名为 fabric 的逻辑数据库。这需通过以下两种方式之一实现：
方式一：通过 DatabaseName 显式指定（推荐，代码级控制）
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.Session;
Driver driver = GraphDatabase.driver(
"bolt://localhost:7687",
AuthTokens.basic("neo4j", "password")
);
// 关键：Session 必须明确指定 database = "fabric"
try (Session session = driver.session(SessionConfig.forDatabase("fabric"))) {
String cypher = """
USE fabric.graph1 MATCH (n) RETURN n
UNION
USE fabric.graph2 MATCH (n) RETURN n
""";
session.run(cypher).forEach(record -> {
System.out.println(record.get(0));
});
}⚠️ 注意：USE fabric.graph1 等子句仅在 fabric 数据库上下文中才合法；若连接的是其他数据库（如 neo4j），会报错 Multiple graphs in the same query not allowed here。
方式二：通过环境变量全局设置（适用于 Spring Boot 等场景）
在启动应用前设置环境变量：
export NEO4J_DATABASE=fabric
或在 application.properties 中配置（Spring Boot + spring-boot-starter-data-neo4j）：
立即学习“Java免费学习笔记（深入）”；
spring.neo4j.database=fabric
此时所有 session.run() 默认作用于 fabric 数据库，无需每次传参。
? 补充关键配置项
- 协议必须使用 bolt://（非 http://）：Fabric 查询依赖 Bolt 协议的高级路由能力，浏览器中的 :use fabric 命令本质是前端模拟，而 Java 驱动必须走 Bolt。若误用 HTTP 连接（如 http://localhost:7474），将触发 WebSocket 连接失败（即你遇到的 readyState: 3 错误）。
-
确保 Neo4j Server 已启用 Fabric：在 neo4j.conf 中确认已启用：
dbms.fabric.enabled=true dbms.fabric.database=fabric
- Fabric 图必须已注册：通过 CALL fabric.registerGraph(...) 将 graph1、graph2 等物理图注册到 Fabric 元数据中，否则 USE fabric.graph1 会报图不存在。
? 总结与避坑指南
| 问题现象 | 根本原因 | 解决方案 |
|---|---|---|
| Query cannot conclude with USE GRAPH | Java 驱动禁止 USE 语句出现在查询末尾（且 Fabric 不支持该语法） | 改为连接时指定 database="fabric" |
| Multiple graphs in the same query not allowed | 当前 Session 连接的不是 fabric 数据库 | 检查 SessionConfig.forDatabase("fabric") 是否生效 |
| WebSocket readyState: 3 超时 | 使用了 HTTP 协议或错误端口（应为 Bolt 7687，非 HTTP 7474） | 改用 bolt://host:7687，禁用 http 相关配置 |
| fabric.graph1 not found | 物理图未在 Fabric 中注册 | 在 Neo4j Browser 执行 CALL fabric.registerGraph("graph1", "bolt://graph1:7687") |
只要确保：✅ Bolt 连接 + ✅ database="fabric" + ✅ Fabric 已启用并注册子图，即可在 Java 中无缝执行跨图 UNION、CALL 等联邦查询，真正发挥 Neo4j Fabric 的分布式图数据编排能力。
