Visualizing Graphs with TinkerPop3: A Migration Guide

Migrating From TinkerPop 2.x to TinkerPop 3.x

The graph ecosystem is constantly evolving, with new and more powerful technologies powering a rapidly expanding ecosystem.

One of the creative and technical drivers behind this evolution is TinkerPop: a collection of collaborators and projects ‘committed to the art of graph computing’. In just a few years, TinkerPop has produced some of the domain’s most recognizable open source ventures, including the BluePrints graph API, the Gremlin graph query language, the Rexster graph server, to name just three.

Introducing TinkerPop3

In early 2016, TinkerPop3 emerged from the Apache Incubator. This version pulled together the (occasionally disparate) collection of projects in TinkerPop 2.x, producing a single ecosystem with the Gremlin query language at its heart.

It was a huge step up from the previous incarnations, providing a near-complete base infrastructure for graph computing, without vendor lock-in. The TinkerPop framework provides an agnostic interface to any graph database for high-efficiency graph computation queries (called “traversals”) and analytics:

It was also brought some big changes for KeyLines developers using components of TinkerPop.

Change 1: The Gremlin Language

One of the biggest changes was to make the Gremlin, TinkerPop’s expressive query language, a first class citizen of the project. This means that all documentation is now integrated with Gremlin, and traversal steps are now found on the official TinkerPop site.

A couple of other things to bear in mind, include:

• Gremlin-Groovy is the default flavor in TinkerPop3. This is different to the Java getters/setters approach of TinkerPop2.
• There are many variants of Gremlin, so test all queries against your specific database implementation.

Change 2: The Rexster server interface

What used to be Rexster, the exposed graph server REST API, is now the Gremlin Server.

While Rexster offered a full REST API with an additional Gremlin query endpoint, with the Gremlin Server, the authors decided to focus on a better approach to handle high-performance queries. The Gremlin Server will, by default, stream the results using WebSockets as a transportation channel to serve the data: this lets the database process and serialize only small amounts of data each cycle using less memory and making it easier to scale.

A recommended alternative path to follow when migrating from Tinkerpop 2.x Rexster is to use an HTTP interface with a Gremlin query endpoint.

How to migrate your KeyLines application to TinkerPop3

1. Change your Gremlin query endpoint:

Using an HTTP interface with a Gremlin query endpoint means you, the KeyLines developer, just need to tweak your code to use the Gremlin query endpoint.

Here’s the relevant snippet of code:

async function gremlinQuery(query, params) {
  const queryObj = {
    gremlin: query,
    bindings: params
  };
  const resp = await fetch("http://localhost:8182", { method: 'POST', body: queryObj });
  const json = await resp.json();
  return json;
}

json = await gremlinQuery("g.V().has('name', name)", {name: 'Joe'})
// Print the result here
console.log(json);
// Create the KeyLines items from the json
...

2. Find the right Gremlin server driver

As I mentioned above, the Gremlin server uses the WebSocket channel by default. This makes it super useful for real-time or data streaming scenarios but as it has a custom sub-protocol, it is unlikely to work in its ‘vanilla’ state.

Happily, there are already drivers for many different languages, so find the right one for you.

For Javascript and NodeJS there’s a client library which uses new ES2015/ES6 features such as Promises (better flow control) and template strings (for easier-to-read Gremlin query generation) called gremlin-javascript.

In order to use the gremlin-javascript library in the browser, be sure to follow their instructions first, then include the resulting gremlin.js file in the HTML page:

<script src="js/keylines.js" type="text/javascript"></script>
<!-- Put the gremlin.js file here just before your app code -->
<script src="js/gremlin.js" type="text/javascript"></script>
<script src="js/app.js" type="text/javascript"></script>

In the app connect to the Gremlin Server first, then use a function to send the queries:

// at the beginning of your app kick off the WebSocket channel
const client = gremlin.createClient();

function gremlinQuery(query, params) {
 return new Promise((resolve, reject) => {
   client.execute(query, params, (err, results) => {
     if (err) {
       return reject(err);
     }
     return resolve(results);
   })
 });
}

items = await gremlinQuery("g.V().has('name', name)", {name: 'Joe'})
// Print the result here
console.log(items);
// Create the KeyLines items from the returned items
...

It’s that simple!

With two code changes, your KeyLines application should be fully compatible with TinkerPop3.

Using TinkerPop3 with the Titan Graph Database?

Our updated getting started guide provides step-by-step instructions on building graph visualization and exploration applications for your Titan 1.X graph database.

View the guide

Apache TinkerPop and Apache TinkerPop Gremlin logos are trademarks of The Apache Software Foundation.