Appendix A. Migration from 2.1 to 3.0/3.1

This migration guide should help with migration from Neo4j-OGM 2.1.x version to 3.0.x or 3.1.x.

A.1. Field access only

Probably the most invasive change is how Neo4j-OGM accesses entity fields. Up to version 2.1.x any setters/getters took precedence before direct field access. This was also the reason why some annotations had to be on both setters and getters/fields and was a frequent source of confusion and many questions on Slack and StackOverflow.

Since version 3.0.0 all properties and relationships are accessed (read and write) by direct field access only. All annotations on getters or setters must be moved to field directly. If there is an annotation duplicated on both field and setter/getter, only the annotation on the field should stay.


The @Target type of the annotations (@Relationship, @Property, etc.) was changed to ElementType.FIELD, so you can easily identify places which needs updating by trying to compile your project.

It was possible to perform some initialisation, validation or logic in annotated setters. New annotation @PostLoad was introduced to allow for any such action after the entity is fully hydrated.

A.2. Configuration

New class Configuration.Builder was introduced for Java configuration using properties or property file. See configuration section and JavaDoc for details.

Components class was removed, if you need to provide custom driver instance use appropriate constructor of SessionFactory.

You no longer need to provide the driver class name as in previous versions. The driver is automatically inferred from given URI.

A.3. Performance and unlimited load depth

In order to improve loading performance, some optimizations are now used by Neo4j-OGM when querying. A new load policy based on list comprehensions generated from schema is now used.

It means that, instead of loading blindly object graphs up to a certain depth, Neo4j-OGM will now only query the nodes and relationships that are expressed in your domain model. For applications that do not require following all the relationships, this can be a huge performance improvement.

However, this new load strategy does not support unlimited depth (depth = -1). Either use specific depth or use PATH_BASED_LOAD_STRATEGY, to revert to the old strategy.


Default depth for Session.load* methods without depth parameter is 1, so there is no need to change anything. Only calls with explicit depth = -1 need to be changed.

A.4. Migration checklist

Here are the things you (may) have to adapt :

  • Id handling : Long native ids are not mandatory anymore. See GraphId field.
  • Primary indexes are now deprecated and replaced by @Id. See Entity identifier.
  • Annotations on accessors are no longer valid. See Annotating entities.
  • Loading with depth -1 calls have to be reviewed (see above).
  • The file and environment variable have been removed. You now have to provide explicitly the configuration file or configure programmatically. See the configuration section.
  • The driver class name in the configuration is now inferred from connection URL.
  • Java 8 is now mandatory. Neo4j-OGM won’t run on any previous Java version.
  • Neo4j 3.1 or higher is required, because of the new schema load strategy, which uses list comprehensions.
  • Java 8 dates are now better supported ; the use of java.util.Date or converters is not required anymore. You may want to switch to more fine grained date types like Instant. See conversions.
  • The query filters are now immutable. See Filters.