Neo4j-core

Actively Maintained Code Climate Build Status Coverage Status PullReview stats

A simple Ruby wrapper around the Neo4j graph database that works with the server and embedded Neo4j API. This gem can be used both from JRuby and normal MRI. It can be used standalone without the neo4j gem.

Basic usage

Executing Cypher queries

To make a basic connection to Neo4j to execute Cypher queries, first choose an adaptor. Adaptors for HTTP, Bolt, and Embedded mode (jRuby only) are available. You can create an adaptor like:

require 'neo4j/core/cypher_session/adaptors/http'
http_adaptor = Neo4j::Core::CypherSession::Adaptors::HTTP.new('http://neo4j:pass@localhost:7474', options)

# or

require 'neo4j/core/cypher_session/adaptors/bolt'
bolt_adaptor = Neo4j::Core::CypherSession::Adaptors::Bolt.new('bolt://neo4j:pass@localhost:7687', options)

# or

require 'neo4j/core/cypher_session/adaptors/embedded'
neo4j_adaptor = Neo4j::Core::CypherSession::Adaptors::Embedded.new('/file/path/to/graph.db', options)

The options are specific to each adaptor. See below for details.

Once you have an adaptor you can create a session like so:

neo4j_session = Neo4j::Core::CypherSession.new(http_adaptor)

From there you can make queries with a Cypher string:

# Basic query
neo4j_session.query('MATCH (n) RETURN n LIMIT 10')

# Query with parameters
neo4j_session.query('MATCH (n) RETURN n LIMIT {limit}', limit: 10)

Or via the Neo4j::Core::Query class

query_obj = Neo4j::Core::Query.new.match(:n).return(:n).limit(10)

neo4j_session.query(query_obj)

Making multiple queries with one request is supported with the HTTP Adaptor:

results = neo4j_session.queries do
  append 'MATCH (n:Foo) RETURN n LIMIT 10'
  append 'MATCH (n:Bar) RETURN n LIMIT 5'
end

results[0] # results of first query
results[1] # results of second query

When doing batched queries, there is also a shortcut for getting a new Neo4j::Core::Query:

results = neo4j_session.queries do
  append query.match(:n).return(:n).limit(10)
end

results[0] # result

Adaptor Options

As mentioned above, each of the adaptors take different sets of options. They are enumerated below:

Shared options

All adaptors take wrap_level as an option. This can be used to control how nodes, relationships, and path data is returned:

  • wrap_level: :none will return Ruby hashes
  • wrap_level: :core_entity will return objects from the neo4j-core gem (Neo4j::Core::Node, Neo4j::Core::Relationship, and Neo4j::Core::Path
  • wrap_level: :prop allows you to define Ruby Procs to do your own wrapping. This is how the neo4j gem provides ActiveNode and ActiveRel objects (see the node_wrapper.rb and rel_wrapper.rb files for examples on how this works

All adaptors will also take either a logger option with a Ruby logger to define where it will log to.

All adaptors will also take the skip_instrumentation option to skip logging of queries.

All adaptors will also take the verbose_query_logs option which can be true or false (false being the default). This will change the logging to output the source line of code which caused a query to be executed (note that the skip_instrumentation should not be set for logging to be produced).

Bolt

The Bolt adaptor takes connect_timeout, read_timeout, and write_timeout options which define appropriate timeouts. The connect_timeout is 10 seconds and the read_timeout and write_timeout are -1 (no timeout). This is to cause the underlying net_tcp_client gem to operate in blocking mode (as opposed to non-blocking mode). When using non-blocking mode problems were found and since the official Neo4j drivers in other languages use blocking mode, this is what this gem uses by default. This issue could potentially be a bug in the handling of the EAGAIN signal, but it was not investigated further. Set the read/write timeouts at your own risk.

The Bolt adaptor also takes an ssl option which also corresponds to net_tcp_client's ssl option (which, in turn, corresponds to Ruby's OpenSSL::SSL::SSLContext). By default SSL is used. For most cloud providers that use public certificate authorities this open generally won't be needed. If you've setup Neo4j yourself you will need to provide the certificate like so:

cert_store = OpenSSL::X509::Store.new
cert_store.add_file('/the/path/to/your/neo4j.cert')
ssl: {cert_store: cert_store}}
bolt_adaptor = Neo4j::Core::CypherSession::Adaptors::Bolt.new('bolt://neo4j:pass@localhost:7687', ssl: {cert_store: cert_store})

You can also turn SSL off by simply specifying ssl: false

HTTP

Since the HTTP adaptor uses the faraday gem under the covers, it takes a faraday_configurator option. This allows you to pass in a Proc which works just like a Faraday setup block:

  faraday_configurator: proc do |faraday|
    # The default configurator uses typhoeus so if you override the configurator you must specify this
    faraday.adapter :typhoeus
    # Optionally you can instead specify another adaptor
    # faraday.use Faraday::Adapter::NetHttpPersistent

    # If you need to set options which would normally be the second argument of `Faraday.new`, you can do the following:
    faraday.options[:open_timeout] = 5
    faraday.options[:timeout] = 65
    # faraday.options[:ssl] = { verify: true }
  end

Embedded

The Embedded adaptor takes properties_file and properties_map options which are passed to loadPropertiesFromFile and setConfig on the GraphDatabaseBuilder class from the Neo4j Java API.

Documentation

Our documentation on ReadTheDocs covers both the neo4j and neo4j-core gems:

Support

Issues

Next Release In Progress In Master

Post an issue

Get Support

Documentation

All new documentation will be done via our readthedocs site, though some old documentation has yet to be moved from our wiki (also there is the neo4j-core wiki)

Contact Us

StackOverflow Gitter Twitter

Developers

Original Author

Current Maintainers

Consulting support? Contact Chris and/or Brian

Contributing

Pull request with high test coverage and good code climate values will be accepted faster. Notice, only JRuby can run all the tests (embedded and server db). To run tests with coverage: rake coverage.

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.