Overview: Neo4j JDBC Driver

Build Status

You can find the full documentation at: http://neo4j-contrib.github.io/neo4j-jdbc/

This is the official JDBC driver for Neo4j.

This driver was mainly developed by Larus BA, Italy, a certified consulting and integration solutions partner for Neo4j. Thank you so much for all your work.

Note
The previous JDBC driver for Neo4j 2.x was moved to the https://github.com/neo4j-contrib/neo4j-jdbc-2x repository.

Being a graph database, Neo4j is not serving data in a relational way and the exact purpose of this project is to allow projects that are using the classic JDBC connector in the relational paradigm to interact with Neo4j.

This driver supports various types of database transports:

  • through the Bolt protocol (3.0.X) using jdbc:neo4j:bolt://<host>:<port>/

  • through the HTTP protocol (2.X+) using jdbc:neo4j:http://<host>:<port>/

Going forward there will also be support for:

  • direct file connection

  • embedded connection

Maven dependency

For the all-in-one module supporting both Bolt and HTTP, you can simply use:

<dependency>
    <groupId>org.neo4j</groupId>
    <artifactId>neo4j-jdbc-driver</artifactId>
    <version>{neo4j-jdbc-version}</version>
</dependency>

If you only want one of the protocols, you can depend on its module:

<dependency>
    <groupId>org.neo4j</groupId>
    <artifactId>neo4j-jdbc-bolt</artifactId>
    <version>{neo4j-jdbc-version}</version>
</dependency>

or

<dependency>
    <groupId>org.neo4j</groupId>
    <artifactId>neo4j-jdbc-http</artifactId>
    <version>{neo4j-jdbc-version}</version>
</dependency>

Minimum viable snippet

Dependency declaration
org.neo4j:neo4j-jdbc-driver:3.0
Run Query
// Connecting
try (Connection con = DriverManager.getConnection("jdbc:neo4j:bolt://localhost", 'neo4j', password)) {

    // Querying
    String query = "MATCH (u:User)-[:FRIEND]-(f:User) WHERE u.name = {1} RETURN f.name, f.age";
    try (PreparedStatement stmt = con.prepareStatement(query)) {
        stmt.setString(1,"John");

        try (ResultSet rs = stmt.execute()) {
            while (rs.next()) {
                System.out.println("Friend: "+rs.getString("f.name")+" is "+rs.getInt("f.age"));
            }
        }
    }
}

Please note that the example above uses the try-with-resource blocks that automatically closes resources when the try block is exited.

Usage with Neo4j Server

  • Install a Neo4j 3.0.X server and start it with the Bolt protocol enabled

  • Connect with URLs in the form jdbc:neo4j:bolt://<host>:<port>/ (e.g. jdbc:neo4j:bolt://localhost/)

  • You can also use additional comma separated parameters in the URL for authentication, debug mode, SSL encryption and flattening e.g. jdbc:neo4j:bolt://localhost/?user=neo4j,password=xxxx,debug=true,noSsl,flatten=[-1,100,1000]

  • Add the JDBC driver dependency or jar file to your project

  • Get a connection from DriverManager

  • Execute queries and transactions using the Cypher graph query language

Flattening

As most JDBC clients and tools don’t support complex objects, the driver can flatten returned nodes and relationships by providing all their properties as individual columns with names like u.name,r.since if you just return a node u or relationship r.

This is enabled with the JDBC-URL parameter flatten=<rows>, where <rows> indicates how many rows are sampled to determine those columns. With -1 all rows are sampled and with any other value you determine the number of rows being looked at.

Building the driver yourself

First clone the repository.

This project is composed by the following modules:

Run all unit tests & integration tests
mvn clean test
Run only integration tests
mvn clean test -Pintegration-test
Run performance tests
mvn clean test -Pperformance-test
Note
To run the performance test, you must have a Neo4j Server (3.0.X) running with the Bolt protocol enabled on port 7687 (default)

Release 3.0 Schedule

General Availability [RELEASED]

  • Extensive Tests with a variety of tools

  • Bug Fixes

  • Documentation

  • Better handling of credentials

  • Support for additional API methods

  • Explicit enabling of flatten=<rows> via JDBC URL

Release Candidate 1 [RELEASED]

  • Move to github.com/neo4j-contrib

  • Changed package to org.neo4j

  • Released to Neo4j’s maven repository

  • HTTP protocol module

Milestone 03 [RELEASED]

  • Batch processing

  • Bug fix

  • Neo4j Java Driver 1.0.1

  • Neo4j 3.0.1

License

Copyright (c) 2016 Neo4j and LARUS Business Automation

The "Neo4j JDBC Driver" is licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and limitations under the License.

Thank you

We’d like to thank:

The core development team:

Contributors:

Supporters:

Technical Reference

Usage Examples

The Bolt Driver

The Bolt driver connects to any Neo4j 3.x database that has the binary "Bolt" transport enabled.

It uses the neo4j-java-driver to provide the connectivity.

Just provide your username and password and you can connect to Neo4j.

The JDBC URL has this format: jdbc:neo4j:bolt://host:port/?username=neo4j,password=xxxx

The HTTP Driver

The HTTP driver uses the existing (since Neo4j 2.x) transaction Cypher HTTP API, and is implemented using Apache Commons httpclient and Jackson for JSON (de)serialization.

The JDBC URL has this format: jdbc:neo4j:http://host:port/?username=neo4j,password=xxxx

JDBC Compatibility

We cover these aspects of the JDBC-APIs, everything that’s not explicitely mentioned should be assumed to be not implemented:

  • Driver handling automatic loading and JDBC URLs

  • Connection, incl. autocommit and manual commit

  • Transactions

  • Statements for reads and writes

  • PreparedStatement for reads and writes, including parameters, both question marks ? and named numbered parameters {1}

  • ResultSet retrieving all columns as String, Object and their native type with optional conversions

Libraries and Frameworks

Java JDBC Usage

Plain JDBC usage was already shown before:

Dependency declaration
org.neo4j:neo4j-jdbc-driver:3.0
Run Query
// Connecting
try (Connection con = DriverManager.getConnection("jdbc:neo4j:bolt://localhost", 'neo4j', password)) {

    // Querying
    String query = "MATCH (u:User)-[:FRIEND]-(f:User) WHERE u.name = {1} RETURN f.name, f.age";
    try (PreparedStatement stmt = con.prepareStatement(query)) {
        stmt.setString(1,"John");

        try (ResultSet rs = stmt.execute()) {
            while (rs.next()) {
                System.out.println("Friend: "+rs.getString("f.name")+" is "+rs.getInt("f.age"));
            }
        }
    }
}

Spring JDBC Template

Integrating with Spring JDBC is as easy as defining a datasource in your Spring config and then using it via JDBC Template.

You can find an example application here:

Play Framework

Taken from the Play Framework Documentation. Enable the database plugin by adding javaJdbc in your build dependencies:

libraryDependencies += javaJdbc

Then you must configure a connection pool in the conf/application.conf file. By convention the default JDBC data source must be called default, but you can use other names for named databases, in this case we use neo4j

# Neo4j database configuration
db.neo4j.driver=org.neo4j.jdbc.bolt.BoltDriver
db.neo4j.url="jdbc:neo4j:bolt://localhost"
import javax.inject.Inject;

import play.mvc.Controller;
import play.db.NamedDatabase;
import play.db.Database;

// inject "neo4j" database instead of "default"
class JavaNamedDatabase extends Controller {
    private Database db;

    @Inject
    public JavaNamedDatabase(@NamedDatabase("neo4j") Database db) {
        this.db = db;
    }

    // do whatever you need with the db
}

Reporting Tools

Jasper Reports

Step 1: Create new Data Adapters:

  • Right click on Data Adapters and click on Create Data Adapter and select "Database JDBC Connection*

2f81674c 2e58 11e6 9dfc f3fed514f9fe
ebf0e510 2e58 11e6 9b36 5feed0879a1c
  • Insert the values of JDBC driver: "org.neo4j.jdbc.bolt.BoltDriver" and

  • JDBC Url: jdbc:neo4j:bolt://localhost like the image below and

  • insert your username and password

98ce1eb0 2e59 11e6 8a59 5c73cd09389f
  • Click on Driver Classpath tab then to add:

e3715aee 2e5a 11e6 95be 870d636e5e2f
  • Add the Neo4j JDBC jar file:

6a5103f2 2e5b 11e6 8574 3e4c98351789
78fc6fae 2e5b 11e6 950d 62ffcea3c11e
  • Click on Test and you should have a successful message:

b9e7d8be 2e5b 11e6 96ad 3d12faa6f588

Step 2: Retrieve Columns from Database:

  • Create new Jasper Report and click on DataSet and Query editor Dialog:

19fadea8 2e5d 11e6 9f4f fec9add565d5
  • Insert the cypher "MATCH (a)-[:ACTED_IN]→(m)←[:DIRECTED]-(d) RETURN a.name, m.title, d.name;" then click on Read Field:

aca6f0de 2e5d 11e6 832a a2388c3f1527
  • You can check data retrieve clicking on Data preview tab then Refresh Preview Data:

f432a70e 2e5d 11e6 82a0 51344894468d

Step 3: Prepare Report and create document:

23a5c2d2 2e5e 11e6 93ec 7f22dd4cc7f5
2d1b40e4 2e5e 11e6 8301 b0886b118787

Eclipse BIRT

  1. Start a new "Report project" under "Report design" perspective

    82aa4d36 3fcd 11e6 8865 17d044d34743
  2. Select the project’s name

    9ffe01d4 3fcd 11e6 8e45 c9f3841a8436
  3. Create a new report (File→New→Report) and give it a name

    e9dce37e 3fcd 11e6 84c4 83c3e7547b46
  4. Choose your template

    04240596 3fce 11e6 9e97 b8e611e48a44
  5. Create a new Datasource by right clicking "Data sources" → New Data Source and choose the second option

    79956734 3fce 11e6 8141 5777f15399e9
  6. Create a new Connection profile store (click new on both windows)

    cf2ad59e 3fce 11e6 911c 999f8b6f2cd0
  7. Choose "BIRTH JDBC Data Source" and give it a name

    f0ec6904 3fce 11e6 88c8 5be6e62ed8bd
  8. Load your jdbc jar by clicking "Manage Drivers" and select "Add"

    2d32090a 3fcf 11e6 893d ed4ccef968c4
  9. Choose your dirver location and press OK

    3fce59f6 3fcf 11e6 9fe7 f7ecca4716db
  10. Fill the driver connection parameters

    59d8e352 3fcf 11e6 8458 5faf8fea540f
  11. Click "Next" and "Finish" and choose the newly created connection profile store

    85f3630e 3fcf 11e6 9521 902bc61e5d8b
  12. Click "Next" and "Finish" and the Data Source should be created

    06b6a280 3fd0 11e6 88e7 0d6f8bc79928
  13. Create a new Dataset (right click Data Sets → New Data Set) and choose Next

    4521c4d2 3fd0 11e6 8fae bb3e0aee3e4f
  14. Type the query you want to create your Dataset with and click Finish

    698c4a36 3fd0 11e6 8ef1 2126cad983a1
  15. A new Window will appear showing the columns available with your query

    83925a2e 3fd0 11e6 9e92 cd8276a24c41
  16. You can also preview the results

    9ffde6ec 3fd0 11e6 9d32 ecb0ab797e7e
  17. Close this window and create a new Table element (Right click the document → Insert → Table)

    848ca81e 3fd3 11e6 9f85 aeed3f4e0092
  18. Choose 4 columns and click Finish

    44c07b28 3fda 11e6 8273 a4b4c0d55545
  19. Fill the table with the following data (drag and drop the datasource colums in the right position)

    edf3b98a 3fda 11e6 9d80 f4026e036770
  20. To export the report click Run → View report → As PDF

    181e062a 3fdb 11e6 89eb 3a14c959e53b

Business Intelligence Tools

QlikView / Qlik Sense via TIQ JDBC Connector

(Thanks a lot to Ralf Becher, TIQ Solutions)

TIQ Solutions provides a commercial product to enable JDBC connectivity in QlikView and Qlik Sense. The configuration is simple.

In QlikView, you can connect to Neo4j directly. In Qlik Sense you need to copy the CUSTOM CONNECT script code.

d04d482a 54d3 11e6 8813 29d3d701ea2b

If your Neo4j connection is established, you now can execute Cypher queries in LOAD statements (but mention the SQL prefix). The results get loaded into memory tables as usual.

d04dbd14 54d3 11e6 914e 0729e02e61e9
add61f14 54d4 11e6 8ed6 3792786c45c3

Tableau via jdbc2tde

(Thanks a lot to Ralf Becher, TIQ Solutions)

Integration with Tableau is not that trivial as it only generates SQL.

So you can either use the Tableau REST integration (which we will publish soon).

ba8d8f42 54d6 11e6 9838 d0e7104d36ab

Or the jdbc2tde tool from TIQ that uses JDBC queries to generate TDE files.

Those can then be loaded into Tableau and visualized and interacted with in the many ways you know and love.

ba8cf712 54d6 11e6 9eee 303abe164f75
ba88be86 54d6 11e6 89ac 2bbf942d100c
ba888ec0 54d6 11e6 8164 755ef3cb2624
ba90b0f0 54d6 11e6 8d41 fd4bc5a31b18

ETL Tools

Pentaho

Step 1: Create database connections:

Right click on Database connections and click on New

463fc1f8 34df 11e6 9dac f62def4311e2

Insert the connection parameters for source database the press Test button to check the connection:

74c1b7d8 34e0 11e6 8478 7952686766c4
846c3d84 34e0 11e6 947b e5e617800c3b

As before, select a new Database connections and insert neo4j connection parameters, set:

  • Connection Type: Generic database

  • Custom Connection URL: "jdbc:neo4j:bolt://localhost:7687"

  • Custom Driver Class Name: "org.neo4j.jdbc.Driver"

  • Login and password:

8a6df4b0 34e1 11e6 84a7 3ea9cd024529
2263fbc6 37ac 11e6 9a8d bdf8c78d96bf

Then press to Test button to check the connection:

2989eaa0 37ac 11e6 8ca7 cd5c50786a5d

Step 2: Create Steps and Hops:

  • From Design select input and click on table input top insert the source table:

95f20bfe 34e2 11e6 9ce0 c5999027c07d
9934f0a6 34e2 11e6 97b4 c1c49c276ccf
  • From Scripting click on Execute SQL script:

0fd68062 34e3 11e6 8272 562f06b4b93f
1e7ad190 34e3 11e6 8fb7 beda60ee391b
  • Double click on table input. Select the source database Connection and write query to extract data the press Preview button to check query:

73469a7e 34e3 11e6 8f77 7c8db5bbcec9
7dee0dae 34e3 11e6 8e89 457a8c5aa36c
  • Double click on Hops, select as From step the table input and as to step the Execute SQL Script:

d82771f6 34e4 11e6 85c8 07a65fe14e6f
dd56b24a 34e4 11e6 88da d0ab1fd8e008
  • Now your Hop is complete!

247b2e12 34e5 11e6 8a31 2e4329c04f1a
  • Double click on Execute SQL script. Click on Get Fields to retrive the column from source database. Write the cypher to create nodes and relationship:

32ef7a56 37ac 11e6 9e58 433ed6444b0a

Step 3: Run the job

  • Click on run this transformation or job and wait until finished:

eefac170 34e5 11e6 83d3 7f4faa4c7745
f1156e06 34e5 11e6 99b1 5d2d37b9737e
f39b13d8 34e5 11e6 8d16 869345f82dd5
  • If all ok, you should have like this:

813e5e2a 34e6 11e6 81cf 5492c664c041

Talend

(Thanks a lot to Benoit Simard)

With Talend, you can query or import your data into Neo4j using Talend JDBC Components. On the Job, you just have to add a tJDBCConnection and add the usual fields: JDBC-URL, Driver-Jar, Driver, username and password.

talend.config

NB: On the Advanced Settings tab, you can also configure the auto-commit, if you want it.

Now, you can add some tJDBCInput to make some queries to your Neo4j databases like this :

talend.query

Database Tools

Squirrel SQL

Squirrel SQL is a widely used SQL workbench that supports many databases out of the box. Adding the JDBC driver was straightforward, as was running Cypher queries and getting tabular results back.

Works in general for scalar values

  • Configured Driver via Add Driver → Extra ClassPath

  • Created New Session,

  • Worked but gave a warning about 2.1 incompatibility

67e6126e 2d85 11e6 96e5 b71a214f811b

Eclipse Database Tools

Step 1: Create a new connection profile

  • Open the Database Developement perspective:

ee537ca2 2d75 11e6 9bcb fbc1e89d987c
ee58c356 2d75 11e6 9f5e 6bc6df75bdaf
  • Click on the icon New Connection Profile:

ee556c1a 2d75 11e6 9aea 3fdcc7256ec5
  • Choose Generic JDBC (and optionally type "Neo4j 3.0 JDBC Bolt Driver" in "name" and "description" fields. Then click Next:

ee55612a 2d75 11e6 908d 910d39dc15b1

Step 2: Create a new driver definition

  • Click on the icon New Driver Definition:

ee5531fa 2d75 11e6 95d8 06f7747178bc
  • Choose "Generic JDBC Driver" in folder Name/Type (and optionally re-type "Neo4j 3.0 JDBC Bolt Driver" in the "Driver Name" field):

ee549466 2d75 11e6 97ef 3c0c0b0a5d71
  • In Folder JAR List, click Add JAR/Zip and choose the new Neo4j JDBC Bolt Driver:

ee692e58 2d75 11e6 94db 64a462195ea8
  • In Folder Properties choose the Driver Class" by clicking the icon [..]:

ee6aded8 2d75 11e6 8344 2b0a96a418c9
  • Choose org.neo4j.jdbc.bolt.BoltDriver as the Driver class:

ee7043f0 2d75 11e6 97ba efb1f3835a4c
  • Set the Connection URL to "jdbc:neo4j:bolt://localhost" and the User ID to "neo4j", then click OK:

ee6bf35e 2d75 11e6 901a 29396d251fb7
  • Set the Password and click Test Connection:

ee6b4bfc 2d75 11e6 9903 419c28499517
  • You should get Ping Succeeded! message (with your database online). Click OK and then Finish:

ee6e9154 2d75 11e6 97a4 5b5185369407

Step 3: Test the connection (match and create)

  • Open an SQL Scrapbook and execute your statement (i.e. match (n) return n):

ee7ec150 2d75 11e6 8643 8b040fb588bb
  • Create statements should work as well:

ee81b3ba 2d75 11e6 8232 b6044e855252

as you can see on the neo4j browser:

ee830f3a 2d75 11e6 9d1f 9b50aac21cb6

SQL-Shell

It’s working now on the master branch (6b166ec31bdb61f76279be717aa1f30ada5c553e)

  • Copy Neo4j JDBC driver into SQLSHELL_HOME/lib folder

  • Edit the configuration file SQLSHELL_HOME/sample.cfg for :

  • Adding neo4j driver :

[drivers]
neo4j = org.neo4j.jdbc.bolt.BoltDriver
  • Adding your database

[db_neo4j]
aliases: neo
driver: neo4j
url: jdbc:neo4j:bolt://localhost
user: neo4j
password: test
  • Now execute sqlshell with the configuration file to open neo database :

$> SQLSHELL_HOME/bin/sqlshell -c SQLSHELL_HOME/sample.cfg neo
  • Execute some queries !

c8c7f33c 2fe1 11e6 90e7 fc44be9d4866

APOC LOAD JDBC

  • Copy Neo4j JDBC Driver jar into NEO4J_HOME/plugins folder

  • Restart the database

  • Run some JDBC Queries:

WITH ['The Matrix'] as movies
CALL apoc.load.jdbcParams('jdbc:neo4j:bolt://localhost?user=neo4j,password=test','MATCH (m:Movie) WHERE m.title=? RETURN m', movies) YIELD row
RETURN row
01334dfc 2f33 11e6 8cc8 9ad9658049cd

Apache SolR

Description

You can index your Neo4j database directly into SolR with the help of SolR Data Import Handler (DIH) feature and the neo4j jdbc driver. This article is just on how to make the glue the two component via the JDBC driver.

How-to

Download the lastest release of SolR (for example : http://apache.crihan.fr/dist/lucene/solr/6.1.0/solr-6.1.0.tgz)

$>cd /tmp
$> wget http://apache.crihan.fr/dist/lucene/solr/6.1.0/solr-6.1.0.tgz

Extract it to a folder (reference as SOLR_HOME)

$> tar xzvf solr-6.1.0.tgz -C SOLR_HOME

Copy the folder SOLR_HOME/example/example-DIH/solr/solr to SOLR_HOME/server/solr/neo4j. This will create a new SolR core called neo4j with all DIH feautres enabled.

$> cp -rf SOLR_HOME/example/example-DIH/solr/solr SOLR_HOME/server/solr/neo4j

Copy The Neo4j JDBC Driver jar into folder SOLR_HOME/server/solr/neo4j/lib (create the folder of it doesn’t exist).

$> mkdir SOLR_HOME/server/solr/neo4j/lib
$> cp neo4j-jdbc-driver-3.0.1-SNAPSHOT.jar SOLR_HOME/solr/server/solr/neo4j/lib/

Edit the file SOLR_HOME/server/solr/neo4j/config/solrconfig.xml to add lib folder by adding this line :

<lib dir="./lib" />

We will configure SolR DIH feature by editing the file SOLR_HOME/server/solr/neo4j/config/solr-data-config.xml. Just replace its content by this one (don’t forget to replace the jdbc url, login password by yours):

<dataConfig>

	<dataSource type="JdbcDataSource"
				driver="org.neo4j.jdbc.Driver"
				url="jdbc:neo4j:bolt://localhost?noSsl"
				user="neo4j"
				password="test" />

	<document name="movie">
        <entity name="movie" query="MATCH (m:Movie) RETURN id(m) AS id, m.title AS title, m.tagline AS tagline, m.released AS released">
             <field name="id" column="id" />
	         <field name="title" column="title" />
             <field name="tagline_s" column="tagline" />
             <field name="release_i" column="released" />
        </entity>
	</document>

</dataConfig>

Start SolR server :

$> SOLR_HOME/bin/solr start

Open your browser at this url, http://localhost:8983/solr/#/neo4j/dataimport//dataimport , and click on the Execute button. A click on the refresh status allow you to see the status of the indexation.

solr dih