Hands-on graph visualization: KeyLines & Neo4j

At Cambridge Intelligence, we make KeyLines – a JavaScript SDK for interactive graph visualization. It’s ideal for hands-on Neo4j developers, offering the same power, scalability and flexibility for which the world’s most popular graph database has become known.

A KeyLines visualization, using the ‘combos’ node grouping functionality
A KeyLines visualization, using the ‘combos’ node grouping functionality

Since 2012, hundreds of developers have used KeyLines to build visualization web applications for Neo4j. As a result, we’ve honed our integration code, documentation, and support to make the process as simple as possible.

Build from scratch or use a template

As KeyLines is an SDK, there are limitless ways to customize your application. You have complete control over every aspect – UI, UX, functionality, visual appearance and branding. The most common approach is to use KeyLines’ API to harness functionality like the time bar, combos, SNA, and geospatial visualization. For that, more advanced JavaScript developers can follow our Neo4j tutorial.

In this post we’ll describe the quickest and easiest way to get started, using one of our Neo4j demos to kick-start the process. With this approach, we’ll use KeyLines’ Cypher integration and a one-to-one mapping between Neo4j and the chart, so switching the schema and producing your own visualization is fast and simple. Let’s begin.

A few prerequisites…

To follow this tutorial, you’ll need:

  • a KeyLines SDK login (Not using KeyLines yet? Request a free trial)
  • a Neo4j instance, loaded with some data
  • basic knowledge of JavaScript and web applications

The visualization architecture

The KeyLines-Neo4j architecture is simple but secure and flexible enough to work in any setup:

The standard KeyLines / Neo4j visualization architecture
The standard KeyLines / Neo4j visualization architecture

KeyLines itself is a JavaScript file, deployed to a web server. The KeyLines chart is then embedded as an HTML element somewhere within your application (or as a standalone component) which allows the user to interact with and explore, the graph.

Graphics rendering is powered by HTML5 Canvas or WebGL – KeyLines will switch between the two depending on the browser – so it performs well even with larger graphs. Also, everything stays inside your corporate firewall so data security shouldn’t be an issue.

Step 1: Download our Neo4j demo

Once you’re in the KeyLines SDK, take a few minutes to look around the site and review the documentation. The ‘Basics’ section of the Documentation tab is the best place to start.

Next, head to the Demos tab. Here you’ll find a gallery of KeyLines apps, ready to download and start customizing:

KeyLines’ gallery of demos
KeyLines’ gallery of demos

There are a few different Neo4j demos, but ‘Integrate with Neo4j’ is the most straightforward. It uses Cypher queries and KeyLines’ incremental layout to explore a Neo4j dataset of movies and actors (appropriately starting from The Matrix).

Exploring movie data with KeyLines, Neo4j and Cypher

To the right of the demo KeyLines chart we’ve included an information box, containing the Cypher queries being raised, and some UI to run layouts from the KeyLines API.

From the demo page, click ‘Download’.

Ready to start visualizing your Neo4j data?
Request a free trial

Step 2: Run the Neo4j demo locally

The demo will download as a Zip folder. Inside you’ll find the following files:

KeyLines – Neo4j demo folder structure

You don’t need to know what each of these files does, but there are a few important ones:

  • css (as you’d expect) contains the different CSS files for the rest of your webpage. You can use ours, or write your own.
  • images contains the image files for nodes, glyphs, etc.
  • neo4j-data contains the files used to import the demo database
  • neo4j-db.js is the database driver, including Cypher integration and JSON parsing code.
  • neo4j-router.js controls the authentication parameters used.
  • neo4j.js adds KeyLines functionality, as well as tying some of that functionality to general UI (e.g. run a layout when the user clicks on this button).

To get the Neo4j demo running locally, open ‘index.htm‘ in your preferred browser. You should see something like this:

A blank KeyLines chart, waiting for data from a Neo4j instance

At this point, the demo is running from our local filesystem. The chart is blank because we haven’t connected it to our database yet.

Step 3: Point the demo at your Neo4j database

In your ‘demo’ folder, find the neo4j-db.js file and add your instance login credentials to the following:

 headers: {
   Authorization: 'Basic '+btoa('username:password')

Obviously, this approach is only recommended during KeyLines prototyping. When you deploy your app in production, you’ll run Neo4j on a secure web server and only expose certain endpoints to KeyLines.

Using Bolt?

In this example, we’ve assumed you’re using Neo4j’s REST API to send queries back and forth. If you’re using Neo4j’s Bolt protocol, you’ll need to make some adjustments to the KeyLines demo at this stage:

  1. Set up the JavaScript Bolt library – either in your browser (using the browser version of the Neo4j driver) or on your server (for example by requiring Neo4j-driver in Node)
  2. Set up the driver – by adding your credentials and creating sessions to run KeyLines’ Cypher queries
  3. Process the Bolt response into KeyLines JSON – in a single loop you can: a) convert the node IDs, b) do the same for link/edge start and endpoints, c) convert other numeric properties.

More detailed instructions can be found in our blog post on Hooking KeyLines up to the Neo4j Bolt Protocol.

Step 4: Update the schema

Next you need to map your Neo4j data to the KeyLines schema, and choose the visual model you want to use.

This stage can be as simple or as complex as you like, but our Neo4j demo uses one-to-one mapping between the chart and database, and follows a typical user workflow (expand and explore). For most developers, a few simple ‘find and replace’ commands should do the trick.

For example, open neo4j-db.js, find ‘e: item.d.type === ‘movie’ ? 1.7 : 2.5’, which enlarges movie nodes in our demo, and replace movie with whichever node type from your schema you want represented as a larger size.

You’ll also need to adjust the Cypher queries in-line with your own schema. That’s in the queryTemplates object in neo4j-db.js.

Finally, you can also change node and link styles at this stage, for example by finding the ‘dbDemoTheme’ object in neo4j.js and changing the font icons by editing the ‘fi’ property.

Step 5: Run the Neo4j demo

The final step is to start your database and load KeyLines. If you’re using Node, that’s a simple `npm install` followed by `npm start` in the root folder.

Now navigate to http://localhost:8080 to find your interactive KeyLines – Neo4j demo:

Our populated KeyLines chart

Optional step 6: incorporate advanced functionality

By now, you’ll have a simple demo, running from your database with your own visual styling. It’s a great starting point for you to visually explore and understand your Neo4j data.

But if you want to take your insight a step further, the KeyLines API offers a huge library of advanced graph analysis and visualization functionality. With a few lines of JavaScript code (take a look at our 80+ demos for inspiration) you can incorporate graph layouts, SNA centrality measures, filtering, and our advanced ‘combos’ functionality.

There are also Neo4j-specific blog posts that’ll help you to visualize time series data and understand the value of geospatial graph visualization.

Try it for yourself

This tutorial is just the starting point. KeyLines and Neo4j are a powerful combination, and make it easy for you to build custom, flexible and high-performance graph exploration tools.

Request a free trial, or contact us for more information.

More from our blog

Visit our blog

Registered in England and Wales with Company Number 07625370 | VAT Number 113 1740 61 | 6-8 Hills Road, Cambridge, CB2 1JP. All material © Cambridge Intelligence 2020.