/neo4j

A Graph Database for JRuby. It uses the java lib neo4j as storage and lucene for quering/indexing

Primary LanguageRubyMIT LicenseMIT

Welcome to Neo4j.rb <img src=“https://secure.travis-ci.org/andreasronge/neo4j.png” /> <img src=“https://gemnasium.com/andreasronge/neo4j.png” /> ↑

Neo4j.rb is a graph database for JRuby.

You can think of Neo4j as a high-performance graph engine with all the features of a mature and robust database. The programmer works with an object-oriented, flexible network structure rather than with strict and static tables — yet enjoys all the benefits of a fully transactional, enterprise-strength database.

It uses two powerful and mature Java libraries:

  • Neo4J - for persistence and traversal of the graph

  • Lucene for querying and indexing.

Documentation ↑

Version >= 2.0 ↑

  • Github Wiki

  • YARD

  • RSpecs - There are 2023 RSpecs (478/neo4j-core, 425/neo4j-wrapper and 1120/this gem - 2012 April)

Version < 2.0.alpha.5 ↑

Presentation Materials and other URLs ↑

Why Neo4j.rb or a Graph Database ? ↑

Here are some of the major benefits of Neo4j.rb

  • Domain Modeling - use the language of a graph (nodes/relationship/properties) to express your domain !

    • Schema Less and Efficient storage of Semi Structured Information

    • No O/R mismatch - very natural to map a graph to an Object Oriented language like Ruby.

  • Performance

  • Embedded Database - no database tier, easier to install, test, deploy and configure. It is run in the same process as your application.

  • Express Queries as Traversals

    • Fast deep traversal instead of slow SQL queries that span many table joins.

    • Very natural to express graph related problem with traversals (recommendation engine, find shortest parth etc..)

  • Seamless integration with Ruby on Rails.

  • ACID Transaction with rollbacks support.

Public API ↑

The neo4j gem depends on the neo4j-wrapper and neo4j-core gems.

neo4j gem ↑

{Neo4j::Rails::Model}

{Neo4j::Rails::Relationship}

{Neo4j::Rails::Observer}

{Neo4j::Railtie}

{Neo4j::Rails::Versioning}

Example ↑

Example of using Neo4j with Rails 3 (ActiveModel)

class User < Neo4j::Rails::Model
  attr_accessor :password
  attr_accessible :email, :password, :password_confirmation, :pending_account

  after_save   :encrypt_password

  email_regex = /\A[\w+\-.]+@[a-z\d\-.]+\.[a-z]+\z/i

  # add an exact lucene index on the email property
  property :email, :index => :exact

  has_one(:avatar).to(Avator)

  validates :email, :presence => true,:format   => { :with => email_regex }
  validates :email, :uniqueness => true, :unless => :pending_account?
  accepts_nested_attributes_for :avatar, :allow_destroy => true

end

u = User.new(:name => 'kalle', :age => 42, :email => "bla@foo.com")
u.save

Make sure you are using JRuby !

Generate a Rails Application ↑

Example of creating an Neo4j Application from scratch: (make sure you have installed JRuby version >= 1.6.2)

gem install rails
rails new myapp -m http://andreasronge.github.com/rails3.rb
cd myapp
bundle
rails generate scaffold User name:string email:string
rails s
open a webbrowser: http://localhost:3000/users

To run it with Tomcat instead of WEBrick

gem install trinidad
trinidad

neo4j-wrapper ↑

Neo4j::NodeMixin

Neo4j::RelationshipMixin

Example ↑

Example of mapping a ruby class to a node and delaring properties and relationships and lucene index.

class Person
  include Neo4j::NodeMixin
  property :name
  property :city

  has_n :friends
  has_one :address
  index :name
end

# assume we have an transaction already running !
andreas = Person.new (:name => 'andreas')
andreas.friends << Person.new (:name => 'peter')
andreas.friends.each {|person| puts "name #{person.name}" }
Person.find("name: andreas").first.name # => 'andreas'

The Neo4j::NodeMixin and Neo4j::RelationshipMixin is implemented in the neo4j-wrapper gem

neo4j-core gem ↑

Neo4j::Node The Java Neo4j Node

Neo4j::Relationship The Java Relationship

Neo4j The Database

Neo4j::Cypher Cypher DSL, see RSpec spec/neo4j/cypher_spec

Neo4j::Algo Included algorithms, like shortest path

Example ↑

Example of creating a Neo4j::Node

require "rubygems"
require 'neo4j'

Neo4j::Transaction.run do
  node = Neo4j::Node.new(:name => 'andreas')
  node.outgoing(:friends) << Neo4j::Node.new(:name => 'peter')
  node.outgoing(:friends).each {|node| puts "name #{node[:name]}"}
end

The Neo4j::Node and Neo4j::Relationship is implemented in the neo4j-core gem.

Architecture ↑

As you seen above, neo4j.rb consists of a three layers API:

  • Layer 1, neo4j-core. For interacting with the basic building blocks of the graph database (node, properties and relationship), see Neo4j::Node and Neo4j::Relationship classes.

  • Layer 2, neo4j-wrapper. A binding API to Ruby objects, see Neo4j::NodeMixin and Neo4j::RelationshipMixin modules.

  • Layer 3, neo4j. An implementation of the Rails Active Model and a subset of the Active Record API, see Neo4j::RailsNode and Neo4j::RailsRelationship class.

Notice that you can always access the lower layers if you want to do some more advanced. You can even access the Java API directly.

Project information ↑

Configuration ↑

Development configuration - You can configure Neo4j through the Neo4j::Config object.

Neo4j::Config[:storage_path] = "/var/neo4j"

Configuring Neo4j from Rails - When using Neo4j.rb from rails you can use the normal rails configuration to set Neo4j configuration.

config.neo4j.storage_path = "#{config.root}/db/neo4j"

Contributing ↑

Have you found a bug, need help or have a patch ? Just clone neo4j.rb and send me a pull request or email me. Do you need help - send me an email (andreas.ronge at gmail dot com).

License ↑

Notice there are different license for the neo4j-community, neo4j-advanced and neo4j-enterprise jar gems. Only the neo4j-community gem is by default required.