Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/neo4jrb/neo4j-core

A simple unified API that can access both the server and embedded Neo4j database. Used by the neo4j gem
https://github.com/neo4jrb/neo4j-core

adaptor driver graph-database neo4j ruby

Last synced: 14 days ago
JSON representation

A simple unified API that can access both the server and embedded Neo4j database. Used by the neo4j gem

Awesome Lists containing this project

README 

        
# Neo4j-core



[![Actively Maintained](https://img.shields.io/badge/Maintenance%20Level-Actively%20Maintained-green.svg)](https://gist.github.com/cheerfulstoic/d107229326a01ff0f333a1d3476e068d)

[![Code Climate](https://codeclimate.com/github/neo4jrb/neo4j-core.svg)](https://codeclimate.com/github/neo4jrb/neo4j-core)

[![Build Status](https://travis-ci.org/neo4jrb/neo4j-core.svg)](https://travis-ci.org/neo4jrb/neo4j-core)

[![Coverage Status](https://coveralls.io/repos/neo4jrb/neo4j-core/badge.svg?branch=master)](https://coveralls.io/r/neo4jrb/neo4j-core?branch=master)

[![PullReview stats](https://www.pullreview.com/github/neo4jrb/neo4j-core/badges/master.svg?)](https://www.pullreview.com/github/neo4jrb/neo4j-core/reviews/master)



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`](https://github.com/neo4jrb/neo4j/blob/master/lib/neo4j/active_node/node_wrapper.rb) and [`rel_wrapper.rb`](https://github.com/neo4jrb/neo4j/blob/master/lib/neo4j/active_rel/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:



```ruby

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:



```ruby

  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:



 * http://neo4jrb.readthedocs.org/en/stable/



## Support



### Issues



[![Next Release](https://badge.waffle.io/neo4jrb/neo4j-core.png?label=Next%20Release&title=Next%20Release) ![In Progress](https://badge.waffle.io/neo4jrb/neo4j-core.png?label=In%20Progress&title=In%20Progress) ![In Master](https://badge.waffle.io/neo4jrb/neo4j-core.png?label=In%20Master&title=In%20Master)](https://waffle.io/neo4jrb/neo4j-core)



[![Post an issue](https://img.shields.io/badge/Bug%3F-Post%20an%20issue!-blue.svg)](https://waffle.io/neo4jrb/neo4j-core)



### Get Support



#### Documentation



All new documentation will be done via our [readthedocs](http://neo4jrb.readthedocs.org) site, though some old documentation has yet to be moved from our [wiki](https://github.com/neo4jrb/neo4j/wiki) (also there is the [neo4j-core wiki](https://github.com/neo4jrb/neo4j-core/wiki))



#### Contact Us



[![StackOverflow](https://img.shields.io/badge/StackOverflow-Ask%20a%20question!-blue.svg)](http://stackoverflow.com/questions/ask?tags=neo4j.rb+neo4j+ruby)  [![Gitter](https://img.shields.io/badge/Gitter-Join%20our%20chat!-blue.svg)](https://gitter.im/neo4jrb/neo4j?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)  [![Twitter](https://img.shields.io/badge/Twitter-Tweet%20with%20us!-blue.svg)](https://twitter.com/neo4jrb)



## Developers



### Original Author



* [Andreas Ronge](https://github.com/andreasronge)



### Previous Maintainers



* [Brian Underwood](https://github.com/cheerfulstoic)

* [Chris Grigg](https://github.com/subvertallchris)



### Current Maintainers



* [Heinrich Klobuczek](https://github.com/klobuczek)

* [Amit Suryavanshi](https://github.com/amitsuryavanshi)



Consulting support? Contact [Heinrich](https://gitter.im/klobuczek) and/or [Amit](https://gitter.im/amitTheSongadya_twitter)



## Contributing



Pull request with high test coverage and good [code climate](https://codeclimate.com/github/neo4jrb/neo4j-core) 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

* Neo4j.rb - MIT, see the LICENSE file http://github.com/neo4jrb/neo4j-core/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.