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 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 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>
    <!-- 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>

    <!-- 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 -->
        // 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);
              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

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
     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

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);

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

  return items;

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

function makeNode(item) {

  var baseType = getType(item.labels);
  var label = ||;
  return {
    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.startNode + '-' + item.endNode;
  var labels =;

  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

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 here. We recommend taking a detailed look through the KeyLines SDK documentation, especially the API reference and sample demos.

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

Solving distributed graph problems with DataStax

We caught up with Denise Gosnell, Senior Manager and Head of Global Graph Practice at DataStax, to talk about graph challenges, graph visualization, and what the future holds.

A night at the Oscars with KeyLines and Stardog

This blog post shows how quick and easy it is to integrate Stardog with KeyLines using Academy Awards data.

Visualizing TED Talks data with Memgraph

Find out how to integrate the KeyLines graph visualization toolkit with the Memgraph database, our latest technology alliance partner.

Visit the blog