= Welcome to Neo4j.rb {<img src="https://secure.travis-ci.org/andreasronge/neo4j.png" />}[http://travis-ci.org/andreasronge/neo4j] {<img src="https://gemnasium.com/andreasronge/neo4j.png" />}[https://gemnasium.com/andreasronge/neo4j]

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}[http://www.neo4j.org] - for persistence and traversal of the graph
* {Lucene}[http://lucene.apache.org/java/docs/index.html] for querying and indexing.


It has been tested with Neo4j version 1.8 ( {see here}[https://github.com/andreasronge/neo4j-core/blob/master/neo4j-core.gemspec]) and JRuby 1.6.7 & 1.7.1 (see Travis)

== Documentation

* {Github Wiki}[https://github.com/andreasronge/neo4j/wiki]
* {Blog}[http://blog.jayway.com/2012/05/07/neo4j-rb-2-0-an-overview/]
* {YARD}[http://rdoc.info/github/andreasronge/neo4j/master/frames]
* RSpecs - There are 2023 RSpecs (478/neo4j-core, 425/neo4j-wrapper and 1120/this gem - 2012 April)
* {Docs from NeoTechnology}[http://docs.neo4j.org/]

== Example applications

* {The Kvitter Rails 3.2x App}[https://github.com/andreasronge/kvitter] (kvitter = tweets in Swedish) 
* {Simple Rails 3.0 App}[https://github.com/andreasronge/neo4j-rails-example]

== 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}[http://en.wikipedia.org/wiki/Object-relational_impedance_mismatch] - very natural to map a graph to an \Object Oriented language like Ruby.
* {Performance}[http://www.oscon.com/oscon2009/public/schedule/detail/8364]
* 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 and neo4j-cypher gem.

=== 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/neo4j/rails.rb -O
 cd myapp
 bundle
 rails generate scaffold User name:string email:string
 rails s
 open a webbrowser: http://localhost:3000/users


The -O flag above means that it will skip active record.
For more information, read the {Github Wiki}[https://github.com/andreasronge/neo4j/wiki]

=== {neo4j-wrapper}[http://github.com/andreasronge/neo4j-wrapper]

{Neo4j::NodeMixin}[http://rdoc.info/github/andreasronge/neo4j-wrapper/Neo4j/NodeMixin]

{Neo4j::RelationshipMixin}[http://rdoc.info/github/andreasronge/neo4j-wrapper/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}[http://github.com/andreasronge/neo4j-wrapper] gem
For more information, read the {Github Wiki}[https://github.com/andreasronge/neo4j/wiki]

=== neo4j-core gem

{Neo4j::Node}[http://rdoc.info/github/andreasronge/neo4j-core/Neo4j/Node] The Java Neo4j Node

{Neo4j::Relationship}[http://rdoc.info/github/andreasronge/neo4j-core/Neo4j/Relationship] The Java Relationship

{Neo4j}[http://rdoc.info/github/andreasronge/neo4j-core/Neo4j] The Database

{Neo4j::Cypher}[http://rdoc.info/github/andreasronge/neo4j-core/Neo4j/Cypher] Cypher DSL, see RSpec spec/neo4j/cypher_spec

{Neo4j::Algo}[http://rdoc.info/github/andreasronge/neo4j-core/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}[http://github.com/andreasronge/neo4j-core] gem.

For more information, read the {Github Wiki}[https://github.com/andreasronge/neo4j/wiki]

== 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
* {GitHub}[http://github.com/andreasronge/neo4j/tree/master]
* {Issue Tracking}[https://github.com/andreasronge/neo4j/issues]
* {Twitter}[http://twitter.com/ronge]
* {Mailing list, neo4jrb@googlegroups.com}[http://groups.google.com/group/neo4jrb]
* {Read only, old lighthouse issues}[http://neo4j.lighthouseapp.com]

== Configuration

{Development configuration}[http://neo4j.rubyforge.org/guides/index.html#development-and-testing-configuration] - You can configure Neo4j through the {Neo4j::Config}[http://neo4j.rubyforge.org/Neo4j/Config.html] object.

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

{Configuring Neo4j from Rails}[http://neo4j.rubyforge.org/guides/configuration.html#config-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
* Neo4j.rb - MIT, see the LICENSE file http://github.com/andreasronge/neo4j/tree/master/LICENSE.
* Lucene -  Apache, see http://lucene.apache.org/java/docs/features.html
* \Neo4j - Dual free software/commercial license, see http://neo4j.org/

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.