Introducing Spring Data Neo4j

Spring Data Neo4j or in short SDN is the next-generation Spring Data module, created and maintained by Neo4j, Inc. in close collaboration with VMware’s Spring Data Team. It supports all officially supported releases of Neo4j, including Neo4j AuraDB. The Spring Data Neo4j project applies aforementioned Spring Data concepts to the development of solutions using the Neo4j graph data store.

SDN relies completely on the Neo4j Java Driver, without introducing another "driver" or "transport" layer between the mapping framework and the driver. The Neo4j Java Driver - sometimes dubbed Bolt or the Bolt driver - is used as a protocol much like JDBC is with relational databases.

SDN is an Object-Graph-Mapping (OGM) library. An OGM maps nodes and relationships in the graph to objects and references in a domain model. Object instances are mapped to nodes while object references are mapped using relationships, or serialized to properties (e.g. references to a Date). JVM primitives are mapped to node or relationship properties. An OGM abstracts the database and provides a convenient way to persist your domain model in the graph and query it without having to use low level drivers directly. It also provides the flexibility to the developer to supply custom queries where the queries generated by SDN are insufficient.

SDN is the official successor to prior SDN version 5, to which this documentation refers as SDN+OGM. SDN version 5 used a separate object mapping framework, much in the way Spring Data JPA relates to JPA. That separate layer aka Neo4j-OGM (Neo4j Object Graph Mapper) is now contained in this module itself. Spring Data Neo4j itself is an object mapper, dedicated to be used in Spring and Spring Boot applications and in some supported Jakarta EE environments. It does not require or support a separate implementation of an object mapper.

Noteworthy features that differentiate the current SDN version from prior SDN+OGM are

  • SDN is a complete OGM on its own

  • Full support for immutable entities and thus full support for Kotlin’s data classes

  • Full support for the reactive programming model in the Spring Framework itself and Spring Data

  • Neo4j client and reactive client feature, resurrecting the idea of a template over the plain driver, easing database access

We provide repositories as a high-level abstraction for storing and querying documents as well as templates and clients for generic domain access or generic query execution. All of them are integrated with Spring’s application transactions.

The core functionality of the Neo4j support can be used directly, through either the Neo4jClient or the Neo4jTemplate or the reactive variants thereof. All of them provide integration with Spring’s application level transactions. On a lower level, you can grab the Bolt driver instance, but than you have to manage your own transactions in these cases.

You still can use Neo4j-OGM, even in modern Spring Boot applications. But you cannot use it with SDN 6+. If you tried you would have two different sets of entities in two different - and unrelated - persistence context. Hence, if you want to stick to Neo4j-OGM 3.2.x, you would use the Java driver instantiated by Spring Boot and pass it onto a Neo4j-OGM session. Neo4j-OGM 3.2.x is still supported, and we recommend its use in frameworks such as Quarkus. In a Spring Boot application however your primary choice should be SDN.

Please make sure you read the Frequently Asked Questions where we address many reoccurring questions about our mapping decisions but also how interaction with Neo4j cluster instances such as Neo4j AuraDB and on-premise cluster deployments can be significantly improved.

Concepts that are important to understand are Neo4j Bookmarks, the potential need for incorporating a proper retry mechanism such as Spring Retry or Resilience4j (we recommend the latter, as this knowledge is applicable outside Spring, too) and the importance of read-only vs write queries in the context of Neo4j cluster.