Start a KeyLines trial

To follow this tutorial, you’ll need a KeyLines evaluation account.

Request a trial account

Neo4j is a robust, scalable native graph database. It’s the most widely-used graph database in the world, with many years in production and millions of downloads. Its power and easy integration means it’s a popular back-end option for many KeyLines developers.

In this tutorial, we’ll walk through the steps of connecting KeyLines to your Neo4j database. In addition, our SDK site has a number of Neo4j demos, available for you to download and customize.

Visualization architecture

KeyLines itself is a JavaScript file that’s deployed to a web server. A chart element (powered by either HTML5 Canvas or WebGL) is then embedded into a web page for the user to access. As the user interacts with the chart, events – like click, double-click, drag – are raised. You can then customize the response to these events, creating a custom user experience.

The architecture is clean, secure and fits any IT environment:

The Neo4j browser, a tool for developers to visualize their data schema
The KeyLines – Neo4j visualization architecture

Step 1: Connect Neo4j to KeyLines

The first step is to setup your Neo4j instance and connect it to KeyLines. Thanks to KeyLines’ Cypher integration, this is pretty simple. If you prefer the Neo4j Bolt protocol, take a look at this blog post as well.

  1. Download the Neo4j files from https://neo4j.com/download/ and follow the installation instructions.

  2. Access the Neo4j browser by navigating to the following URL in Chrome or Firefox: http://localhost:7474/browser/. You should see a new empty database.

  3. Configure your username and password, it will be required to interact with the REST interface later.

    You should be able to call a REST interface running at http://localhost:7474/db/data/transaction/commit. This is how KeyLines submits cypher queries, and how it receives the results as a JSON file. If you plan to send multiple statements to the database we recommend omitting the final /commit.

    Note: if you are running an older version of Neo4j – pre v2.2 – you will need to use the legacy end-point at http://localhost:7474/db/data/cypher. Generally this guide is written for v2.2 and later.

  4. Type :play movie graph in Neo4j browser command-line and follow the first step to get some sample cypher code. Run the create code to generate some data based around actors in the Matrix movies.

Step 2: Embed KeyLines in a web page

Once you have access to the KeyLines SDK and have installed your instance of Neo4j, you can embed a KeyLines chart into your webpage.

The HTML code below is 1) loading a webpage, and 2) creating a KeyLines chart object.

<!DOCTYPE html>
<html>
<head>
    <!-- Load the KeyLines file -->
    <script src="keylines.js" type="text/javascript"></script>

    <!-- Other libraries we want to use, e.g. jQuery -->
    <script src="jquery.js" type="text/javascript"></script>
</head>

<body>
    <!-- This is the HTML element that will be used to render the KeyLines component -->
    <div id="chartID" style="width: 400px; height: 300px;"></div>

    <!-- This is the actual code to load KeyLines in the page -->
    <script>
        // This will store a reference to our KeyLines chart object 
        var myChart;
        $(window).load(function() {
            // Load the component
            KeyLines.create("chartID", chartReady);
        });

        function chartReady(err, chart) {
          // Store a reference to the KeyLines chart object 
          myChart = chart;

          // Prepare the Cypher query
          var query = getMovieQuery("The Matrix");

          // Send the query to the REST endpoint
          sendQuery(query, function(json) {
            var items = makeKeyLinesItems(json);
            chart.load({
              type: "LinkChart",
              items: items
            }, layout);
          });
        }

        function getMovieQuery(name) {
          var template = 'MATCH (m:Movie{title: {name}})<-[r:ACTED_IN*]- (a:Person) RETURN *';

          // Use the new Neo4j transaction format 
          return {
            statements: [{
              statement: template,

              // Be safe and use params to avoid Cypher injections 
              parameters: {
                name: name
              },

              // Ask the result in the new graph format 
              resultDataContents: ['graph']
            }]
          };
        }
        //more goes here - see below
    </script>
</body>
</html>

Step 3: Send a query to Neo4j

Now we have a KeyLines chart, we need to raise AJAX Cypher queries to retrieve data from our Neo4j database. For our own convenience we can create a function to send AJAX requests to the cypher endpoint:

function sendQuery(query, callback) {

 // Replace dbUsername and dbPassword with your credentials
 $.ajax({
     type: 'POST',

     // This is the url of the cypher end point.
     url: 'http://localhost:7474/db/data/transaction/commit',

     // serialize the query object
     data: JSON.stringify(query),

     // Authenticate to the server
     headers: {
       Authorization: 'Basic ' + btoa('dbUsername:dbPassword')
     },
     dataType: 'json',
     contentType: 'application/json'
   })

   // Send the data to the callback when done
   .done(callback)
}

There are two things taking place in this query.

Firstly, sendQuery accepts a query parameter, which is the full Cypher query we want to run. Secondly, a callback function is called with a JSON response from our Neo4j Cypher endpoint.

Step 4: Convert to KeyLines JSON

Next we need to run a makeKeyLinesItems function to parse from Neo4j’s JSON format to KeyLines’ own format:

function makeKeyLinesItems(json) {
  var items = [];

  $.each(json.results[0].data, function(i, entry) {
    // Make nodes
    $.each(entry.graph.nodes, function(j, node) {
      var node = makeNode(node);
      items.push(node);
    });

    // Make links
    $.each(entry.graph.relationships, function(j, edge) {
      var link = makeLink(edge);
      items.push(link);
    });
  });

  return items;
}

function getType(labels) {
  // get only the first label
  return (labels[0] || '').toLowerCase();
}

function makeNode(item) {

  var baseType = getType(item.labels);
  var label = item.properties.title || item.properties.name;
  return {
    id: item.id,
    type: 'node',
    t: label,
    u: getNodeIcon(baseType), // get the icon based on the label
    ci: true,
    e: baseType === 'movie' ? 2 : 1,
    d: item
  };
}

function getNodeIcon(type) {
  // Be sure to have an '/images' to serve the right assets here 
  if (type === 'movie') {
    return 'images/icons/movie3.png';
  }
  return 'images/icons/person.png';
}

function makeLink(item) {
  // create a unique id
  var id = item.id + ':' + item.startNode + '-' + item.endNode;
  var labels = item.properties.roles;

  return {
    type: 'link',
    id1: item.startNode,
    id2: item.endNode,
    id: id,
    t: labels ? labels.join(' ') : '', // Use roles as label 
    fc: 'rgba(52,52,52,0.9)',
    a2: true, // draw an arrow pointing to the movie
    c: 'rgb(0,153,255)',
    w: 2,
    d: item
  };
}

Step 5: Run a graph layout

Now that the data has been parsed and loaded in KeyLines, we just need a layout. You can choose from the growing list of automatic layouts listed in the API.

In the current example we’re going to use the standard layout with a nice force-directed “spring” effect from the center of the canvas:

function layout() {
  // Place the new items at the center of the screen
  myChart.zoom('fit', {}, function() {
    // Now layout nicely
    myChart.layout();
  });
}

Step 6: Customize your chart

The final part of the process is to customize your chart’s appearance, workflow and functionality.

KeyLines offers a huge range of different ways to customize your final application – far too many to outline them here. Instead we recommend taking a detailed look through the KeyLines SDK documentation, especially the API reference and sample demos.

KeyLine
The KeyLines SDK site includes a KeyLines-Neo4j sample demo, with downloadable source code. Request a KeyLines trial account to get started.

Further resources

From the blog

Visualizing crime patterns data as a graph

In a previous post on law enforcement and data visualization, we saw how successful law enforcement agencies understand the wealth...

Hooking KeyLines up to the Neo4j Bolt Protocol

Neo4j 3.0 has many new features, and we’re particularly interested in the Bolt Protocol. Bolt promises to be a faster...

Visualizing Neo4j 2.2

Last week Neo Technologies announced the general release of v2.2 of the world’s most popular graph database. The culmination of...

Subscribe to our newsletter

Get occasional data visualization updates, stories and best practice tips by email