Goals This guide explains the example application we use to introduce the different Neo4j drivers in detail. Prerequisites You should be familiar with graph database concepts and the property graph model. You should have installed Neo4j and made yourself familiar… Read more →

This guide explains the example application we use to introduce the different Neo4j drivers in detail.
You should be familiar with graph database concepts and the property graph model. You should have installed Neo4j and made yourself familiar with our Cypher Query language.

Example Project Description

To demonstrate connection to and usage of Neo4j in different programming languages we’ve created an example application. It is a simple, one-page webapp, that uses Neo4j’s movie demo database (movie, actor, director) as dataset. The same front-end web page consumes 3 REST-endpoints provided by backend implemented in the different programming languages and drivers.

  • movie search
  • single movie listing
  • graph visualization of the domain

movie application

Domain Model

(:Movie {title,released,tagline})<-[:ACTED_IN {roles}]-(actor:Person)


The source code for the different examples is available on GitHub.


The webpage is a single Bootstrap page that uses jQuery AJAX calls to access the backend and adds the returned JSON result data to HTML elements in the page.

For the search, that is the /search?q=query endpoint whose results are added as table rows. If you click on any of the movie titles, the side-view is populated with the movie details.

For the movie details it uses the /movie/Movie%20Title endpoint and the results are rendered as panel title, image source, and unordered list for crew.

Graph Visualization

For the Graph Visualization we use d3.js. Our /graph endpoint already returns the data in the format of “nodes” and “links”-list that d3 can use directly. We then apply the force-layout algorithm to render nodes as circles and relationships as lines, and add some minor styling to the visualization to provide the movie title/person name as an HTML title attribute to the node circles.

Data Setup

  • Start your local Neo4j Server (Download & Install)
  • Open the Neo4j Browser.
  • Install the Movies dataset with :play movies
  • Click the CREATE statement and hit the triangular “Run” button to insert the data.

You can also choose to use a cloud-hosted Neo4j database. If you go this route, then you have to provide the URL to your Neo4j server in an environment variable NEO4J_URL.

Alternatively you can run this Cypher LOAD CSV statement:


Get Movie

// JSON object for single movie with cast
curl http://localhost:8080/movie/The%20Matrix

{"title": "The Matrix",
 "cast": [{"job": "acted", "role": ["Emil"], "name": "Emil Eifrem"}, {"job": "acted", "role": ["Agent Smith"], "name": "Hugo Weaving"}, ...
          {"job": "directed", "role": null, "name": "Andy Wachowski"}, {"job": "produced", "role": null, "name": "Joel Silver"}]}

The Cypher query is used, with the parameters {title:"The Matrix"}

It matches the movie by title, then optionally finds all people working on that movie and returns the movie title and a crew-list consisting of a map with person-name, job identifier derived from the relationship-type and optionally a role for actors.

MATCH (movie:Movie {title:{title}})
 OPTIONAL MATCH (movie)<-[r]-(person:Person)
 RETURN movie.title as title,
                role:r.roles}) as cast LIMIT 1

Search Movies

// list of JSON objects for movie search results
curl http://localhost:8080/search?q=matrix

[{"movie": {"released": 1999, "tagline": "Welcome to the Real World", "title": "The Matrix"}},
 {"movie": {"released": 2003, "tagline": "Free your mind", "title": "The Matrix Reloaded"}},
 {"movie": {"released": 2003, "tagline": "Everything that has a beginning has an end", "title": "The Matrix Revolutions"}}]

The Cypher query used, with the parameters {query:"(?i).*matrix.*"}, a case-insensitive regular expression partial match.

The Search Movies query matches the movies by title with a regular expression and then returns the movie nodes as a list of maps with the title, released and tagline entries.

MATCH (movie:Movie)
 WHERE movie.title =~ {query}
 RETURN movie

Graph Visualization

// JSON object for whole graph viz (nodes, links - arrays)
curl http://localhost:8080/graph[?limit=50]

  [{"title":"Apollo 13","label":"movie"},{"title":"Kevin Bacon","label":"actor"},
   {"title":"Tom Hanks","label":"actor"},{"title":"Gary Sinise","label":"actor"},
   {"title":"Ed Harris","label":"actor"},{"title":"Bill Paxton","label":"actor"}],

The Cypher query used finds all pairs of movies and actors and returns the movie title and a collection of all actor names as cast. A separate function then takes this result and converts it into the node- and link-list that d3 expects.

The parameter {limit:50} is used to prevent the visualization from becoming a hairball.

MATCH (m:Movie)<-[:ACTED_IN]-(a:Person)
 RETURN m.title as movie, collect(a.name) as cast
 LIMIT {limit}

Run Locally

Then setup and start the language/stack specific implementation of the backend and open the web-application on http://localhost:8080.

You can search for movies by title or click on any result entry to see the details.

Deploy to Heroku

Many of the mentioned GitHub example repositories feature a “Deploy to Heroku” button. You can either use that or follow the manual process outlined below.

We want to install our application to the cloud, for instance the Heroku PaaS. We will also use either the GrapheneDB or GraphStory Neo4j Database Hosting Add-On.

Install the Heroku Toolbelt and git.

Then run these commands:

# initialize git repository and add files
git init
git add .
git commit -m"my neo4j movies app"

# create heroku application, please change the app-name
export app=my-neo4j-movies-app
heroku apps:create $app

# add free hosting database
heroku addons:add graphenedb:chalk --app $app
# or
heroku addons:add graphstory --app $app

# configure your app to use the add-on
heroku config:set NEO4J_REST_URL=GRAPHENEDB_URL --app $app
# or
heroku config:set NEO4J_REST_URL=GRAPHSTORY_URL --app $app

# deploy to heroku
git push heroku master

# open application
heroku open --app $app

# open addon admin page
heroku addons:open graphenedb
# or
heroku addons:open graphstory

In the Graphenedb-UI use “Launch Neo4j Admin UI”. In the Neo4j-Browser import the :play movies dataset as of the install instructions above.

Then your app is ready to roll.

Existing Language / Driver Examples

For our example application we’ve provided a implementation for the languages and drivers listed below. You can find them in the Neo4j Examples GitHub repository. Most of them have thankfully been made available by the driver authors.