如何将Spring Data Neo4j 5.0.3自定义Cypher查询标记为只读

我之前在对接Neo4j因果集群时也碰到过一模一样的问题，结合Spring Data Neo4j(SDN) 5.x的特性和Neo4j集群的路由逻辑，咱们一步步来解决它：

核心原因分析 #

SDN 5.0.3中，session.query()方法默认绑定到写会话，不管你的Cypher是不是只读查询：

• 底层Neo4j驱动的路由逻辑依赖于会话的「访问模式」（READ/WRITE），但SDN对自定义Cypher查询不会自动解析其读写属性，默认都会使用WRITE模式，强制路由到主节点。
• 只有SDN自动生成的查询（比如Repository的findByXXX方法）才会被自动标记为只读，进而路由到从节点。

具体解决办法 #

1. 显式创建只读会话执行查询 #

在获取Session时，直接指定访问模式为READ，这样所有通过该Session执行的查询都会被路由到只读从节点：

// 打开只读会话
Session session = sessionFactory.openSession(Session.ReadAccess.READ);
// 执行自定义只读Cypher
Result result = session.query("MATCH (u:User) WHERE u.age > $age RETURN u.name", 
                              Collections.singletonMap("age", 18));
// 处理查询结果...

2. 在Repository中用@Query注解标记只读查询 #

如果你的自定义查询是定义在Repository接口里的，可以通过@Query的readOnly=true属性显式标记为只读，SDN会自动为该查询分配只读会话：

@Repository
public interface UserRepository extends Neo4jRepository<User, Long> {
    // 标记为只读查询，路由到从节点
    @Query(value = "MATCH (u:User) WHERE u.city = $city RETURN u", readOnly = true)
    List<User> findUsersByCity(@Param("city") String city);
}

3. 确认Neo4j驱动配置正确 #

一定要使用bolt+routing协议连接集群，而不是普通的bolt协议，否则驱动无法识别集群结构进行路由：

# application.properties中的配置示例
spring.data.neo4j.uri=bolt+routing://master-node:7687,slave-node1:7687,slave-node2:7687
spring.data.neo4j.username=neo4j
spring.data.neo4j.password=your-cluster-password

4. 注意事务上下文的影响 #

如果你的查询是在一个写事务中执行的（比如被@Transactional注解且默认是写事务），即使你指定了只读会话，查询也会被强制路由到主节点。确保只读查询在独立的只读事务或无事务上下文中执行：

// 显式指定只读事务
@Transactional(readOnly = true)
public List<String> getAllUserNames() {
    Session session = sessionFactory.getCurrentSession();
    return session.query("MATCH (u:User) RETURN u.name", Collections.emptyMap())
                  .stream()
                  .map(record -> record.get("u.name").asString())
                  .collect(Collectors.toList());
}

额外注意事项 #

• Neo4j 3.3.1的因果集群会确保从节点的数据一致性，如果从节点未同步完主节点的最新事务，驱动会自动将查询路由到主节点，这是正常的一致性保障机制。
• SDN 5.0.3是比较旧的版本，若条件允许，升级到SDN 5.3+会获得更智能的查询读写判断逻辑，减少手动配置的麻烦。

内容的提问来源于stack exchange，提问作者simonl