Spring Boot Neo4j JDBC - Movies Example Application

Even if Neo4j is all about graphs, its graph query language Cypher is well suited to be used with JDBC (Java Database Connectivity). As you probably know, JDBC is a common way to connect to a datastore, especially since there are a lot of tooling and connectors written around it in the Business Intelligence, Data Migration, and ETL world.

The Neo4j JDBC driver works with Neo4j Server in version 2.x and with embedded and in-memory databases. It allows you to (transactionally) execute parametrized Cypher statements against your Neo4j database to either create, query or update data.

Here we integrate Neo4j-JDBC with Spring-Boot and the traditional Spring-JDBC (JDBCTemplate) and Spring Web-MVC to create the backend.

The Stack

These are the components of our mini Web Application:

• Application Type: Java-Web Application

• Web framework: Spring-Boot with Spring-WebMVC

• Persistence Access: Spring-JDBC

• Neo4j Database Connector: Neo4j-JDBC with Cypher

• Database: Neo4j-Server

• Frontend: jquery, bootstrap, d3.js

Endpoints:

Get Movie

// JSON object for single movie with cast
curl http://neo4j-movies.herokuapp.com/movie/The%20Matrix

// list of JSON objects for movie search results
curl http://neo4j-movies.herokuapp.com/search?q=matrix

// JSON object for whole graph viz (nodes, links - arrays)
curl http://neo4j-movies.herokuapp.com/graph

Setup

Spring Boot is a rapid application development environment, bundling necessary Spring modules into easy-to-use starter packages.

It is based on annotation-based Java config and pre-configuring the packages with sensible defaults.

You add the dependency to the JDBC driver and Spring-Boot-Starters to your pom.xml:

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-jdbc</artifactId>
	<version>${spring-boot.version}</version>
</dependency>
<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web</artifactId>
	<version>${spring-boot.version}</version>
</dependency>
<dependency>
	<groupId>org.neo4j</groupId>
	<artifactId>neo4j-jdbc</artifactId>
	<version>2.3.2</version>
</dependency>

For the backend we use a Spring-WebMVC @RestController whose service methods access an autowired JdbcTemplate.

Currently we get the NEO4J_URL from a system property, but it should be equally simple to get it from an entry in application.properties. If you configure a password with your Neo4j server please set the environment variable like this:

export NEO4J_URL=jdbc:neo4j:http://localhost:7474?user=neo4j,password=<password>

Using the JDBC-template with Cypher is easy. Here is an example from the /movie endpoint:

@Autowired
JdbcTemplate template;

String GET_MOVIE_QUERY =
  "MATCH (movie:Movie {title:{1}})" +
  " OPTIONAL MATCH (movie)<-[r]-(person:Person)\n" +
  " RETURN movie.title as title, collect({name: person.name, " +
  " job: head(split(lower(type(r)),'_')), role: r.roles}) as cast LIMIT 1";

@RequestMapping("/movie/{title}")
public Map<String,Object> movie(@PathVariable("title") String title) {
    return template.queryForMap(GET_MOVIE_QUERY, title);
}

You would then set parameters on your statement. Please note that only numeric parameter names are possible, starting from 1.

You can use all known JdbcTemplate methods, like queryForObjects, queryForMap and RowMapper or ResultSetCallBack as you’re used to.

Run locally:

Start your local Neo4j Server (Download & Install), open the Neo4j Browser. Set the initial password to log-in, please use the same password in the NEO4J_URL environment variable. Then install the Movies data-set with :play movies, click the statement, and hit the triangular "Run" button.

Start this application with:

mvn spring-boot:run

Go to http://localhost:8080

You can search for movies by title and/or click on any entry.