What is a Graph Database?

A graph database stores data in a graph, the most generic of data structures, capable of elegantly representing any kind of data in a highly accessible way. Let’s follow along some graphs, using them to express themselves. We’ll “read” a graph by following arrows arond the diagram to form sentences.

A Graph contains Nodes and Relationships

The simplest possible graph is a single Node, a record that has named values referred to as Properties. A Node could start with a single Property and grow to a few million, though that can get a little awkward. At some point it makes sense to distribute the data into multiple nodes, organized with explicit Relationships.

Relationships organize Nodes into arbitrary structures, allowing a Graph to resemble a List, a Tree, a Map, or a compound Entity – any of which can be combined into yet more complex, richly inter-connected structures.

Traverse a Graph with a Traversal

A Traversal is how you query a Graph, navigating from starting Nodes to related Nodes according to an algorithm, finding answers to questions like “what music do my friends like that I don’t yet own,” or “if this power supply goes down, what web services are affected?”

Query a Graph with Cypher

Cypher is a declarative query language (much like SQL) used to explore graphs; it uses ASCII-notation to express relationships between nodes. An example query showing my grown-up friends (if any).

start me=node:user(name=”my name”)
match me-[:FRIEND]->friend
where friend.age > 18
return friend.name

Cypher uses a technique called graph matching to find suitable sub-graphs to work with.

Indexes look-up Nodes or Relationships

Often, you want to find a specific Node or Relationship according to a Property it has. This special case of Traversal is so common that it is optimized into an Index look-up, for questions like “find the Account for username master-of-graphs.”

Neo4j is a Graph Database

Neo4j is a commercially supported open-source graph database, that is:

• intuitive, using a graph model for data representation
• reliable, with fully ACID transactions
• durable, using disk-based, native storage
• massively scalable, up to several billion nodes/relationships/properties
• highly-available, when replicated out across multiple machines
• expressive, querying with the Cypher Graph Query Language
• high-speed, using a powerful graph traversal engine
• embeddable, with a few small jars
• simple, accessible by a convenient REST interface or object-oriented API

Heroku Neo4j Add-On

The add-on provides access to hosted Neo4j servers via the REST interface.

You can access the Web-Admin UI via a link from the Add-On page. It allows you to monitor, visualize and query your Neo4j-Instance.

Neo4j REST clients contributed by the community.

Local test setup on your machine

This small sample app shows how to get up and running with the Ruby REST bindings (neography).

Getting started with Neo4j Server

• download & extract the latest version of Neo4j Server
• or brew install neo4j
• start with ./bin/neo4j start
• Neo4j server is now available at http://localhost:7474
• test the database using the webadmin interface.
• use curl to explore the REST API

For example:

$ curl -H Accept:application/json http://localhost:7474/db/data/

Create simple, local Sinatra app

• create a simple application using http-rest-server
• see getting started for sinatra on heroku
• use ruby-neo4j-rest binding: neography

Install rubygems

$ gem install sinatra neography

Create Gemfile

source :rubygems
gem 'sinatra'
gem 'neography'

Create config.ru

require './myapp'
run Sinatra::Application

Create myapp.rb

require 'sinatra'
require 'neography'

neo = Neography::Rest.new("http://localhost:7474")

def create_graph(neo)
   # procedural API
  me = neo.get_root
  pr = neo.get_node_properties(me)
  return if pr && pr['name']
  neo.set_node_properties(me,{"name" => "I"})
  you = neo.create_node("name" => "you")
  neo.create_relationship("love", me, you)
end

create_graph(neo)

get '/' do
  ## object-oriented-API
  me = Neography::Node.load(neo, 0)       
  rel = me.rels(:love).first
  you = rel.end_node
  "#{me.name} #{rel.rel_type} #{you.name}"
end

Add to git-repository

$ git init
$ git add Gemfile config.ru myapp.rb
$ git commit -m "initial version"

Start app

$ rackup -p 8000

• open browser at http://localhost:8000/ you should see I love you

Deploy to Heroku

Prepare app for heroku environment, modify myapp.rb

neo = Neography::Rest.new(ENV['NEO4J_URL'] || "http://localhost:7474")

Create a Heroku app using the CLI:

$ heroku apps:create
Creating furious-fog-653... done, stack is bamboo-mri-1.9.2
http://furious-fog-653.heroku.com/ | git@heroku.com:furious-fog-653.git
Git remote heroku added

Add Neo4j Add-On

$ heroku addons:add neo4j
-----> Adding neo4j to furious-fog-653... done, (free)

View the addon-settings for your app on heroku

$ heroku addons:open neo4j

Deploy by pushing to heroku

$ git push heroku master

Open the application in the browser

$ heroku open

You can access information about your application

$ heroku logs
$ heroku info
$ heroku config
$ heroku ps
$ heroku addons:open neo4j

Use curl to explore the REST API

$ curl -H Accept:application/json $NEO4J_REST_URL

Add-On Settings

• Plan: your chosen plan (currently there is only the free test plan)

• Web-Admin: Neo4j Administration UI, requires authentication with login and password (those are also encoded in the link URL, your browser might give a phishing warning for that)

• REST-URL: base URL for the discoverable REST-API (login, password again encoded in link)

• Login

• Password

• Backup: will stop your Neo4j Server, backup the database and provide it as a Zip-Archive * you can use the backup for local usage too, just extract it in the data/graph.db directory

• Restore: will stop your Neo4j Server and replace it’s database with the one provided

  • via an URL to a Zip-file
  • via an uploaded local Zip-file

• we also host some sample data files

  Summary

This approach uses the plain REST-API. This implies that each graph-operation is backed by a http-call and transmits nodes, relationships and properties individually over the wire. The application-performance is influenced by network latency and bandwidth.

To speed things up you should use Cypher queries, traversals, the Batch-REST-API or (paged) index operations.

Java Applications

Java developers can just as easily deploy their Neo4j applications to Heroku. The trick is to use the correct Heroku stack, and package your application as a runnable jar with a bash script.

See the Heroku Java Workbook to get started with Java applications and use the java-rest-bindings driver or any other suitable REST-library.

Troubleshooting

Please don’t hesitate to contact us with any feedback or questions, at heroku at neo4j dot org. Feel free to join the neo4j google group.

If you have an interesting application or approach to show, ping us as well. Both Heroku and Neo4j are keen to support developers creating cool stuff. We are also interested if you organize events around Neo4j (and Heroku).