Goals This guide provides an overview of options for connecting to Neo4j using Ruby. It will introduce the different drivers and link to relevant resources. Prerequisites You should be familiar with graph database concepts and the property graph model. You… Learn More →

This guide provides an overview of options for connecting to Neo4j using Ruby. It will introduce the different drivers and link to relevant resources.
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.

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.

Neo4j for Rubyists

There are three popular gems for Neo4j:

neography (GitHub)

A thin wrapper for the REST API that also provides additional methods to simplify node and relationship CRUD. It is compatible with Neo4j Server 1.8 through 2.X.

neo4j-core (GitHub)

A slightly heavier wrapper that provides a full Cypher DSL in addition to methods to simplify CRUD. It is compatible with Neo4j 2+ in both Server and Embedded modes.

neo4j (GitHub)

An OGM based on the ideas of ActiveRecord that provides app-building tools that will make any Ruby on Rails user happy. It relies on neo4j-core and, as a result, is compatible with Neo4j 2+ in both Server and Embedded modes.

We also offer a quick online course to using Neo4j and Ruby.

Follow the guidance and videos here: Getting Started with Neo4j and Ruby.

Feature Comparison

Each gem fills a different need, so the choice of a gem should be based on the plans for your app and its hosting. You may also want to review frequency of updates, versions of Neo4j supported, and size of the community. Here’s a comparison chart of the these three gems to help make your decision.

Feature neography neo4j-core neo4j


Thin wrapper for the REST API. Fewest dependencies.

Provides simple communication with DB, Cypher DSL.

Full-featured ORM similar to ActiveRecord.

Neo4j Embedded/Java API



Neo4j Server








Cypher DSL


Yes + association chaining

ActiveModel-complaint (Drop-in use with Ruby on Rails)


Legacy Indexing Support


Neo4j 1.X Support


Neo4j 2.X Support




All of the gems provide full support for Neo4j transactions.

Deployment Considerations

Very often, your gem choice may come down to how you want to deploy:


Using Ruby with a separate Neo4j Server over the HTTP API


Connecting directly to the Neo4j database files from within your Ruby process (this requires JRuby)

A separate Neo4j server is go-to choice for most developers, especially if they are used to other relational or NoSQL databases in frameworks such as Ruby on Rails. It allows you to have separate web and database servers and allows compatibility with popular PaaSes such as Heroku. If this sounds good to you, any of the popular gems are solid choices and you are free to consider whether you want a thin wrapper or the full framework experience.

Neo4j Embedded and JRuby is less common but offers blazing fast performance and access to our core Java API. The downside is that JRuby has its own configuration and compatibility demands and hosting a Java app can be difficult. Thankfully, modern app servers such as Torquebox and a strong community provide far more options and resources now than ever before. If this is right for you, the Neo4j-core and Neo4j gems will offer what you need.

Importing data

There are many ways to import your existing data depending on how it is currently structured

  • LOAD CSV is a clause built into Cypher which allows you to build your own import scripts
  • neo4j-import is a binary command which comes with Neo4j and which takes files in a specific CSV format to import data very quickly
  • neo4apis-activerecord is a good choice if you already have a project using ActiveRecord. However it also works to import an existing SQL database even if you don’t have any models defined

Get more information on our Working With Data page.


Written by our own Max De Marzi, Neography feels very familiar if you’re already used to Neo4j: it’s designed as a thin wrapper above our database APIs.

It supports the Neo4j transactional Cypher endpoint as well as the existing REST API and even supports Neo4j-Spatial.

Compared to Neo4j-core, it is notable for its smaller footprint, fewer dependencies, and support for extensions to the REST API. It is the perfect choice for basic communication with a database or as a backend for a custom OGM.

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

neo.execute_query("MATCH (person:Person) RETURN person LIMIT 10")

node = neo.create_node("age" => 31, "name" => "Max")


The Neo4j.rb project is made up of the following Ruby gems:

  • neo4j A Object-Graph-Mapper (OGM) for the Neo4j graph database. It tries to follow API conventions established by ActiveRecord but with a Neo4j flavor.
  • neo4j-core A low level driver for connecting to Neo4j. Used by the neo4j gem.
  • neo4j-rake_tasks A set of rake tasks for installing and managing a Neo4j database within your project. Used by the neo4j-core gem.

Andreas Ronge, one of our Swedish friends from Malmö, started writing his canonical Neo4j Ruby driver since before we hit 1.0.

Brian Underwood and Chris Grigg joined the project and together released version 3.0 in September 2014. Neo4j.rb 3.0 won a Neo4j Graphie award for “Best Community Contribution” at the 2014 GraphConnect Conference.

Since then Brian and Chris have continued the effort to build new features, improve the API, and increase performance. In addition to working actively on the Neo4j.rb project, Brian and Chris are very active community members, you can find them online on Stack Overflow, Gitter, and Twitter as well as in person at meetups and Neo4j events.

Both projects support accessing Neo4j in embedded mode via JRuby and server mode via MRI.


Similar to Neography, Neo4j-core is a gem that provides low-level communication to a Neo4j server. In addition to basic database communicaton and node/relationship CRUD, Neo4j-core provides strong support for Neo4j 2.0’s schema indexes, constraints, labels, and a strong Cypher DSL.

How to get running:

session = Neo4j::Session.open(:server_db,


session.query("MATCH (person:Person) RETURN person LIMIT 10")

# alternatively you can use the query chaining API:

session.query.match(person: :Person).return(:person).limit(10).to_a


The neo4j gem uses neo4j-core as an API to connect to the server and provides an ActiveRecord-like experience for use in frameworks. It adds modules allowing the creation of models that look and feel very similar to those found in vanilla Ruby on Rails. The gem builds on Neo4j-core’s foundation to streamline all aspects of node and relationship CRUD and provides an extremely advanced, intuitive, flexible DSL for generating Cypher.

How to get running:

# See the documentation for setup instructions

class Person

  include Neo4j::ActiveNode

  property :name

  has_many :out, :books, type: :OWNS_BOOK

  has_many :both, :friends, type: :HAS_FRIEND


person = Person.find_by(name: 'Jim')

# Get the books owned by Jim's friends:


Neo4j gem integrations

There are many common gems that you’ll want to use with your Neo4j database. Many are supported for the Neo4j.rb project:


File Attachment


ElasticSearch Integration

Admin User Interface

Integration With the Neo4j Spatial Plugin

Ruby Object Manager


Other Drivers


To install: gem install pacer

Express yourself clearly and model your application in terms you understand with Pacer – a JRuby gem for building embedded Neo4j applications. Pacer supports Neo4j 1.8 and 1.9 only.