shotishu / neo4j-jdbc

Neo4j JDBC driver

Neo4j JDBC driver

This is a first attempt at creating a JDBC driver for the graph database Neo4j. While Neo4j is a graph database, and JDBC is based on the relational paradigm, this driver provides a way to bridge this gap.

The textual representation of declarative queries in the Cypher query language which returns tabular results make it possible to use the JDBC concepts and APIs.

The driver can be used in conjunction with

• a Neo4j Server

• a on disk Neo4j database

• an existing Neo4j GraphDatabaseService instance passed to the driver

• an temporary in-memory instance of Neo4j

Usage

• Add the JDBC driver jar file to your applications classpath

• Load the driver with the class org.neo4j.jdbc.Driver

• Execute queries using the Cypher graph query language

• Use the according JDBC-url (see below)

To debug the driver, add ?debug=true to the URL. This will log all calls to the driver to the Java Util Logging framework.

Server

• Install a Neo4j server, and start it with the REST API enabled.

• Connect with URLs on the form jdbc:neo4j://<host>:<port>/, e.g. jdbc:neo4j://localhost:7474/

Graph Database on disk

• create or use and existing graph database on disk

• Connect with URLs on the form jdbc:neo4j:file:/path/to/db, e.g. jdbc:neo4j:file:/home/user/neo/graph.db

In-Memory Graph Database

• Connect with URLs on the form jdbc:neo4j:mem or jdbc:neo4j:mem:name, e.g. jdbc:neo4j:mem:mydb

• The passed in name allows for a database that is reusable across connections

Existing Graph Database Instance

• Connect with URLs on the form jdbc:neo4j:instance:name, e.g. jdbc:neo4j:mem:mydb and put the GraphDatabaseService object instance under the same name into the properties provided to the driver

Server-Authentication

The driver supports authentication. You can provide the JDBC connection properties "user" and "password", and these will then be used to perform BASIC AUTH authentication while performing the REST API calls.

(optional) Database/Table-MetaData

This can be done by introducing type nodes in the graph, which are directly related to the root node by the relationship TYPE. Each type node has a property "type" with its name (i.e. "tablename), and HAS_PROPERTY relationships to nodes that represent the properties that the node can have (i.e. "columns"). For each instance of this type (i.e. "row") there is a relationship from the instance to the type node via the IS_A relationship. By using this structure the JDBC driver can mimic tables of a relational database.

MetaData-Setup

• Add as many TYPE nodes as you want

• For each type node, add as many HAS_PROPERTY nodes as you want

• For each property node, set property "name" and "type". "type" should be "String" for now

• Add as many instance nodes as you want, with the defined properties, and relate them to their type node with the IS_A relationship

Quirks modes

Many of the tools below issue SQL statements in order to browse tables. For these tools to work the driver detects whether it is running in any of those environments, and if so starts a "quirks mode", whereby those standard SQL statements are replaced on the fly with the Cypher equivalents.

Using with DbVisualizer

One of the first tests I did with the driver was to connect to Neo4j using the DbVisualizer tool (www.dbvis.com/).

Here is how you can try it out:

• Download and install DbVisualizer

• Add the JDBC driver jar as a Neo4j driver in the Driver Manager.

• Add a connection to your database

• Under "Connection properties", change "SQL Statements" as follows:

  • SELECT ALL: start n=node(0) match (n)-[:TYPE]->(type)<-[:IS_A]-(instance) return instance.Firstname . Column names are hardcoded for now, as there is no * selection in Cypher yet

  • SELECT COUNT: start n=node(0) match (n)-[:TYPE]->(type)<-[:IS_A]-(instance) return count(instance)

Now you should be able to browse the type nodes as tables and the nodes of those types as rows. Use the "SQL Commander" to issue arbitrary Cypher queries to the Neo4j server.

Using with LibreOffice

To use the driver with LibreOffice (should be similar with OpenOffice, not tested though), follow these steps:

• Add the driver jar to the classpath in the Java settings in LibreOffice

• Create a new Database and select JDBC.

• Enter the JDBC URL and set org.neo4j.jdbc.Driver as driver

• Optionally enter authentication settings

• Click Finish

Now you can browse the "tables" and the data, as well as create Queries that perform Cypher queries, and view the results.

Using with IntelliJ

To use the driver with IntelliJ 11, do as follows:

• Open up the Data Sources tab

• Click +, select the JDBC driver jar, and enter the JDBC settings for the connection

• Switch to the SQL Console, select Properties and go to the Text Mode tab. As "Parameter pattern", enter (\{[\w]*\}). This will allow you to replace Cypher parameters with values before executing a query

Now you can browse "tables" and execute Cypher queries from within IntelliJ.

Using with ODBC on Windows

To use the driver as an ODBC data source in Windows, do as follows:

• Download and install "ODBC-JDBC Gateway" from Easysoft: http://www.easysoft.com/products/data_access/odbc_jdbc_gateway/

• Set up an ODBC data source by following the guide provided with the above software

Now you can browse "tables" and execute Cypher queries from any ODBC-compliant tool.