neo4j-gremlin-bolt

This project allows the use of the Apache Tinkerpop Java API with the neo4j server using the BOLT protocol.

Build status

Build Status Coverage Status Maven Central Contributors

Requirements

Usage

Add the Neo4j Apache Tinkerpop implementation to your project:

Maven

    <dependency>
        <groupId>com.steelbridgelabs.oss</groupId>
        <artifactId>neo4j-gremlin-bolt</artifactId>
        <version>{version}</version>
    </dependency>

*Please check the Maven Central for the latest version available.

License

neo4j-gremlin-bolt and it's modules are licensed under the Apache License v 2.0.

Features

Graph API

Element ID providers

The library supports an open architecture for element ID generation for new Vertices and Edges. The following element ID providers are supported out of the box:

Neo4J native id() support, see Neo4JNativeElementIdProvider for more information.

    // create id provider
    Neo4JElementIdProvider<?> provider = new Neo4JNativeElementIdProvider();

Pros:

Cons:

Database sequence support, see DatabaseSequenceElementIdProvider for more information.

    // create id provider
    Neo4JElementIdProvider<?> provider = new DatabaseSequenceElementIdProvider(driver);

Pros:

Cons:

Custom providers, by implementing the Neo4JElementIdProvider interface.

Connecting to the database

    // create driver instance
    Driver driver = GraphDatabase.driver("bolt://localhost", AuthTokens.basic("neo4j", "neo4j"));
    // create id provider instances
    vertexIdProvider = ...
    edgeIdProvider = ...
    // create graph instance
    try (Graph graph = new Neo4JGraph(driver, databaseName, vertexIdProvider, edgeIdProvider)) {

    }

Working with transactions

    // create graph instance
    try (Graph graph = new Neo4JGraph(driver, databaseName, vertexIdProvider, edgeIdProvider)) {
        // begin transaction
        try (Transaction transaction = graph.tx()) {
            // use Graph API to create, update and delete Vertices and Edges

            // commit transaction
            transaction.commit();
        }
    }

Neo4J BOLT+Routing support

    // create graph instance
    try (Graph graph = new Neo4JGraph(driver, databaseName, vertexIdProvider, edgeIdProvider, false, "bookmark-1")) {
        // begin transaction
        try (Transaction transaction = graph.tx()) {
            // use Graph API to create, update and delete Vertices and Edges

            // commit transaction
            transaction.commit();
        }
    }
    // create graph instance
    try (Graph graph = new Neo4JGraph(driver, databaseName, vertexIdProvider, edgeIdProvider, true, "bookmark-1")) {
        // begin transaction
        try (Transaction transaction = graph.tx()) {
            // use Graph API to read Vertices and Edges

            // commit transaction
            transaction.commit();
        }
    }

Enabling Neo4J profiler

    // create graph instance
    try (Neo4JGraph graph = new Neo4JGraph(driver, databaseName, vertexIdProvider, edgeIdProvider)) {
        // enable profiler
        graph.setProfilerEnabled(true);

    }

The library will prefix CYPHER statements with the PROFILE clause dumping the output into the log file, example:

2016-08-26 23:19:42.226  INFO 98760 --- [-f6753a03391b-1] c.s.o.n.s.summary.ResultSummaryLogger    : Profile for CYPHER statement: Statement{text='PROFILE MATCH (n:Person{id: {id}})-[r:HAS_ADDRESS]->(m) RETURN n, r, m', parameters={id: 1306984}}

+----------------------+----------------+------+---------+-----------+
| Operator             + Estimated Rows + Rows + DB Hits + Variables |
+----------------------+----------------+------+---------+-----------+
| +ProduceResults      |              0 |    1 |       0 | m, n, r   |
| |                    +----------------+------+---------+-----------+
| +Expand(All)         |              0 |    1 |       2 | m, n, r   |
| |                    +----------------+------+---------+-----------+
| +Filter              |              0 |    1 |       1 | n         |
| |                    +----------------+------+---------+-----------+
| +NodeUniqueIndexSeek |              0 |    1 |       2 | n         |
+----------------------+----------------+------+---------+-----------+

Working with Vertices and Edges

Create a Vertex

Create a new Vertex in the current graph call the Graph.addVertex() method.

  // create a vertex in current graph
  Vertex vertex = graph.addVertex();

Create a new Vertex in the current graph with property values:

  // create a vertex in current graph with property values
  Vertex vertex = graph.addVertex("name", "John", "age", 50);

Create a new Vertex in the current graph with a Label:

  // create a vertex in current graph with label
  Vertex vertex1 = graph.addVertex("Person");
  // create another vertex in current graph with label
  Vertex vertex2 = graph.addVertex(T.label, "Company");

Building the library

To compile the code and run all the unit tests:

mvn clean install

To run the Tinkerpop integration tests you need a running instance of the neo4j server. The easiest way to get one up and running is by using the official neo4j docker image:

docker run -d --name neo4j -p 7687:7687 -p 7474:7474 -e NEO4J_AUTH=neo4j/neo4j123 -e NEO4J_ACCEPT_LICENSE_AGREEMENT=yes neo4j:3.4-enterprise

And then execute the integration tests by running the following command:

mvn test -Pintegration-test