Neo4j¶

Node

An Object or Entity which has a distinct identity. Can store arbitrary properties with values

Label

A means of identifying nodes. Nodes can have zero or more labels. While similar in concept to relational table names, nodes can have multiple labels (i.e. a node could have the labels Person and Teacher)

Relationship

A link from one node to another. Can store arbitrary properties with values. A direction is required but relationships can be traversed bi-directionally without a performance impact.

Type

Relationships always have exactly one type which describes how it is relating it’s source and destination nodes (i.e. a relationship with a FRIEND_OF type might connect two Person nodes)

Neo4j.rb¶

Neo4j.rb consists of the neo4j and neo4j-core gems.

neo4j

Provides ActiveNode and ActiveRel modules for object modeling. Introduces Model and Association concepts (see below). Depends on neo4j-core and thus both are available when neo4j is used

neo4j-core

Provides low-level connectivity, transactions, and response object wrapping. Includes Query class for generating Cypher queries with Ruby method chaining.

Model

A Ruby class including either the Neo4j::ActiveNode module (for modeling nodes) or the Neo4j::ActiveRel module (for modeling relationships) from the neo4j gem. These modules give classes the ability to define properties, associations, validations, and callbacks

Association

Defined on an ActiveNode model. Defines either a has_one or has_many relationship to a model. A higher level abstraction of a Relationship

ActiveNode¶

ActiveNode provides an Object Graph Model (OGM) for abstracting Neo4j concepts with an ActiveRecord-like API:

# Models to create nodes
person = Person.create(name: 'James', age: 15)

# Get object by attributes
person = Person.find_by(name: 'James', age: 15)

# Associations to traverse relationships
person.houses.map(&:address)

# Method-chaining to build and execute queries
Person.where(name: 'James').order(age: :desc).first

# Query building methods can be chained with associations
# Here we get other owners for pre-2005 vehicles owned by the person in question
person.vehicles(:v).where('v.year < 2005').owners(:other).to_a

Generating a new app¶

To create a new Rails app with Neo4j as the default model mapper use -m to run a script from the Neo4j project and -O to exclude ActiveRecord like so:

rails new myapp -m http://neo4jrb.io/neo4j/neo4j.rb -O

An example series of setup commands:

rails new myapp -m http://neo4jrb.io/neo4j/neo4j.rb -O
cd myapp
rake neo4j:install[community-latest]
rake neo4j:start

rails generate scaffold User name:string email:string
rails s
open http://localhost:3000/users

Adding the gem to an existing project¶

Include in your Gemfile:

# for rubygems
gem 'neo4j', '~> 6.0.0'

In application.rb:

require 'neo4j/railtie'

If you want the rails generate command to generate Neo4j models by default you can modify application.rb like so:

class Application < Rails::Application
  # ...

  config.generators { |g| g.orm :neo4j }
end

Rails configuration¶

For both new apps and existing apps the following configuration applies:

An example config/neo4j.yml file:

development:
  type: server_db
  url: http://localhost:7474

test:
  type: server_db
  url: http://localhost:7575

production:
  type: server_db
  url: http://neo4j:password@localhost:7000

You can also use your Rails configuration. The following example can be put into config/application.rb or any of your environment configurations (config/environments/(development|test|production).rb) file:

config.neo4j.session_type = :server_db
config.neo4j.session_path = 'http://localhost:7474'

Neo4j requires authentication by default but if you install using the built-in rake tasks) authentication is disabled. If you are using authentication you can configure it like this:

config.neo4j.session_path = 'http://neo4j:password@localhost:7474'

Of course it’s often the case that you don’t want to expose your username / password / URL in your repository. In these cases you can use the NEO4J_TYPE (either server_db or embedded_db) and NEO4J_URL/NEO4J_PATH environment variables.

Configuring Faraday¶

Faraday is used under the covers to connect to Neo4j. You can use the initialize option to initialize the Faraday session. Example:

config.neo4j.session_options = {initialize: { ssl: { verify: true }}}

Connection¶

To open a session to the neo4j server database:

# In JRuby or MRI, using Neo4j Server mode. When the railtie is included, this happens automatically.
Neo4j::Session.open(:server_db)

session = Neo4j::Session.open(:embedded_db, '/folder/db')
session.start

Rails configuration¶

config/application.rb

config.neo4j.session_type = :server_db
# GrapheneDB
config.neo4j.session_path = ENV["GRAPHENEDB_URL"] || 'http://localhost:7474'
# Graph Story
config.neo4j.session_path = ENV["GRAPHSTORY_URL"] || 'http://localhost:7474'

Labels¶

By default ActiveNode takes your model class’ name and uses it directly as the Neo4j label for the nodes it represents. This even includes using the module namespace of the class. That is, the class MyClass in the MyModule module will have the label MyModule::MyClass. To change this behavior, see the module_handling configuration variable.

Additionally you can change the name of a particular ActiveNode by using mapped_label_name like so:

class Post
  include Neo4j::ActiveNode

  self.mapped_label_name = 'BlogPost'
end

Indexes¶

To declare a index on a property

class Person
  include Neo4j::ActiveNode
  property :name, index: :exact
end

Only exact index is currently possible.

Indexes can also be declared like this:

class Person
  include Neo4j::ActiveNode
  property :name
  index :name
end

Constraints¶

You can declare that a property should have a unique value.

class Person
  property :id_number, constraint: :unique # will raise an exception if id_number is not unique
end

Notice an unique validation is not enough to be 100% sure that a property is unique (because of concurrency issues, just like ActiveRecord). Constraints can also be declared just like indexes separately, see above.

Labels¶

The class name maps directly to the label. In the following case both the class name and label are Post

class Post
  include Neo4j::ActiveNode
end

If you want to specify a different label for your class you can use mapped_label_name:

class Post
  include Neo4j::ActiveNode

  self.mapped_label_name = 'BlogPost'
end

If you would like to use multiple labels you can use class inheritance. In the following case object created with the Article model would have both Post and Article labels. When querying Article both labels are required on the nodes as well.

class Post
  include Neo4j::ActiveNode
end

class Article < Post
end

Serialization¶

Pass a property name as a symbol to the serialize method if you want to save a hash or an array with mixed object types* to the database.

class Student
  include Neo4j::ActiveNode

  property :links

  serialize :links
end

s = Student.create(links: { neo4j: 'http://www.neo4j.org', neotech: 'http://www.neotechnology.com' })
s.links
# => {"neo4j"=>"http://www.neo4j.org", "neotech"=>"http://www.neotechnology.com"}
s.links.class
# => Hash

Neo4j.rb serializes as JSON by default but pass it the constant Hash as a second parameter to serialize as YAML. Those coming from ActiveRecord will recognize this behavior, though Rails serializes as YAML by default.

Neo4j allows you to save Ruby arrays to undefined or String types but their contents need to all be of the same type. You can do user.stuff = [1, 2, 3] or user.stuff = [“beer, “pizza”, “doritos”] but not user.stuff = [1, “beer”, “pizza”]. If you wanted to do that, you could call serialize on your property in the model.

Creating Unique Relationships¶

By including the unique option in a has_many or has_one association’s method call, you can change the Cypher used to create from “CREATE” to “CREATE UNIQUE.”

has_many :out, :friends, type: 'FRIENDS_WITH', model_class: User, unique: true

Instead of true, you can give one of three different options:

• :none, also used true is given, will not include properties to determine whether ot not to create a unique relationship. This means that no more than one relationship of the same pairing of nodes, rel type, and direction will ever be created.
• :all, which will include all set properties in rel creation. This means that if a new relationship will be created unless all nodes, type, direction, and rel properties are matched.
• {on: [keys]} will use the keys given to determine whether to create a new rel and the remaining properties will be set afterwards.

Eager Loading¶

ActiveNode supports eager loading of associations in two ways. The first way is transparent. When you do the following:

person.blog_posts.each do |post|
  puts post.title
  puts "Tags: #{post.tags.map(&:name).join(', ')}"
  post.comments.each do |comment|
    puts '  ' + comment.title
  end
end

Only three Cypher queries will be made:

• One to get the blog posts for the user
• One to get the tags for all of the blog posts
• One to get the comments for all of the blog posts

While three queries isn’t ideal, it is better than the naive approach of one query for every call to an object’s association (Thanks to DataMapper for the inspiration).

For those times when you need to load all of your data with one Cypher query, however, you can do the following to give ActiveNode a hint:

person.blog_posts.with_associations(:tags, :comments).each do |post|
  puts post.title
  puts "Tags: #{post.tags.map(&:name).join(', ')}"
  post.comments.each do |comment|
    puts '  ' + comment.title
  end
end

All that we did here was add .with_associations(:tags, :comments). In addition to getting all of the blog posts, this will generate a Cypher query which uses the Cypher COLLECT() function to efficiently roll-up all of the associated objects. ActiveNode then automatically structures them into a nested set of ActiveNode objects for you.

From an ActiveRel Model¶

Once setup, ActiveRel models follow the same rules as ActiveNode in regard to properties. Declare them to create setter/getter methods. You can also set created_at or updated_at for automatic timestamps.

ActiveRel instances require related nodes before they can be saved. Set these using the from_node and to_node methods.

rel = EnrolledIn.new
rel.from_node = student
rel.to_node = lesson

You can pass these as parameters when calling new or create if you so choose.

rel = EnrolledIn.new(from_node: student, to_node: lesson)
#or
rel = EnrolledIn.create(from_node: student, to_node: lesson)

From a has_many or has_one association¶

Add the :rel_class option to an association with the name of an ActiveRel model. Association creation and querying will use this rel class, verifying classes, adding defaults, and performing callbacks.

class Student
  include Neo4j::ActiveNode
  has_many :out, :lessons, rel_class: :EnrolledIn
end

Creating Unique Relationships¶

The creates_unique class method will change the Cypher generated during rel creation from CREATE to CREATE UNIQUE. It may be called with one optional argument of the following:

• :none, also used when no argument is given, will not include properties to determine whether ot not to create a unique relationship. This means that no more than one relationship of the same pairing of nodes, rel type, and direction will ever be created.
• :all, which will include all set properties in rel creation. This means that if a new relationship will be created unless all nodes, type, direction, and rel properties are matched.
• {on: [keys]} will use the keys given to determine whether to create a new rel and the remaining properties will be set afterwards.

:each_rel, :each_with_rel, or :pluck methods¶

Any of these methods can return relationship objects.

Student.first.lessons.each_rel { |r| }
Student.first.lessons.each_with_rel { |node, rel| }
Student.first.query_as(:s).match('s-[rel1:\`enrolled_in\`]->n2').pluck(:rel1)

These are available as both class or instance methods. Because both each_rel and each_with_rel return enumerables when a block is skipped, you can take advantage of the full suite of enumerable methods:

Lesson.first.students.each_with_rel.select{ |n, r| r.grade > 85 }

Be aware that select would be performed in Ruby after a Cypher query is performed. The example above performs a Cypher query that matches all students with relationships of type enrolled_in to Lesson.first, then it would call select on that.

Separation of Relationship Logic¶

ActiveRel really shines when you have multiple associations that share a relationship type. You can use an ActiveRel model to separate the relationship logic and just let the node models be concerned with the labels of related objects.

class User
  include Neo4j::ActiveNode
  property :managed_stats, type: Integer #store the number of managed objects to improve performance

  has_many :out, :managed_lessons,  model_class: Lesson,  rel_class: :ManagedRel
  has_many :out, :managed_teachers, model_class: Teacher, rel_class: :ManagedRel
  has_many :out, :managed_events,   model_class: Event,   rel_class: :ManagedRel
  has_many :out, :managed_objects,  model_class: false,   rel_class: :ManagedRel

  def update_stats
    managed_stats += 1
    save
  end
end

class ManagedRel
  include Neo4j::ActiveRel
  after_create :update_user_stats
  validate :manageable_object
  from_class User
  to_class :any
  type 'manages'

  def update_user_stats
    from_node.update_stats
  end

  def manageable_object
    errors.add(:to_node) unless to_node.respond_to?(:managed_by)
  end
end

# elsewhere
rel = ManagedRel.new(from_node: user, to_node: any_node)
if rel.save
  # validation passed, to_node is a manageable object
else
  # something is wrong
end

Types and Conversion¶

The type option has some interesting qualities that are worth being aware of when developing. It defines the type of object that you expect when returning the value to Ruby, _not_ the type that will be stored in the database. There are a few types available by default.

• String
• Integer
• Fixnum
• BigDecimal
• Date
• Time
• DateTime
• Boolean (TrueClass or FalseClass)

Declaring a type is not necessary and, in some cases, is better for performance. You should omit a type declaration if you are confident in the consistency of data going to/from the database.

class Post
  include Neo4j::ActiveNode

  property :score, type: Integer
  property :created_at, type: DateTime
end

In this model, the score property’s type will ensure that String interpretations of numbers are always converted to Integer when you return the property in Ruby. As an added bonus, it will convert before saving to the database because Neo4j is capable of storing Ints natively, so you won’t have to convert every time. DateTimes, however, are a different beast, because Neo4j cannot handle Ruby’s native formats. To work around this, type converter knows to change the DateTime object into an Integer before saving and then, when loading the node, it will convert the Integer back into a DateTime.

This magic comes with a cost. DateTime conversion in particular is expensive and if you are obsessed with speed, you’ll find that it slows you down. A tip for those users is to set your timestamps to type: Integer and you will end up with Unix timestamps that you can manipulate if/when you need them in friendlier formats.

Custom Converters¶

It is possible to define custom converters for types not handled natively by the gem.

class RangeConverter
  class << self
    def primitive_type
      String
    end

    def convert_type
      Range
    end

    def to_db(value)
      value.to_s
    end

    def to_ruby(value)
      ends = value.to_s.split('..').map { |d| Integer(d) }
      ends[0]..ends[1]
    end
    alias_method :call, :to_ruby
  end

  include Neo4j::Shared::Typecaster
end

This would allow you to use property :my_prop, type: Range in a model. Each method and the alias_method call is required. Make sure the module inclusion happens at the end of the file.

primitive_type is used to fool ActiveAttr’s type converters, which only recognize a few basic Ruby classes.

convert_type must match the constant given to the type option.

to_db provides logic required to transform your value into the class defined by primitive_type. It will store the object in the database as this type.

to_ruby provides logic to transform the DB-provided value back into the class expected by code using the property. It shuld return an object of the type set in convert_type.

Note the alias_method to make to_ruby respond to call. This is to provide compatibility with the ActiveAttr dependency.

An optional method, converted?(value) can be defined. This should return a boolean indicating whether a value is already of the expected type for Neo4j.

.find¶

Find an object by id_property (TODO: LINK TO id_property documentation)

.find_by¶

find_by and find_by! behave as they do in ActiveRecord, returning the first object matching the criteria or nil (or an error in the case of find_by!)

Post.find_by(title: 'Neo4j.rb is awesome')

Querying the scope¶

Similar to ActiveRecord you can perform various operations on a scope like so:

lesson.teachers.where(name: /.* smith/i, age: 34).order(:name).limit(2)

The arguments to these methods are translated into Cypher query statements. For example in the above statement the regular expression is translated into a Cypher =~ operator. Additionally all values are translated into Neo4j query parameters for the best performance and to avoid query injection attacks.

Chaining associations¶

As you’ve seen, it’s possible to chain methods to build a query on one model. In addition it’s possible to also call associations at any point along the chain to transition to another associated model. The simplest example would be:

student.lessons.teachers

This would returns all of the teachers for all of the lessons which the students is taking. Keep in mind that this builds only one Cypher query to be executed when the result is enumerated. Finally you can combine scoping and association chaining to create complex cypher query with simple Ruby method calls.

student.lessons(:l).where(level: 102).teachers(:t).where('t.age > 34').pluck(:l)

Here we get all of the lessons at the 102 level which have a teacher older than 34. The pluck method will actually perform the query and return an Array result with the lessons in question. There is also a return method which returns an Array of result objects which, in this case, would respond to a call to the #l method to return the lesson.

Note here that we’re giving an argument to the associaton methods (lessons(:l) and teachers(:t)) in order to define Cypher variables which we can refer to. In the same way we can also pass in a second argument to define a variable for the relationship which the association follows:

student.lessons(:l, :r).where("r.start_date < {the_date} and r.end_date >= {the_date}").params(the_date: '2014-11-22').pluck(:l)

Here we are limiting lessons by the start_date and end_date on the relationship between the student and the lessons. We can also use the rel_where method to filter based on this relationship:

student.lessons.where(subject: 'Math').rel_where(grade: 85)

Associations and Unpersisted Nodes¶

There is some special behavior around association creation when nodes are new and unsaved. Below are a few scenarios and their outcomes.

When both nodes are persisted, associations changes using << or = take place immediately – no need to call save.

student = Student.first
Lesson = Lesson.first
student.lessons << lesson

In that case, the relationship would be created immediately.

When the node on which the association is called is unpersisted, no changes are made to the database until save is called. Once that happens, a cascading save event will occur.

student = Student.new
lesson = Lesson.first || Lesson.new
# This method will not save `student` or change relationships in the database:
student.lessons << lesson

Once we call save on student, two or three things will happen:

• Since student is unpersisted, it will be saved
• If lesson is unpersisted, it will be saved
• Once both nodes are saved, the relationship will be created

This process occurs within a transaction. If any part fails, an error will be raised, the transaction will fail, and no changes will be made to the database.

Finally, if you try to associate an unpersisted node with a persisted node, the unpersisted node will be saved and the relationship will be created immediately:

student = Student.first
lesson = Lesson.new
student.lessons << lesson

In the above example, lesson would be saved and the relationship would be created immediately. There is no need to call save on student.

Parameters¶

If you need to use a string in where, you should set the parameter manually.

Student.all.where("s.age < {age} AND s.name = {name} AND s.home_town = {home_town}")
  .params(age: params[:age], name: params[:name], home_town: params[:home_town])
  .pluck(:s)

Variable-length relationships¶

Introduced in version 5.1.0

It is possible to specify a variable-length qualifier to apply to relationships when calling association methods.

student.friends(rel_length: 2)

This would find the friends of friends of a student. Note that you can still name matched nodes and relationships and use those names to build your query as seen above:

student.friends(:f, :r, rel_length: 2).where('f.gender = {gender} AND r.since >= {date}').params(gender: 'M', date: 1.month.ago)

There are many ways to provide the length information to generate all the various possibilities Cypher offers:

# As a Fixnum:
## Cypher: -[:`FRIENDS`*2]->
student.friends(rel_length: 2)

# As a Range:
## Cypher: -[:`FRIENDS`*1..3]->
student.friends(rel_length: 1..3) # Get up to 3rd degree friends

# As a Hash:
## Cypher: -[:`FRIENDS`*1..3]->
student.friends(rel_length: {min: 1, max: 3})

## Cypher: -[:`FRIENDS`*0..]->
student.friends(rel_length: {min: 0})

## Cypher: -[:`FRIENDS`*..3]->
student.friends(rel_length: {max: 3})

# As the :any Symbol:
## Cypher: -[:`FRIENDS`*]->
student.friends(rel_length: :any)

#match¶

.match('n')

MATCH n

.match(:n)

MATCH n

.match(n: Person)

MATCH (n:`Person`)

.match(n: 'Person')

MATCH (n:`Person`)

.match(n: ':Person')

MATCH (n:Person)

.match(n: :Person)

MATCH (n:`Person`)

.match(n: [:Person, "Animal"])

MATCH (n:`Person`:`Animal`)

.match(n: ' :Person')

MATCH (n:Person)

.match(n: nil)

MATCH (n)

.match(n: 'Person {name: "Brian"}')

MATCH (n:Person {name: "Brian"})

.match(n: {name: 'Brian', age: 33})

MATCH (n {name: {n_name}, age: {n_age}})

Parameters: {:n_name=>"Brian", :n_age=>33}

.match(n: {Person: {name: 'Brian', age: 33}})

MATCH (n:`Person` {name: {n_Person_name}, age: {n_Person_age}})

Parameters: {:n_Person_name=>"Brian", :n_Person_age=>33}

.match('n--o')

MATCH n--o

.match('n--o').match('o--p')

MATCH n--o, o--p

one node object¶

.match_nodes(var: node_object)

MATCH var WHERE (ID(var) = {ID_var})

Parameters: {:ID_var=>246}