gremlin-client

gremlin-client

A proof of concept WebSocket JavaScript client for TinkerPop3 Gremlin Server.

Tested with Node.js v0.10.29 and v0.11.13. Tested with Chrome 35, Firefox 28, Safari 7.

Installation

Gremlin Client is an AMD/CommonJS module that works in both Node.js and WebSocket enabled browsers.

npm install gremlin-client --save

In the browser, you can require the module with browserify or directly insert a <script> tag, which will expose a global gremlin variable:

<script type="text/javascript" src="gremlin.js"></script>

Usage

Set-up client

// Will open a WebSocket to ws://localhost:8182 by default
var client = gremlin.createClient();

same as:

var client = gremlin.createClient(8182, 'localhost');

If you want to use Gremlin-Server sessions, you can set the session argument as true in the options object:

var client = gremlin.createClient(8182, 'localhost', { session: true });

The client supports two modes: streaming results, or traditional callback mode.

Stream mode: client.stream(script)

Return a Node.js stream which emits a data event with the raw data returned by Gremlin Server every time it receives a message. The stream simultaneously also emits a higher level result event.

The stream emits an end event when receiving the last, type: 0 message.

var query = client.stream('g.V()');

query.on('result', function(result) {
  console.log(result);
});

// Alternatively:
// query.on('data', function(message) {
//   console.log(message.result);
// });

query.on('end', function(msg) {
  console.log("All results fetched", msg);
});

Callback mode: client.execute(script, callback)

Will execute the provided callback when all results are actually returned from the server. Until it receives the final type: 0 message, the client will internally concatenate all partial results returned over different messages.

Using Gremlin-JavaScript syntax with Nashorn

Providing your configured nashorn script engine in your gremlin-server.yaml file, you can send and execute Gremlin-JavaScript formatted queries:

scriptEngines: {
  gremlin-groovy: {
    imports: [java.lang.Math, org.apache.commons.math3.util.FastMath],
    staticImports: [java.lang.Math.PI],
    scripts: [scripts/generate-classic.groovy]},
  nashorn: {
      imports: [java.lang.Math, org.apache.commons.math3.util.FastMath],
      staticImports: [java.lang.Math.PI]}}

Then, in your Node.js/Browser environment:

var client = gremlin.createClient({ language: 'nashorn' });

// Wrap a script definition in a JavaScript function
var script = function() {
  // Retrieve all vertices ordered by name
  g.V().order(function(a, b) {
    return a.get().value('name').localeCompare(b.get().value('name')); // JavaScript replacement for <=> spaceship operator
  });
};

// Send that script function body to Gremlin Server for execution in Nashorn engine
client.execute(script, function(err, response) {
  // Handle response.results
});

The client gets a string representation of the function passed to client.stream() or client.query() by calling the .toString() method.

Bound parameters

The following example shows how to send a Gremlin-Javascript formatted script to Gremlin Server with bound parameters using the stream API:

var s = client.stream(function() { g.v(id); }, { id: 1 });

s.on('data', function(result) {
  // handle result
});

Running the Examples

This section assumes that you configured resultIterationBatchSize: 1 in your Gremlin Server .yaml config file and loaded the default TinkerPop graph with scripts: [scripts/generate-classic.groovy]

To run the command line example:

cd examples
node node-example

To run the browser example:

cd examples
node server

then open http://localhost:3000/examples/gremlin.html for a demonstration on how a list of 6 vertices is being populated as the vertices are being streamed down from Gremlin Server.

Features

• commands issued before the WebSocket is opened are queued and sent when it's ready.

To do list

• handle any errors
• reconnect WebSocket if connection is lost
• support .execute() with promise
• secure WebSocket
• tests
• performance optimization