Neo4j v3 Declared Relationships

Declare relationships in your models to create methods for getting, setting, and traversing relationships.

There are a few configurable options possible in all relationship declarations. A basic understanding of Neo4j relationships is helpful, bordering on necessary, so see http://docs.neo4j.org/chunked/stable/graphdb-neo4j-relationships.html.

All has_many/has_one method calls begin with declaration of direction

Those can be:

• :in
• :out
• :both

:both comes with the caveat that the relationship created will be outgoing but matches will omit the direction.

class Show
  include Neo4j::ActiveNode
  has_many :in, :bands
end

Second argument is a symbol that sets the method and defaults: relationship type and expected object class

class Show
  include Neo4j::ActiveNode
  has_many :in, :bands
end

• Method is "bands"
• Relationship type is "#bands"
• Looks for constant Band These are only DEFAULTS, though. All can be overridden.

In v3, Declared (auto-generated) relationship types are prefixed with "#"

In the above example, the relationship type is "#bands". The reason it is that and not just "bands" is because it acts as a reminder that this relationship type was created by ActiveNode. In practice, the idea is that if you come across this relationship through a match, you don't have to wonder what it is or where it came from, since you will not have specified it explicitly anywhere. It signifies that it was automatically generated.

It is considered a best practice to specify a relationship type and not rely on automatic naming. Automatic naming, while helpful, runs the risk of reusing types and just generally making Cypher queries a bit cumbersome (and let's be honest, ugly) should you ever need to use them.

In v4, declared (auto-generated) relationship types are all caps

Similar to ActiveRecord's naming conventions for file names and tables, the association enrolled_in would become ENROLLED_IN. The # prefix is no longer used.

This behavior can be controlled with the config.neo4j.transform_rel_type option. Permitted values are:

• :upcase, the current default
• :downcase
• :legacy, downcases + leading #
• :none, takes the association name exactly as it is

Note that this only pertains to automatic relationship types. If you explicitly call type, it will use whatever you give it.

Association names, polymorphic matches and overriding the model

By default, the second argument defines the methods to be created and tells the association to look for a class of that name. If you choose to use an association name that does not match the singular or pluralized version of the model name, use the model_class option to specify a target class.

model_class can be a constant or a string. A string is recommended if you have model subclasses due to possible circular dependency issues.

class Show
  include Neo4j::ActiveNode
  has_many :in, :bands
  # looks for Band

  has_many :in, :people_playing_music
  # Uninitialized Constant PeoplePlayingMusic

  has_many :in, :people_playing_music, model_class: Band
  # overrides default
end

To define a polymorphic association, pass model_class boolean false.

class User
  include Neo4j::ActiveNode
  has_many :out, :managed_objects, type: 'manages', model_class: false
end

class Show
  include Neo4j::ActiveNode
  has_many :in, :admins, model_class: User, type: 'manages'
  # see the notes on "origin" below for a better way of doing this
end

class Band
  include Neo4j::ActiveNode
  has_many :in, :admins, model_class: User, type: 'manages'
end

Self referencing the model (e.g., parent child relations) is also possible. For example, here is how you would declare the relationship "Band inspired by Band":

class Band
  include Neo4j::ActiveNode
  has_many :out, :inspirations, model_class: Band
end

Declaring relationship type

By default, it bases relation type off of the symbol passed. Use type to declare a specific type. Doing this is considered a best practice.

class Show
  include Neo4j::ActiveNode
  has_many :out, :people_playing_instruments, type: 'performing_bands', model_class: Band
end

Declaring Origin

Rather than declaring the full relationship on two models, you can use origin to reference a "master" association.

class Show
  include Neo4j::ActiveNode
  has_many :out, :bands, type: 'performing_bands'
  has_one :out, :headliner, model_class: Band, type: 'headlined_by'
end

class Band
  include Neo4j::ActiveNode
  has_many :in, :shows, origin: :bands
  has_many :in, :headlining_shows, model_class: Show, origin: :headliner
end

The benefit of this is that changing the relationship types declared on Show will not require updates to Band. There is still a dependency -- changing the method on Show will break Band -- but this is testable and very easy to catch.

Relationship callbacks

You can specify before and after callback methods on all declared relationships. There are some simple guidelines:

• Your callback methods must accept one argument that represents the other node in the relationship. Use self for the node where the method is defined.
• If your before callback explicitly returns false, the relationship will not be created.
• has_n relationship setters will return false if a callback explicitly returns false, has_one will always return the object passed into the setter, so check for failure if you need to take action in your app

class Topic
  include Neo4j::ActiveNode
  property :last_post, type: DateTime

  has_many :in, :posts, before: :check_poster, after: :set_topic_stats
  has_one :out, :poster, model_class: User

  private

  def check_poster(other)
    return false if other.poster.nil?
  end

  def set_topic_stats(other)
    self.poster = other.poster
    self.last_post = DateTime.now
    self.save
  end
end

class Post
  include Neo4j::ActiveNode

  has_one :in, :poster, model_class: User, origin: :posts, before: :check_post_privileges, after: :notify_friends

  def check_post_privileges(other)
    return false if other.allowed_to_post == false
  end

  def notify_friends(from, to)
    # call a method to notify the poster's friends of a new post
    other.notify_friends(self)
  end
end

# elsewhere in the app...

if !(@topic.posts << post)
  #raise an error, notify someone, do something...
end

# but what if...
@post.poster = @user
# has_one callbacks do not return false, so check after setting
if @topic.poster.nil?
  notify_admins_banned_user_is_being_shady
end

Creating and querying undeclared relationships

You can create an undeclared relationship between two Neo4j::ActiveNode models.

from_node.create_rel("FRIENDS", to_node)

...and add properties to the relationship.

from_node.create_rel("FRIENDS", to_node, :weight=>1)

Querying an undeclared relationship is same as querying any declared relationship.

from_node.rels(dir: :outgoing, type: "FRIENDS")
to_node.rels(dir: :incoming, type: "FRIENDS")

from_node.rels(dir: :outgoing, type: "FRIENDS").each do |rel|
   puts rel.start_node # from_node itself
   puts rel.end_node # to_node
end

Dependent Options (v4)

Similar to ActiveRecord, you can specify four dependent options when declaring an association.

class Route
  include Neo4j::ActiveNode
  has_many :out, :stops, type: 'STOPPING_AT', dependent: :delete_orphans
end

The available options are:

• :delete, which will delete all associated records in Cypher. Callbacks will not be called. This is the fastest method.
• :destroy, which will call each on the association and then destroy on each related object. Callbacks will be called. Since this happens in Ruby, it can be a very expensive procedure, so use it carefully.
• :delete_orphans, which will delete only the associated records that have no other relationships of the same type.
• :destroy_orphans, same as above, but it takes place in Ruby.

The two orphan-destruction options are unique to Neo4j.rb. As an example of when you'd use them, imagine you are modeling tours, routes, and stops along those routes. A tour can have multiple routes, a route can have multiple stops, a stop can be in multiple routes but must have at least one. When a route is destroyed, :delete_orphans would delete only those related stops that have no other routes.

Returning relationships

There are a few different ways to return a relationship object. If you traversing a relationship between two nodes and want to work with the relationship between them at the same time, an easy way to do that is with each_with_rel.

student = Student.first
student.lessons(:node, :rel).each_with_rel do |node, rel|
  puts n.name
  puts rel[:name] #at the moment, rel props are only accessible by keys, not accessor methods
end

Note that you must assign node and relationship identifiers in your association method call.

The result is one query and one method call instead of two.

Query a certain relationship with a certain direction between two nodes at hand:

node.rels(dir: :outgoing, between: another_node).each do |rel|
   puts rel[:name]
end

Advanced Functionality

See Neo4j::ActiveRel for notes about using ActiveRel models for advanced options.