bbenzikry / metabase-neo4j-driver

Provides SQL and Cypher support for working with neo4j from metabase

Neo4j Metabase driver

SQL and Cypher support for Neo4j on Metabase

Neo4j Prerequisites

• Make sure your neo4j instance / cluster has APOC enabled.

Without APOC, the underlying BI connector will not be usable. For more information on the permission set required, download the BI connector docs

Installation

Run with Docker

git clone https://github.com/bbenzikry/metabase-neo4j-driver.git
cd metabase-neo4j-driver
docker build -t metabase/neo4j .
docker run --name metabase-neo4j -p 3000:3000 metabase/neo4j

JAR installation

• Download the latest metabase version from here
• Download the latest neo4j.metabase-driver.jar from the releases page
• Create a metabase folder and place your metabase.jar
• Copy neo4j.metabase-driver.jar to the plugins/ folder

  .
  ├── metabase.jar
  └── plugins
      └── neo4j.metabase-driver.jar

• Run java -jar metabase.jar

Using Cypher

• Cypher is currently only implemented for explicit querying
• All cypher queries must return column based results ( aggregation results or column values )

Working with a relational model on graphs

The JDBC driver exposes schemas for Relationships and Nodes

• Relationships

  • The driver creates one table for each distinct combination of source label, relationship type, and target label.

• Nodes

  • The driver only creates tables for nodes that have labels.
  • The driver creates one table for each distinct combination of node labels.

  Given

  • Node1, with the label [Alphabet]
  • Node2, with the label [Google]
  • Node3, with the labels[Alphabet,Google]

  The following tables will be created:

  • Alphabet
  • Google
  • Alphabet_Google

• Naming Separators between node label names and relationship names is an underscore by default

To change the Node name seperator, you can use the LabelSeparator JDBC property, or RelNodeSeperator for Relationship tables.

JDBC properties can be added via the driver configuration as shown in the image below.

For an up to date list of allowed configuration values, please download the JDBC driver

Building the driver

Prerequisites

Install Metabase as a local maven dependency, compiled for building drivers

Clone the Metabase repo

cd /path/to/metabase_source
lein install-for-building-drivers

Download and install the Neo4j BI connector

• Get the connector here

# cp the jar to the maven dir
mkdir -p ~/.m2/repository/neo4j/neo4j-bi-jdbc/1.0.0 && cp JAR_PATH ~/.m2/repository/neo4j/neo4j-bi-jdbc/1.0.0/

Build the driver

# (In the directory where you cloned this repository)
lein clean
DEBUG=1 LEIN_SNAPSHOTS_IN_RELEASE=true lein uberjar

Copy it to your plugins dir and restart Metabase

mkdir -p /path/to/metabase/plugins/
cp target/uberjar/neo4j.metabase-driver.jar /path/to/metabase/plugins/
jar -jar /path/to/metabase/metabase.jar

or:

mkdir -p /path/to/metabase_source/plugins
cp target/uberjar/neo4j.metabase-driver.jar /path/to/metabase_source/plugins/
cd /path/to/metabase_source
lein run

Caveats

This is a WIP.

It is not heavily tested and is not compatible with neo4j 3.5 ( even though the underlying JDBC driver is )

TODO

• Edge properties

• Timestamp casting support

• Cypher support

• Multiple database support

• Metabase variable substitution

• Testing

• CI

Future

• Support complex results in cypher ( e.g. non relational projections )
• Graph viz support

Known issues

• Initial DB creation and/or sync may time out. You can configure a higher timeout value with the MB_DB_CONNECTION_TIMEOUT_MS environment variable.

• In a standalone neo4j installation, if you encounter the error below, use StrictlyUseBoltScheme=true in the JDBC options ( see: #12 )

[Simba] [Neo4jJDBCDriver](100041) An error has occurred during data source connection: Failed to obtain connection towards READ server

_{^{Logos and images used in this document are licensed to their original creators and do not indicate any affiliation with this project}}

Donations

Did this project help you out?

bbenzikry.eth / 0x10c97e3e727cb3ee0bafb4f99f63225525150a35

metabase-neo4j-driver's Issues

cypher - connection pooling

Update metabase version

Add support for map arrays

See bbenzikry/neo4clj#1

The following does not work

match(e:testing)
with collect(e.date) as dates,  ["column1", "column2"] as columns
unwind dates as dt
with [{_date:dt,  _name:columns[0], avg:tointeger(rand() * 100)},{_date:dt,  _name:columns[1], avg:tointeger(rand() * 100)} ] as test_metrics
return test_metrics

while this will:

match(e:testing)
with collect(e.date) as dates,  ["column1", "column2"] as columns
unwind dates as dt
with [{_date:dt,  _name:columns[0], avg:tointeger(rand() * 100)},{_date:dt,  _name:columns[1], avg:tointeger(rand() * 100)} ] as test_metrics
unwind test_metrics as tm 
return tm._date, tm._name, tm.avg

Support direct cypher queries

Causal clustering

• Make protocol configurable
• Validate neo4j:// scheme works well

Smaller jar footprint

Cypher addition ( neo4j parser + driver ) caused a huge increase to the uberjar footprint

• Look into FFI to https://github.com/cleishm/libcypher-parser as an alternative

Cypher - prevent destructive operations

While roles and permissions are easy to use in the enterprise version, the community version is lacking.
We should use CypherParser to identify DELETE / DETACH / MERGE / CREATE / APOC and GDS persistent calls and prevent them when running a cypher query.

Upgrade cypher parser for 4.2

Support variable expansion

Clarify permission requirements for schema allocation on enterprise version

Update BI driver to 1.0.8

Cypher - multiple database support

Currently multiple databases only work for SQL access via the JDBC driver.
Cypher defaults to the default database

• Upgrade neo4clj to support configurable session for execute!

Failed to obtain connection

I have this error trying to configure the connection to my neo4j database

[Simba]Neo4jJDBCDriver An error has occurred during data source connection: Failed to obtain connection towards READ server. Known routing table is: Ttl 1614258567866, currentTime 1614258267882, routers AddressSet=[], writers AddressSet=[], readers AddressSet=[], database 'neo4j'

Tested with all available protocols

note: I can use my database from the neo4j browser, with same access configuration