Good Relationships: The Spring Data Neo4j Guide Book

In order to configure Spring Data Neo4j with Java-based bean config, your Spring context must extend the core Neo4jConfiguration class that comes with Spring Data Neo4j. The example below shows how this can be done.

The Neo4jServer interface simply provides a URL with which to access the database. The default implementations are RemoteServer and InProcessServer (for testing).

As the name implies, RemoteServer is used to provide the URL of a remote Neo4j server. This will be the most typical use case for deployed applications. As the above example shows, you simply construct a new instance with the URL of the server that you want to use.

InProcessServer is useful for test and development environments, but is not recommended for production use. This implementation will start a new instance of CommunityNeoServer running on an available local port and return the URL needed to connect to it. It also registers a shutdown hook so that the underlying Neo4j server exits cleanly when the JVM shuts down, via Control+C, for example. To use the InProcessServer in your tests, you will need to add a dependency to the spring-data-neo4j-tests.jar`:

The SessionFactory is needed by SDN to create instances of org.neo4j.ogm.session.Session as required. This also sets up the object-graph mapping metadata when constructed, which is then used across all Session objects that it creates. As seen in the above example, the packages to scan for domain object metadata should be provided to the SessionFactory constructor.

Note that the session factory should typically be application-scoped. While you can use a narrower scope for this if you like, there is typically no advantage in doing so.

A Session is used to drive the object-graph mapping framework on which Spring Data Neo4j is based. All repository implementations and Neo4jTemplate are driven by the Session, and you can also auto-wire it into your Spring beans and code against it directly if you wish.

The life cycle of a Session is important to consider because it keeps track of the changes that have been made to entities and their relationships. The reason it does this is so that only entities and relationships that have changed get persisted on save, which is particularly efficient when working with large graphs. Note, however, that the Session doesn’t ever return cached objects so there’s no risk of getting stale data on load; it always hits the database.

If your application relies on long-running sessions and doesn’t reload entities then you may not see changes made from other users and find yourself working with outdated objects. On the other hand, if your sessions have too narrow a scope then your save operations can be unnecessarily expensive, as updates will be made to all objects if the session isn’t aware of the those that were originally loaded.

There’s therefore a trade off between the two approaches. In general, the scope of a Session should correspond to a "unit of work" in your application. What this means depends on the usage scenario, but in a typical web-based Spring application we recommend using a request-scoped or HTTP-session-scoped Session. Either way, if you make sure you load fresh data at the beginning of each unit of work then data integrity shouldn’t be a problem.

Additional beans can be configured to be included in the Neo4j-Configuration just by defining them in the Spring context in the normal way.

Reflection and annotation-based metadata is collected about persistent entities in org.neo4j.ogm.metadata.Metadata which provides it to any part of the library. This information is gathered by reading the class files directly rather than loading via reflection, resulting in much faster startup times.

The metadata holds all the required object-graph mapping information for each type. This metadata is discovered at start-up by specifying a list of packages in which all classes are scanned, including those in sub-packages. In order to omit a class from being metadata-mapped you should annotate it with @org.neo4j.ogm.annotation.Transient.

The Spring repositories and Neo4jTemplate are both backed by org.neo4j.ogm.session.Session, which is a key component of the framework. The Session provides methods to load, save or delete object graphs from the database and also provides transaction support. The new Neo4jTemplate is essentially a wrapper around this Session, which exposes all of its useful methods but handles transactions and provides the traditional Spring Data operations and exception translation.

Unlike the previous AspectJ-driven mapping, Spring Data Neo4j 4 doesn’t automatically commit when a transaction closes, so an explicit call to save(…​) is required in order to persist changes to the database.

Spring Data Neo4j introduces the concept of persistence horizon (depth). On any individual request, the persistence horizon indicates how many relationships should be traversed in the graph when loading or saving data. A horizon of zero means that only the root object’s properties will be loaded or saved, a horizon of 1 will include the root object and all its immediate neighbours, and so on. This attribute is enabled via a depth argument available on all repository and template methods, but SDN 4 chooses sensible defaults so that you don’t have to specify the depth attribute unless you want change the default values.

The @NodeEntity annotation is used to declare that a POJO class is an entity backed by a node in the graph database. Entities handled by Spring Data Neo4j must have one empty public constructor to allow the library to construct the objects.

Fields on the entity are by default mapped to properties of the node. Fields referencing other node entities (or collections thereof) are linked with relationships.

@NodeEntity annotations are inherited from super-types and interfaces. It is not necessary to annotate your domain objects at every inheritance level.

If the label attribute is set then this will replace the default label applied to the node in the database. This replaces the previous @TypeAlias annotation. The default label is just the simple class name of the annotated entity. All parent classes are also added as labels so that retrieving a collection of nodes via a parent type is supported.

Entity fields can be annotated with @Property, @GraphId, @Transient or @Relationship. All annotations live in the org.neo4j.ogm.annotation package. Marking a field with the transient modifier has the same effect as annotating it with @Transient; it won’t be persisted to the graph database.

Saving a simple object graph containing one actor and one film using the above annotated objects would result in the following being persisted in Neo4j.

When annotating your objects, you can apply the annotations to either the fields or their accessor methods, but bear in mind the aforementioned EntityAccessStrategy ordering when annotating your domain model.

In this case, a graph similar to the following would be persisted.

While this will map successfully to the database, it’s important to understand that the names of the properties and relationship types are tightly coupled to the class’s member names. Renaming any of these fields will cause parts of the graph to map incorrectly, hence the recommendation to use annotations.

This is a required field which must be of type Long. It is used by Spring Data Neo4j to store the node or relationship-id to re-connect the entity to the graph.

If the field is simply named 'id' then it is not necessary to annotate it with @GraphId as the OGM will use it automatically.

As we touched on earlier, it is not necessary to annotate property fields as they are persisted by default. Fields that are annotated as @Transient or with transient are exempted from persistence. All fields that contain primitive values are persisted directly to the graph. All fields convertible to a String using the Spring conversion services will be stored as a string. Spring Data Neo4j includes default type converters that deal with the following types:

Collections of primitive or convertible values are stored as well. They are converted to arrays of their type or strings respectively. Custom converters are also specified by using @Convert - this is discussed in detail later on.

Node property names can be explicitly assigned by setting the name attribute. For example @Property(name="last_name") String lastName. The node property name defaults to the field name when not specified.

Every field of a node entity that references one or more other node entities is backed by relationships in the graph. These relationships are managed by Spring Data Neo4j automatically.

The simplest kind of relationship is a single field pointing to another node entity (1:1). In this case, the field does not have to be annotated at all, although the annotation may be used to control the direction and type of the relationship. When setting the field, a relationship is created when the entity is persisted. If the field is set to null, the relationship is removed.

It is also possible to have fields that reference a set of node entities (1:N). These fields come in two forms, modifiable or read-only. Modifiable fields are of the type Collection<T>, and read-only fields are Iterable<T>, where T is a type annotated with @NodeEntity.

For graph to object mapping, the automatic transitive loading of related entities depends on the depth of the horizon specified on the call to Session.load(). By default, the related node or relationship entities will just be loaded to minimum depth 0, which means their properties will be set but no further related entities will be populated.

If this Set of related entities is modified, the changes are reflected in the graph once the root object (Actor, in this case) is saved. Relationships are added, removed or updated according to the differences between the root object that was loaded and the corresponding one that was saved..

Spring Data Neo4j ensures by default that there is only one relationship of a given type between any two given entities. If you don’t care about the direction then you can specify direction=Relationship.UNDIRECTED which will guarantee that the path between two node entities is navigable from either side.

To access the full data model of graph relationships, POJOs can also be annotated with @RelationshipEntity, making them relationship entities. Just as node entities represent nodes in the graph, relationship entities represent relationships. As described above, fields annotated with @Relationship provide a way to only link node entities via relationships, but it provides no way of accessing the relationships themselves.

Fields in relationship entities are similar to node entities, in that they’re persisted as properties on the relationship. For accessing the two endpoints of the relationship, two special annotations are available: @StartNode and @EndNode. A field annotated with one of these annotations will provide read-only access to the corresponding endpoint, depending on the chosen annotation.

For controlling the relationship-type a String attribute called type is available on the @RelationshipEntity annotation. Like the simple strategy for labelling node entities, if this is unset then the name of the class is used to derive the relationship type.

In previous versions of Spring Data Neo4j, a dynamic relationship type field was supported. However, this has been dropped completely for version 4, since it was not possible to manage it effectively for both reading from and writing to the graph.

In some cases, you want to model two different aspects of a conceptual relationship using the same relationship type. Here is a canonical example:

In previous versions of Spring Data Neo4j, you would have to add an enforceTargetType attribute into every clashing @Relationship annotation for this to map correctly. Thanks to changes in the underlying object-graph mapping mechanism, this is no longer necessary and the above will work just fine.

However, please be aware that this will only work because the end node types (Car and Pet) are different types. If you wanted a person to own two cars, for example, then you’d have to use a Collection of cars or use differently-named relationship types.

From Spring Data Neo4j 4, @Indexed is no longer available. The index management concern was separated from the mapping framework. Creating indexes should be done when seeding and migrating databases instead as part of data model design decisions.

Index creation and management is therefore now outside the scope of this document. Please see the Neo4j documention on indexes for for information: http://neo4j.com/docs/stable/query-schema-index.html

Schema indexes are automatically used by Neo4j’s Cypher engine, so using the annotated or derived repository finders or the query methods in Neo4jTemplate will use them out of the box.

Neo4j allows to configure (legacy) auto-indexing for certain properties on nodes and relationships. It is possible to use the specific index names node_auto_index and relationship_auto_index when querying indexes in Spring Data Neo4j either with the query methods in template and repositories or via Cypher.

Previous versions of Spring Data Neo4j offered support for full-text queries using the manual index facilities. However, as of SDN 4 milestone 1 at least, this is no longer supported. To create fulltext entries for an entity you can add the updated nodes within AfterSaveEvents to a remote fulltext-index via Neo4j’s REST API. Fulltext query support is still available via Cypher queries and will be fully addressed by a future Neo4j version.

Previous versions of Spring Data Neo4j offered support for spatial queries using the neo4j-spatial library. However, as of SDN 4 milestone 1 at least, this is no longer supported. To create spatial entries for an entity you can add the updated nodes within AfterSaveEvents to a remote fulltext-index via Neo4j’s REST API. Spatial query support is still available via Cypher queries and will be fully addressed by a future Neo4j version.

For Spring Data Neo4j 4, the changes to the underlying architecture have led to the pruning of the Neo4jTemplate feature set. Basic operations are now entirely limited to CRUD operations on entities and executing arbitrary Cypher queries; more low-level manipulation of the graph database is not possible.

Given that the latest version of the framework is driven by Cypher queries alone, there’s no way to work directly with Node and Relationship objects any more in remote server mode. Similarly, the traverse() method has disappeared, again because the underlying query-driven model doesn’t handle it in an efficient way.

If you find yourself in trouble because of the omission of these features, then your best options are:

Of course, there are pros and cons to both of these approaches, but these are largely outside the scope of this document. In general, for low-level, very high-performance operations like complex graph traversals you’ll get the best performance by writing a server-side extension. For most purposes, though, Cypher will be performant and expressive enough to perform the operations that you need.

Neo4jTemplate allows to save, load, loadAll and delete entities. However, as of SDN 4, it no longer provides the stored type information via getStoredJavaType. The eagerness with which objects are retrieved is controlled by specifying the 'depth' argument to any of the load methods.

All of these basic CRUD methods just call onto the underlying methods of Session, albeit with transaction handling and exception translation managed for you.

The Neo4jTemplate also allows execution of arbitrary Cypher queries via its query, queryForObject and queryForObjects methods. Cypher queries that return tabular results should be passed into the query method. An Iterable<Map<String,Object>> containing the raw data is returned, which can be either used as-is or converted into a richer type if needed. The keys in each Map correspond to the names listed in the return clause of the executed Cypher query.

For the query methods that retrieve mapped objects, the recommended query format is to return a path, which should ensure that known types get mapped correctly and joined together with relationships as appropriate.

For Cypher update operations, Neo4jTemplate provides an execute method, to which an arbitrary Cypher update statement (such as CREATE, MERGE or DELETE) can be passed.

The Neo4jTemplate provides implicit transactions for some of its methods. For instance save uses them. For other modifying operations please provide Spring Transaction management using @Transactional or the TransactionTemplate.

Neo4j Template utilises Spring’s event mechanism through ApplicationListener and ApplicationEvent to notify interested parties about certain data manipulations performed through it. The following hooks are available in the form of types of application event:

The point at which these events get fired by the Neo4jTemplate should be pretty obvious from the names. The following example demonstrates how to hook into the Spring application events API and register listeners that perform behaviour across types of entities as actions are performed using the template.

Note that changes made to entities in the before-save event application listener are reflected in the stored entity - after-save ones are not.

As of SDN 4, this GraphRepository<T> should be the interface from which your entity repository interfaces inherit, with T being specified as the domain entity type to persist.

There is also no TypeRepresentationStrategy in the latest framework version. Instead, the type representation strategy has been greatly simplified to use a single label-based mechanism as described in more detail here: Entity Type Representation

Examples of methods you get for free out of GraphRepository are as follows. For all of these examples the ID parameter is a Long that matches the graph ID:

The Repository instances are only created through Spring and can be auto-wired into your Spring beans as required.

The recommended way of providing repositories is to define a repository interface per domain class. The underlying Spring repository infrastructure will automatically detect these repositories, along with additional implementation classes, and create an injectable repository implementation to be used in services or other spring beans.

By default, Spring Data Neo4j will automatically perform the following type conversions:

Two Date converters are provided "out of the box"

By default, SDN will use the @DateString converter as described above. However if you want to use a different date format, you can annotate your entity attribute accordingly:

Alternatively, if you want to store Dates as long values, use the @DateLong annotation:

Collections of primitive or convertible values are also automatically mapped by converting them to arrays of their type or strings respectively.

In order to define bespoke type conversions for particular members, you can annotate a field or method with @Convert to specify an implementation of org.neo4j.ogm.typeconversion.AttributeConverter to use.

You could then apply this to your class as follows:

From version 4 onwards, the entity persistence is all performed through the save() method on the underlying Session object. This method is normally invoked indirectly via a Spring repository or Neo4jTemplate.

Under the bonnet, the implementation of Session has access to the MappingContext that keeps track of the data that has been loaded from Neo4j during the lifetime of the session. Upon invocation of save() with an entity, it checks the given object graph for changes compared with the data that was loaded from the database. The differences are used to construct a Cypher query that persists the deltas to Neo4j before repopulating it’s state based on the response from the database server.

As mentioned previously, save(entity) is overloaded as save(entity, depth), where depth dictates the number of related entities to save starting from the given entity. A depth of 0 will persist only the properties of the specified entity to the database, and a depth of -1 will persist everything in the object graph rooted at the given entity.

Specifying the save depth is handy when it comes to dealing with complex collections, that could potentially be very expensive to load.

Neither the actor nor the movie has been assigned a node in the graph. If we were to call repository.save(movie), then Spring Data Neo4j would first create a node for the movie. It would then note that there is a relationship to an actor, so it would save the actor in a cascading fashion. Once the actor has been persisted, it will create the relationship from the movie to the actor. All of this will be done atomically in one transaction.

The important thing to note here is that if repository.save(actor) is called instead, then only the actor will be persisted. The reason for this is that the actor entity knows nothing about the movie entity - it is the movie entity that has the reference to the actor. Also note that this behaviour is not dependent on any configured relationship direction on the annotations. It is a matter of Java references and is not related to the data model in the database.

If the relationships form a cycle, then the entities will first of all be assigned a node in the database, and then the relationships will be created. The cascading is however only propagated to related entity fields that have been modified.

In the following example, the actor and the movie are both attached entites, having both been previously persisted to the graph:

You can now tailor your persistence requests according to the characteristics of the portions of your graph you want to work with. This means you can choose to make deeper or shallower fetches based on fine tuning the types and amounts of data you want to transfer based on your individual constraints.

If you know that you aren’t going to need an object’s related objects, you can choose not to fetch them by specifying the fetch-depth as 0. Alternatively if you know that you will always want to a person’s complete set of friends-of-friends, you can set the depth to 2.

SDN 4 introduces smart object-mapping. This means that all other things being equal, it is possible to reliably detect which nodes and relationships needs to be changed in the database, and which don’t.

Knowing what needs to be changed means we don’t need to flood Neo4j with requests to update objects that don’t require changing, or create relationships that already exist. We can minimise the amount of data we send across the wire as a result, which results in a faster network interaction, and fewer CPU cycles consumed on the server.

Supporting the smart object-mapping capability is the Neo4jSession. This object can be declared with different lifetimes, depending on the requirements of your application. For web-based applications, you might choose between HTTP Request-scoped lifetime or HTTP Session-scoped lifetimes. For a standalone application, you may choose to maintain a single session for the entire lifetime of the application.

The advantage of longer-running sessions is that you will be able to make more efficient requests to the database at the expense of the additional memory associated with the session. The advantage of shorter sessions is they impose almost no overhead on memory, but will result in less efficient requests to Neo4j when storing and retrieving data.

It is also possible to manage your session lifetimes in code. For example, associated with single fetch-update-save cycle or unit of work.

Support for overriding property types via arguments to @Property has been dropped. If your attribute requires a non-default conversion to and from a database property, you can use a Custom Converter instead.

In previous versions of Spring Data Neo4j, you would have to add an enforceTargetType attribute into every clashing @Relationship annotation. Thanks to changes in the underlying object-graph mapping mechanism, this is no longer necessary.

Neo4j is dropping XA support and therefore SDN 4 does not provide any capability for cross-store persistence

SDN 4 replaces the existing TypeRepresentionStrategy configuration with a straightforwad convention based on simple class-names or entities using @NodeEntity(label=…​)

Please refer to Entity Type Representation for more details.

Support for Aspect J based persistence has been removed from SDN 4 as the write- and read-through approach only works with an integrated, embedded database, not Neo4j server. The performance improvements in SDN 4 should make the use as a performance optimization unnecessary.

The following table shows the Neo4jTemplate functions that have been retained for version 4 of Spring Data Neo4j. In some cases the method names have changed but the same functionality is offered under the new version.

To achieve the old template.fetch(entity) equivalent behaviour, you should call one of the load methods specifying the fetch depth as a parameter.

It’s also worth noting that exec(GraphCallback) and the create…​() methods have been made obsolete by Cypher. Instead, you should now issue a Cypher query to the new execute method to create the nodes or relationships that you need.

Previous versions of SDN allowed you to use a DSL to generate Cypher queries. There are many different DSL libraries available and you’re free to use which of these - or none - that you want. With Cypher changing on a regular basis, avoiding a DSL implementation in SDN means less ongoing maintenance and less likelihood of your code being incompatible with future versions of Neo4j.

These features cannot be supported by Cypher and have therefore been dropped from Neo4jTemplate.