Grex

A JavaScript TinkerPop Rexster 2.x+ client for Node.js and the browser.

gRex helps you send Gremlin queries via HTTP to Rexster with the Gremlin extension enabled. The library supports script engine bindings and server-side scripts.

Learning Gremlin

Valuable source of information:

• GremlinDocs
• SQL2Gremlin
• Upcoming TinkerPop3 documentation
• The official Gremlin users mailing list.

Troubleshooting

Feel free to open issues if you have trouble using the library (bugs, feature requests).

General questions should be posted on StackOverflow with the javascript and gremlin tags.

Contributing

The master branch is a stable, release-only branch. Please checkout the develop branch for the latest changes. Pull requests are welcome and should be sent against develop.

• In case of bug fixes, please provide your pull requests with two commits: the first one with tests that show the problem being fixed (so people can checkout the commit and see what's wrong), and the last one with the actual fix.
• If you wish to send a pull request with a new feature, please open an issue first so we can discuss about it.

Testing

gRex is being developed with rexster-server-2.5.0. We use a slightly modified rexster.xml file located in conf/. Please follow the following steps to setup your test environment:

cd /path/to/rexster-server-2.5.0
ln -s /path/to/grex/conf/rexster-2.5.0.xml config/rexster-2.5.0-grex.xml
ln -s /path/to/grex/scripts scripts
bin/rexster.sh -s -c conf/rexster-2.5.0-grex.xml

This will start Rexster 2.5.0 with gRex test scripts folder loaded (required by tests).

Then run tests:

cd /path/to/grex
npm install
gulp test

Installation

gRex works in Node.js and the browser.

$ npm install grex --save

Quick start

Grex does three things:

• creates an HTTP client
• helps you generate a Gremlin queries (Groovy flavored)
• sends the query with any bound parameters for execution, retrieving the results (if any).

var grex = require('grex');
var client = grex.createClient();
// Init a couple shortcuts
var gremlin = grex.gremlin;
var g = grex.g;

// 1. Initialize a Gremlin object to work with
var query = gremlin(g.v(1)); // query.script === 'g.v(1)'

// 2. Send script for execution, and return a raw response object with a 'results' Array property.
client.execute(query, function(err, response) {
  // ...
})

Shorter version:

client.execute(g.v(1), function(err, response) {
  // ...
});

Documentation

A distinct GremlinScript object is created internally every time you call grex.gremlin(). Each GremlinScript instance is independant from the others and will be executed in a transaction, providing the exposed graph database you're using supports them.

In order to get an API closer to Groovy-flavored Gremlin, it is recommended that you add the following shortcuts on top of your JavaScript files:

var g = grex.g; // Graph getter
var _ = grex._; // Pipeline getter. Beware of conflicts and make sure you don't override libraries such as Underscore.js or Lodash.js

Building a Gremlin script

var query = gremlin(g.V('name', 'marko').out());
// query.script === "g.V('name','marko').out"

Building a multiline Gremlin script

Creating a GremlinScript with multiple statements is done by calling query() multiple times:

// JavaScript
var query = gremlin();
query(g.addVertex({ name: "Alice" }));
query(g.addVertex({ name: "Bob" }));
query(g.addVertex({ name: "Carol" }));
query(g.addVertex({ name: "Dave" }));

This will generate the following Groovy code, stored as a string in query.script:

// Groovy
g.addVertex(["name": "Alice"])
g.addVertex(["name": "Bob"])
g.addVertex(["name": "Carol"])
g.addVertex(["name": "Dave"])

Note that spaces are actually ommitted in the generated string. This documentation will display them in the following examples for clarity.

Building a multiline Gremlin script with JavaScript variables

The following is especially useful with transactions, for example when simultaneously creating vertices and edges.

Grex query function object returned by grex.gremlin() has a special .var(statement[, identifier]) method which helps you identify a statement and store it in a variable.

// JavaScript
var query = gremlin();
var bob = query.var(g.addVertex({ name: 'Bob' }));
var alice = query.var(g.addVertex({ name: 'Alice' }));
query(g.addEdge(bob, alice, 'likes', { since: 'now' }));

The above code will generate this Groovy script:

// Groovy
i0 = g.addVertex(["name": "Bob"])
i1 = g.addVertex(["name": "Alice"])
g.addEdge(i0, i1, "likes", ["since":"now"])

The Rexster Gremlin extension will execute the provided script in a transaction (see Rexster Wiki on extensions and transactions).

This API is required because JavaScript unfortunately lacks reflection on variable names.

Although identifiers are automatically assigned within the context of a script, you can add a second optional parameters to query.var() and pass an arbitrary string to use as the identifier:

// JavaScript
var query = gremlin();
var bob = query.var(g.addVertex({ name: 'Bob' }), 'v1');

Will generate:

// Groovy
v1 = g.addVertex(["name": "Bob"])

Bound parameters

Binding parameters can be done in several ways. This is recommended to use for performance and security reasons.

Explicit parameter binding

Grex provides a bindParameter function which returns an instance of BoundParameter. Such parameter is automatically attached as a binding.

var bind = grex.bindParameter;

var query = gremlin(g.addVertex(bind({ name: "Eve" })));
query.script.should.equal('g.addVertex(p0)\n');
query.params.p0.name.should.equal('Eve');

Building a Gremlin script with string formatting and bound parameters

Grex supports binding parameters when used with formatted strings. It internally uses Node.js util.format.

var query = gremlin();
query('g.v(%s)', 1);
// query.script === "g.v(p0)"
// query.params === { p0: 1 }

This will generate the following Gremlin script, with a gremlin.params = { p0: 1 } params map attached and sent to Rexster:

// Groovy
g.v(p0)

You can naturally pass multiple parameters:

var query = gremlin();
query("g.addVertex('name', %s, 'age', %s)", "Bob", 26);
// query.script === "g.addVertex('name', p0, 'age', p1)"
// query.params.p0 === 'Bob'
// query.params.p1 === '26'

Note that it is currently not possible to change the bound parameter naming mechanism, which defaults to p followed by an automatically incremented integer.

IMPORTANT: gRex helpers/wrapper classes currently do NOT send your script parameters as bound parameters to Rexster. You are currently vulnerable to Gremlin-"SQL-like"-injection if you use the helpers. For increased security, please use the string format API described in this sub-section only.

For example, the following is currently unsafe if you don't trust your data source. Make sure you sanitize your input.

// JavaScript
var query = gremlin(g.V('name', req.body.name));
client.execute(query, function(err, result) {
  //...
});

Multiline scripts combining Grex helpers and direct string formatting

You can combine both style in multiline scripts:

// JavaScript
var query = gremlin();
query('g.addVertex("name", %s)', 'Alice');
query(g.addVertex('name', 'Bob'))
// query.script === "g.addVertex('name', p0)\ng.addVertex('name','bob')\n"
// query.params.p0 === 'Alice'

Executing a Gremlin script

Executing

A Gremlin script will be sent to Rexster for execution when you call the client.execute() method.

The previous example can thus be executed the following way:

client.execute(query, function(err, response) {
  if(err) {
    console.error(err);
  }
  console.log(response.results);
});

Executing a one line script is trivial:

client.execute(gremlin(g.v(1)), function (e, response) { console.log(response) });

Automatic query creation for one line scripts

For single line scripts, gRex allows you to directly pass an instance of ObjectWrapper to client.execute() (and client.fetch()). These methods will internally create a 'GremlinScript' which will be executed right away.

client.fetch(g.V(), function (e, vertices) { console.log(vertices) });

Which is a shorthand for:

client.fetch(gremlin(g.V()), function (e, vertices) { console.log(vertices) });

You can also pass a raw String.

client.fetch('g.V()', function (e, vertices) { console.log(vertices) });

Fetching

Grex establishes a slight difference between executing and fetching.

While client.execute() returns a raw Rexster response object, client.fetch() directly returns the results part of the response object, allowing you to directly manipulate objects in your scripts without having to call response.results.

var query = g.V('type', 'user');
client.fetch(query, function(err, results) {
  if(err) {
    console.error(err);
  }
  console.log(results);
  var user = new UserModel(results[0]);
});

When creating your client with grex.createClient(options), it is also possible to define your own custom function in options.fetched in order to change the behavior of client.fetch(). This is useful if you wish to automatically instantiate returned graph Elements with custom classes of your own. The default handlers in gRex only returns the results part of the response, making client.fetch() a very close cousin of client.execute().

Fetching a single result from the graph

If you know in advance that a given query should return no more than one result, gRex provides a convenient client.fetchOne() method that retrieves the first element of the results array returned by Rexster.

client.fetchOne(g.v(6), function(err, vertex) {
  var user = new UserModel(vertex);
});

However, be aware that fetchOne() will NOT prevent Rexster from sending a lot of data; make sure your Gremlin query is restrictive enough to limit the number of results returned.

Returning a stream of results

var s = client.stream(g.V());

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

This will return a stream of objects which can be pipe'd into any Node.js transform streams.

Executing a stored, server-side script

Please refer to Rexster documentation for help on setting up server-side scripts.

var client = grex.createClient({
  load: ['vertices'] // Load vertices.gremlin, server-side
});

// Assumes vertices.gremlin contains an allVertices function
client.execute(gremlin('allVertices()'), function(err, results) {
  should.not.exist(err);
  should.exist(results);
  done();
});

Accessing the internal GremlinScript instance of a query

Calling query() returns the internal instance of GremlinScript:

var query = gremlin(g.V('name', 'marko').out());

console.log(query().constructor.name); // GremlinScript
// query().script === "g.V('name','marko').out"

Calling query() is especially useful if you wish to gain direct access to the lower level/private methods of the GremlinScript class. Unless debugging or trying to gain direct access to the raw script string, you shouldn't need to do this.

This allows you to directly set the GremlinScript.script property with an arbitrary string of Gremlin/Groovy (for example, the content of a .groovy file). You can also set the GremlinScript.params map and manually attach custom bound parameters to your script.

API differences between Gremlin Groovy and gRex JavaScript

Grex tries to implement Gremlin (Groovy flavored) syntax as closely as possible. However, there are some notable differences.

All JavaScript method calls require parentheses (), even if there are no arguments. Using JavaScript getters could mimic the API The generated Groovy code will also use parentheses (see Method Notation vs. Property Notation).

Here are several examples which illustrate the differences between Gremlin Groovy and gRex JavaScript. Note that Groovy generated strings are displayed first in the following examples.

Support for multiple arguments or Object argument

// Groovy
g.V('name', 'marko').out

// JavaScript
g.V('name', 'marko').out();
g.V({ name: 'marko' }).out();

Support for multiple arguments or Array argument

// Groovy
g.v(1, 4).out('knows', 'created').in

// JavaScript
g.v(1, 4).out('knows', 'created').in();
g.v([1, 4]).out(['knows', 'created']).in();

Array indexes

// Groovy
g.V[0].name

// JavaScript
g.V().index(0).property('name');

Array ranges

// Groovy
g.V[0..<2].name

/// JavaScript
g.V().range('0..<2').property('name');

Comparison tokens

You may pass comparison tokens as strings or as appropriate JavaScript objects which grex directly exposes.

// Groovy
g.E.has('weight', T.gt, 0.5f).outV.transform{[it.id,it.age]}

// JavaScript
g.E().has('weight', 'T.gt', '0.5f').outV().transform('{[it.id,it.age]}');

// alternatively
var T = grex.T;
g.E().has('weight', T.gt, '0.5f').outV().transform('{[it.id,it.age]}');

Passing of pipelines

Make sure you declare the following on top of your script:

var _ = grex._;
// Beware of conflicts and make sure you don't override Underscore.js or Lodash.js

This allows you to call the _() function directly, leaving no differences with a Groovy environment:

// Groovy
g.V.and(_().both("knows"), _().both("created"))

// JavaScript
g.V().and(_().both("knows"), _().both("created"))

// Groovy
g.v(1).outE.or(_().has('id', T.eq, "9"), _().has('weight', T.lt, 0.6f))

// JavaScript
g.v(1).outE().or(_().has('id', 'T.eq', 9), _().has('weight', 'T.lt', '0.6f'));

// Groovy
g.V.retain([g.v(1), g.v(2), g.v(3)])

// JavaScript
g.V().retain([g.v(1), g.v(2), g.v(3)])

Closures

Closures currently need to be passed in as a string argument to methods. Though not trivial to implement, this will likely change in the future (see issue#22). It could also be supported with a different API or maybe using ES6 Proxies. Suggestions welcomed!

// Groovy
g.v(1).out.gather{it.size()}

g.v(1).out.ifThenElse{it.name=='josh'}{it.age}{it.name}

g.V.out.groupBy{it.name}{it.in}{it.unique().findAll{i -> i.age > 30}.name}.cap

// JavaScript
g.v(1).out().gather("{it.size()}");

g.v(1).out().ifThenElse("{it.name=='josh'}{it.age}{it.name}");

g.V().out().groupBy('{it.name}{it.in}{it.unique().findAll{i -> i.age > 30}.name}').cap()

Java classes

Java classes are currently passed in either as strings or as JavaScript objects.

// Groovy
g.createIndex("my-index", Vertex.class)

// JavaScript
g.createIndex("my-index", "Vertex.class");

// alternatively
var Vertex = grex.Vertex;
g.createIndex("my-index", Vertex);

Passing classes as strings might be deprecated in future versions.

Retrieving indexed Elements

// Groovy
g.idx("my-index")[[name:"marko"]]

// JavaScript
g.idx("my-index", {name:"marko"});

This may change once ES6 Proxies are out.

Other notable differences

• Comparators and Float's are not native javascript Types so they currently need to be passed in as a string to Grex methods. Floats need to be suffixed with a 'f'. This will probably change in future versions of Grex.

  g.v(1).outE().has("weight", "T.gte", "0.5f").property("weight")

• Certain methods cannot (yet) be easily implemented. Such as aggregate, store, table, tree and fill. These methods require a local object to populate with data, which cannot be easily done in this environment. You may however directly pass an arbitrary string to query() to bypass this limitation.

• Tokens/Classes: You will notice that in the examples tokens are passed as string (i.e. 'T.gt'). However, Grex also exposes some objects for convenience that you can use in place of string representations in your queries. To access the objects, reference them like so:

    var T = grex.T;
    var Contains = grex.Contains;
    var Vertex = grex.Vertex;
    var Edge = grex.Edge;
    // etc.
    // Most tokens/classes are exposed. Feel free to open an issue if some are missing.

API documentation

Grex

When starting with gRex and/or Gremlin, it is recommended that you use the proxied getters/wrappers.

grex.createClient()

Instantiate a Rexster client.

Options:

• host - default: localhost
• port - default: 8182
• graph - default: tinkergraph
• load - an Array of server-side scripts to load
• showTypes - whether results should be returned with types (default: false)
• fetched - a function to apply, modifying the behavior of client.fetch

grex.gremlin

A getter returning a function.

Doing grex.gremlin will instantiate a new GremlinScript instance and return a function responsible for appending bits of Gremlin-Groovy scripts to the instance.

A getter which returns a function responsible for creating a new GremlinScript instance.

var grex = require('grex');
var g = grex.g;
var gremlin = grex.gremlin;

// Create two distinct GremlinScript instances
var queryA = gremlin();
var queryB = gremlin();

queryA(g.addVertex());
queryB(g.v(40));
queryA(g.v(1));

// queryA.script === 'g.addVertex()\ng.v(1)\n'
// queryB.script === 'g.v(40)\n'

grex.g

A getter returning a new Graph() wrapper instance.

Graph methods return convenient wrapper objects, which is either:

• a new PipelineWrapper instance which you get when calling g.v(), g.V(), g.E(), etc.)
• a new VertexWrapper via g.addVertex() or new EdgeWrapper instance via g.addEdge(). Note that both classes inherits from ElementWrapper. They all inherits from ObjectWrapper.

grex._

A getter returning a new Pipeline() wrapper instance.

grex.bindParameter(value)

Returns an instance of BoundParameter for the given value.

Client

For all four query methods, bindings are optional.

client.execute(gremlin, bindings, callback)

Callback signature: (err, response)

• err object
• raw Rexster response object

client.fetch(gremlin, bindings, callback)

Callback signature: (err, results, response)

• err object
• results array (shortcut for response.results)
• raw Rexster response object

client.fetchOne(gremlin, bindings, callback)

Callback signature: (err, result)

• err object
• the first element of the raw response.results array
• raw Rexster response object

client.stream(gremlin, bindings)

Returns a Stream of objects which can be pipe'd into any Node.js transform stream.

Todo

• bound arguments on helpers/wrappers (for security and better performance on the server)
• closure as JavaScript functions
• simplified API (remove gremlin.g and gremlin._, remove Java .class, etc.)
• Rexpro?
• performance checks and improvements

Author

Jean-Baptiste Musso - @jbmusso.

Based on the work started by Frank Panetta - @entrendipity.

Contributors

https://github.com/gulthor/grex/graphs/contributors

License

MIT (c) 2013-2014 Jean-Baptiste Musso, Entrendipity Pty Ltd.