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 KeyLines & Neo4j integration 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 resources from the KeyLines SDK

Once you’re in the KeyLines SDK, take a few minutes to look around the site and check out the Demos tab. Here you’ll find a gallery of KeyLines examples to give you inspiration for your own applications:

KeyLines’ gallery of demos
A small selection of KeyLines’ 70+ interactive demos

The Integrate with Neo4j demo uses Cypher queries and KeyLines’ incremental layout to explore a Neo4j dataset of movies and actors (appropriately starting from The Matrix). To the right of the KeyLines chart, the handy panel contains details of the Cypher queries being raised, and some UI to run layouts from the KeyLines API.

The Neo4j integration demo from the KeyLines SDK
The Integrate with Neo4j demo from the KeyLines SDK

Now click the SDK’s Documentation tab. Once you’re comfortable with the information in the Basics section, head to the Third Party Integrations > Neo4j page. Here you’ll find a more advanced Neo4j third-party integration tutorial complete with example Neo4j source files. Download the Neo4j demo files and, if you haven’t downloaded it already, the latest version of KeyLines.

Finally, move the downloaded keylines.tgz file into the Neo4j folder. At the console, to add KeyLines as a package dependency, run:

npm add file:./keylines-X.XX.X-XXXXXXXXXX_dev.tgz

Step 2: Run the Neo4j demo locally

The downloaded Neo4j folder contains some important items:

  • 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
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
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, advanced filtering, and our ‘combos’ node combining functionality.

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.

A screen showing a graph visualization created using KeyLines
FREE: Start your KeyLines trial today

Visualize your data! Request full access to our KeyLines SDK, demos and live-coding playground.

TRY KEYLINES

How can we help you?

Request trial

Ready to start?

Request a free trial

Learn more

Want to learn more?

Read our white papers

“case

Looking for success stories?

Read our case studies

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 2022.
Read our Privacy Policy.