Neo4j.rb 3.0.rc

Neo4j.rb is a Ruby driver for the Neo4j graph database which I together with many contributors have been developing since 2008. It now consists of two Ruby gems, neo4j-core and neo4j. The neo4j-core gem is a simple Ruby wrapper around the Neo4j primitives: nodes, relationships, labels and properties. The neo4j.rb gem is a drop in replacement for active record in Ruby on Rails.

Last week Neo4j Technology and Jayway sponsored Brian Underwood and Chris Grigg to come to Malmö and work together with me. We made great progress and created a 3.0 release candidate. We also discussed features in future releases, for example exciting things like eager loading, linked lists and cascade delete.

The 3.0 release is a complete rewrite of the driver. This was required since neo4j.rb 3.0 now supports the Neo4j Server as well as the embedded Neo4j. That means that you can run your Neo4j Ruby on Rails application on Heroku. If you later decide to use the Neo4j embedded database (for example to access the Java API directly without any HTTP requests) you only have to change one line of configuration.

Another reason for the rewrite was to take advantage of new features in Neo4j such as labels and the cypher query language. Labels are now mapped to Ruby modules or classes. When neo4j.rb loads a Neo4j node it checks which labels it has in order to decide which Ruby class should wrap the node.

Chris Grigg, me and Brian Underwood
Chris Grigg, me and Brian Underwood


Neo4j.rb 3.0 works on both MRI Ruby and JRuby. To install the neo4j.rb release candidate open a terminal and type:

gem install neo4j -v 3.0.0.rc.3

One way to install the database is by using Rake. Create a Rakefile with the following content

Then type: rake neo4j:install[community-2.1.3]
To start it, type: rake neo4j:start

The Neo4j Browser

We are now going to play around with the basic primitives of Neo4j by just using the neo4j-core API. Let’s open an IRB console and type:

There are two different session types, server_db (default) or embedded_db. We have above created a session to the Neo4j server at port 7474. Now, let’s create some nodes representing me and my two cats and the relationships between us.

We can now visualize nodes and relationships we just created in the Neo4j browser. Open a browser on http://localhost:7474 and enter the following cypher query: MATCH (h:Human)-[:pets]-(a) WHERE = 'andreas' RETURN h,a

Neo4j Editor
The Neo4j Browser

Let’s get back to the Ruby IRB console and ask for the names of all pets for owner Andreas:

Mapping nodes to Ruby classes

So far we have only used the neo4j-core API. Now let’s use the neo4j.rb gem to map those nodes to Ruby classes. This also gives you an idea how to use an already existing Neo4j database (for example, created by the Neo4j Browser) together with neo4j.rb.
Enter in the IRB console:

We have now created a Human model with one declared outgoing relationship of type pets. Relationships have here been restricted to always start on Human nodes and end at Animal nodes.

Notice how we have mapped the same relationship kittens to two different Ruby methods: kittens and mother. The mother relationship accessor method will navigate incoming relationships of type kittens. It’s now easy to write queries by using the declared relationships above. For example:

More info

The upcoming 3.0 release is an important release since it supports the Neo4j Server. The embedded database is still supported which you can use from JRuby instead of writing server-side scripts (Neo4j Server Plugin). This can sometimes give you much better performance.

For more information check the neo4j.rb wiki, the neo4j.rb github repository, neo4j-core wiki and the neo4j-core github repository.

This Post Has One Comment

Leave a Reply