Neo4j-core¶ ↑
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 theneo4j-core
gem (Neo4j::Core::Node
,Neo4j::Core::Relationship
, andNeo4j::Core::Path
-
wrap_level: :prop
allows you to define Ruby Procs to do your own wrapping. This is how theneo4j
gem providesActiveNode
andActiveRel
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¶ ↑
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¶ ↑
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¶ ↑
-
Neo4j.rb - MIT, see the LICENSE file github.com/neo4jrb/neo4j-core/tree/master/LICENSE.
-
Lucene - Apache, see lucene.apache.org/java/docs/features.html
-
Neo4j
- Dual free software/commercial license, see 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.