= 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. This JRuby gem uses the mature {Neo4j Java library}[http://www.neo4j.org].

It has been tested with Neo4j version 1.8.2 and 1.9.M03 ( {see here}[https://github.com/andreasronge/neo4j-core/blob/master/neo4j-core.gemspec]) and JRuby 1.7.4 (see Travis)

Notice, you do not need to install the Neo4j server since this gem comes included with the database.
However, if you still want to use the Neo4j server (e.g. the admin UI) you can connect the embedded databas with the Neo4j server using a Neo4j HA Cluster (see wiki pages).

== 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

* {Neo4j.rb with HA Cluster Screencast}[http://youtu.be/PblrbrT5JNY]
* {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}[http://rdoc.info/github/andreasronge/neo4j/Neo4j/Rails/Model]

{Neo4j::Rails::Relationship}[http://rdoc.info/github/andreasronge/neo4j/Neo4j/Rails/Relationship]

{Neo4j::Rails::Observer}[http://rdoc.info/github/andreasronge/neo4j/Neo4j/Rails/Observer]

{Neo4j::Rails::HaConsole::Railitie}[http://rdoc.info/github/andreasronge/neo4j/Neo4j/Rails/HaConsole/Railtie]

{Neo4j::Rails::Versioning}[http://rdoc.info/github/andreasronge/neo4j/Neo4j/Rails/Versioning]

{Neo4j::Rails::Compositions::ClassMethods}[http://rdoc.info/github/andreasronge/neo4j/Neo4j/Rails/Compositions/ClassMethods]

{Neo4j::Rails::AcceptId}[http://rdoc.info/github/andreasronge/neo4j/Neo4j/Rails/AcceptId]

==== 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:

 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, :index => :exact
      property :city

      has_n :friends
      has_one :address
    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]

== Rails/Neo4j.rb in a Cluster ?

Yes, check {Neo4j.rb Ha Cluster}[https://github.com/andreasronge/neo4j/wiki/Neo4j%3A%3Aha-cluster] or {Screencast}[http://youtu.be/PblrbrT5JNY]
Notice, you don't need to install the Neo4j Server, but it could be a useful tool to visualize the graph.

== 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.