Goals For Java developers that require a simple mechanism to manage their domain objects with Neo4j, this guide introduces the Neo4j Object Graph Mapping (OGM) library. This is the same library that powers Spring Data Neo4j but can also be… Learn More →

Goals
For Java developers that require a simple mechanism to manage their domain objects with Neo4j, this guide introduces the Neo4j Object Graph Mapping (OGM) library. This is the same library that powers Spring Data Neo4j but can also be used independently of Spring as well.
Prerequisites
You should be familiar with the graph database concepts and the property graph model. Having installed Neo4j and tried out our Cypher Query language helps too. When developing with Neo4j, please use JDK 8 and your favorite IDE.
Intermediate


Neo4j-OGM

While using the Cypher query language alongside the Java driver works well for small projects and more advanced queries, the boilerplate of CRUD operations often gets tedious.

That’s where object graph mappers come in; they take your existing domain objects (POJOs) and map them to Neo4j. The great benefit with this approach is that with graph databases, there is no data-model impedence mismatch like there is with relational databases.

Besides the Neo4j-OGM, there are also Spring Data Neo4j, Hibernate-OGM and others.

We created the Neo4j-OGM as a standalone, simple object graph mapper for Java which also acts as the base for Spring Data Neo4j.

The Neo4j-OGM uses Cypher in a consistent manner under the hood and can communicate via several transport protocols – bolt, http and embedded.

Features

The Neo4j-OGM supports the features you would expect:

  • Object graph mapping of annotated node- and relationship-entities
  • Neo4jSession for direct interaction with Neo4j
  • Fast class metadata scanning
  • Optimized management of data loading and change tracking for minimal data transfers
  • Multiple transports: binary (bolt), HTTP and embedded
  • Persistence lifecycle events
  • Query result projection to DTOs

Versions

Consult the version table to determine which version of the OGM to use with a particular version of Neo4j and related technologies.

Neo4j-OGM Version Neo4j Version Bolt Version# Spring Data Neo4j Version Spring Boot Version

3.0.0+

3.0.x, 3.1.x

1.1.0+

5.0.0+

2.0.0+

2.1.0+

2.3.x, 3.0.x, 3.1.x

1.1.0+

4.2.0+

1.5.0+

2.0.2+

2.3.x, 3.0.x

1.0.0+

4.1.2 – 4.1.6+

1.4.x

2.0.1*

2.2.x, 2.3.x

1.0.0-RC1

4.1.0 – 4.1.1

1.4.x

1.1.5*

2.1.x, 2.2.x, 2.3.x

N/A

4.0.0+

1.4.x

* These versions are no longer actively developed or supported.

# Not applicable to Embedded and HTTP drivers

Dependency Management

For building an application, your build automation tool needs to be configured to include the Neo4j OGM dependencies.

The OGM dependencies consist of neo4j-ogm-core, together with the relevant dependency declarations on the driver you want to use. OGM 2.1 provides support for connecting to Neo4j by configuring one of the following Drivers:

  • neo4j-ogm-http-driver – Uses HTTP to communicate between the OGM and a remote Neo4j instance.
  • neo4j-ogm-embedded-driver – Connects directly to the Neo4j database engine.
  • neo4j-ogm-bolt-driver – Uses native Bolt protocol to communicate between the OGM and a remote Neo4j instance.

If you’re not using a particular driver, you don’t need to declare it.

Neo4j OGM projects can be built using Maven, Gradle or any other build system that utilises Maven’s artifact repository structure.

Maven

In the <dependencies> section of your pom.xml add the following:

Maven dependencies
<dependency>
    <groupId>org.neo4j</groupId>
    <artifactId>neo4j-ogm-core</artifactId>
    <version>2.1.1</version>
    <scope>compile</scope>
</dependency>

<!-- Only add if you're using the HTTP driver -->
<dependency>
    <groupId>org.neo4j</groupId>
    <artifactId>neo4j-ogm-http-driver</artifactId>
    <version>2.1.1</version>
    <scope>runtime</scope>
</dependency>

<!-- Only add if you're using the Embedded driver -->
<dependency>
    <groupId>org.neo4j</groupId>
    <artifactId>neo4j-ogm-embedded-driver</artifactId>
    <version>2.1.1</version>
    <scope>runtime</scope>
</dependency>

<!-- Only add if you're using the Bolt driver -->
<dependency>
    <groupId>org.neo4j</groupId>
    <artifactId>neo4j-ogm-bolt-driver</artifactId>
    <version>2.1.1</version>
    <scope>runtime</scope>
</dependency>

If you plan on using a development (i.e. SNAPSHOT) version of the OGM you will need to add the following to the <repositories> section of your pom.xml:

Neo4j Snapshot Repository
<repository>
    <id>neo4j-snapshot-repository</id>
    <name>Neo4j Maven 2 snapshot repository</name>
    <url>http://m2.neo4j.org/content/repositories/snapshots</url>
</repository>

Gradle

Ensure the following dependencies are added to you build.gradle:

Gradle dependencies
dependencies {
    compile 'org.neo4j:neo4j-ogm-core:2.1.1'
    runtime 'org.neo4j:neo4j-ogm-http-driver:2.1.1' // Only add if you're using the HTTP driver
    runtime 'org.neo4j:neo4j-ogm-embedded-driver:2.1.1' //  Only add if you're using the Embedded driver
    runtime 'org.neo4j:neo4j-ogm-bolt-driver:2.1.1' // Only add if you're using the Bolt driver
}

If you plan on using a development (i.e. SNAPSHOT) version of the OGM you will need to add the following section of your build.gradle:

Neo4j Snapshot Repository
repositories {
    maven { url "http://m2.neo4j.org/content/repositories/snapshots" }
}

Minimal Code Snippet

This code example is taken from the Example Project (see below).

@NodeEntity(label="Film")
public class Movie {

   @GraphId Long id;

   @Property(name="title")
   private String name;
}

@NodeEntity
public class Actor extends DomainObject {

   @GraphId
   private Long id;

   @Property(name="name")
   private String fullName;

   @Relationship(type="ACTED_IN", direction=Relationship.OUTGOING)
   private List<Role> filmography;

}

@RelationshipEntity(type="ACTED_IN")
public class Role {
    @GraphId   private Long relationshipId;
    @Property  private String title;
    @StartNode private Actor actor;
    @EndNode   private Movie movie;
}

The Example Project

The Neo4j example project is a small, one page webapp for the movies database built into the Neo4j tutorial. The front-end page is the same for all drivers: movie search, movie details, and a graph visualization of actors and movies. Each backend implementation shows you how to connect to Neo4j from each of the different languages and drivers.

You can learn more about our small, consistent example project across many different language drivers here. You will find the implementations for all drivers as individual GitHub repositories, which you can clone and deploy directly.

FAQ

  1. What is the difference between Neo4j OGM and Spring Data Neo4j (SDN)?

    Spring Data Neo4j (SDN) uses the OGM under the covers. It’s like Spring Data JPA, where JPA/Hibernate underly it. Most of the power of SDN actually comes from the OGM.