Connecting to Neo4j

In this tutorial we explain how to load data from Noe4j and display it with Ogma.

Neo4j is a scalable graph database specifically optimized to store and traverse graphs of connected data. By intuitively mapping data points and the connections between them, Neo4j powers intelligent, real-time applications.

Tutorial objectives

We use Neo4j’s javascript driver to connect to the neo4j database and send a query. The response is then translated and displayed with Ogma. In the second part of this tutorial, we add design rules to style the graph visualization and apply a layout to locate the nodes on the screen.

This tutorial assumes that an instance of Neo4j 3.0.0+ is running on the localhost, with the Bolt connector activated and the "Movies ad Actors" dataset loaded. Feel free to replicate these settings to follow along or adjust them to your specific use-case.

Importing the libraries

We use the neo4j-javascript-driver library to communicate with the Neo4j database via the Bolt binary protocol:

<!--  Import the neo4j javascript driver -->
<script src="https://cdn.jsdelivr.net/npm/neo4j-driver@1.5.1/lib/browser/neo4j-web.min.js"></script>

<script>
  // Host of your Neo4j installation
  const host = 'bolt://localhost:7687';

  // Create a driver to connect to the Neo4j database
  const driver = neo4j.v1.driver(host, neo4j.v1.auth.basic(login, password));
</script>

Send a Cypher query

Neo4j queries are written with the Cypher query language. In this example we retrieve 5 nodes from the graph.

// The Cypher query to return 5 nodes from the graph
MATCH (n) RETURN n LIMIT 5

For more details about the Cypher query language, please refer to the Cypher language reference.

To run this query on your Web page, use the following code:

// Create a session to execute the query.
const session = driver.session();
const query = 'MATCH (n:Actor)-[r]-(m:Movie) RETURN n.name, r, m.title LIMIT 5';
session
  .run(query)
  .then(result => {
    // Close the neo4j session
    session.close();

    console.log('Response from Neo4j:', JSON.stringify(result, null, 2));
  })
  .catch(error => {
    console.error(error);
  });

The Neo4j server's response should look like this:

{
  "records": [
    {
      "keys": ["n", "r", "m"],
      "length": 3,
      "_fields": [
        {
          "identity": {
            "low": 359,
            "high": 0
          },
          "labels": ["Person", "Actor"],
          "properties": {
            "name": "Dean Knowsley",
            "lastModified": "1300090343000",
            "id": "98216",
            "biography": "",
            "version": {
              "low": 37,
              "high": 0
            },
            "profileImageUrl": "http://cf1.imgobject.com/profiles/077/4beb40bd017a3c37a1000077/dean-knowsley-profile.jpg"
          }
        }
        // [...]
      ]
    }
  ]
}

Ogma can only display graph data so ensure that your queries only return nodes and edges and no tabular or numerical data. For instance, Ogma can display a shortest path query, but not a summation over quantities.

Parsing the response

Ogma embeds a Neo4j translator, so parsing and importing the response from Neo4j is a simple function call:

Ogma.parse.neo4j(response).then(rawGraph => {
  return ogma.this.ogma.addGraph(rawGraph, { locate: {} });
});

Applying styles and layout to the graph

To make our graph more readable, we apply some styles and a layout. For more information about styling, please refer to the Styling Tutorial.

// add a Rule so style the nodes
ogma.styles.addNodeRule({
  // the caption of a node is the content of "neo4jProperty.name" or "neo4jProperty.text" or "neo4jProperty.title"
  text: n =>
    n.getData('neo4jProperties.name') ||
    n.getData('neo4jProperties.text') ||
    n.getData('neo4jProperties.title')
});

// Apply a force-directed layout
ogma.layouts.forceLink({});