grex

gRex

Gremlin inspired Rexster Graph Server client for NodeJS and the browser.

Dependancies

batch kibble (Rexster extension)

Move the batch-kibble-XXX.jar, located in the modules lib folder, to the /ext folder under the rexster server directory. Add an allow tag to the database extensions configuration in the rexster.xml file.

<extensions>
    <allows>
        <allow>tp:gremlin</allow>
        <allow>tp:batch</allow>
    </allows>
</extensions>

Q

A tool for making and composing asynchronous promises in JavaScript.

Installation

gRex can be loaded as:

• a <script> tag in the browser (creating a g global variable)

   <script type="text/javascript" src="q.min.js"></script>    
   <script type="text/javascript" src="grex-client.js"></script>
  

• a Node.js and CommonJS module available from NPM as the grex package

  $ npm install grex
  

  then in node

  var g = require(“grex”);
  

• a RequireJS module

Introduction

gRex tries to implement Gremlin syntax as closely as possible. However, there are some differences.

• All method calls require brackets (), even if there are no arguments.

• Closures do not translate to javascript. Closures need to passed in as one string argument to gRex methods.

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

• Comparators and Float's are not native javascript Types so need to be passed in as a string to gRex methods. Floats need to be suffixed with a 'f'.

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

• Certain methods cannot be implemented. Such as aggregate, store, table, tree and fill. These methods take a local object and populate it with data, which cannot be done in this environment.

Getting Started

###Options

Options specify the location and name of the database.

####host (default: localhost)

Location of Rexster server

####port (default: 8182)

Rexster server port

####graph (default: tinkergraph)

Graph database name

####idRegex (default: false)

This can remain as false, if IDs are number. If IDs are not numbers (i.e. alpha-numeric or string), but still pass parseFloat() test, then idRegex must be set. This property will enable gRex to distinguish between an ID and a float expression.

g.setOptions({ host: 'myDomain', graph: 'myOrientdb', idRegex: /^[0-9]+:[0-9]+$/ });

Examples

A good resource to understand the Gremlin API is GremlinDocs. Below are examples of gremlin and it's equivalent gRex syntax.

N.B.: gRex uses the Q module to return a Promise when making Ajax calls. All requests are invoked with get() and the callback is captured by then(result, error);. However, this is not the case when performing Create, Update and Deletes of Vertices or Edges. These actions are batched to reduce the number of calls to the server. In order to send these type of requests invok g.commit().then(result, error); after making your updates to the data.

All calls are invoked with get().

g.V('name', 'marko').out().get().then(function(result){console.log(result)}, function(err){console.log(err)});

g.createIndex('my-index', 'Vertex.class').get().then(function(result){console.log(result)}, function(err){console.log(err)});

Except when creating, updating or deleting Vetices or Edges. Use g.commit() to commit all changes.

gRex>     g.addVertex(100, {k1:'v1', 'k2':'v2', k3:'v3'});

gRex>     g.addVertex(200, {k1:'v1', 'k2':'v2', k3:'v3'});

gRex>     g.addEdge(300,100,200,'pal',{weight:'0.75f'})

gRex>     g.updateVertex(100, {k2: 'v4'});

gRex>     g.removeVertex(100, ['k2', 'k3']);

gRex>     g.removeVertex(200);

gRex>     g.commit().then(function(result){console.log(result)}, function(err){console.log(err)});

For simplicity the callbacks are not included in the examples below.

Example 1: Basic Transforms

gremlin>  g.V('name', 'marko').out

gRex>     g.V('name', 'marko').out();

gRex>     g.V({name: 'marko'}).out();

gremlin>  g.v(1, 4).out('knows', 'created').in

gRex>     g.v(1, 4).out('knows', 'created').in();

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

Example 2: [i]

gremlin>  g.V[0].name

gRex>     g.V().index(0).property('name');

Example 3: [i..j]

gremlin>  g.V[0..<2].name

gRex>     g.V().range('0..<2').property('name');

Example 4: has

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

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

Example 5: and & or

gremlin>  g.V.and(_().both("knows"), _().both("created"))

gRex>     g.V().and(g._().both("knows"), g._().both("created"))

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

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

Example 6: groupBy

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

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

Example 7: retain

gremlin>  g.V.retain([g.v(1), g.v(2), g.v(3)])

gRex>     g.V().retain([g.v(1), g.v(2), g.v(3)])

Example 8: Create index

gremlin>  g.createIndex("my-index", Vertex.class)

gRex>     g.createIndex("my-index", "Vertex.class")

Example 9: Add to index

gremlin>  g.idx("my-index").put("name", "marko", g.v(1))

gRex>     g.idx("my-index").put("name", "marko", g.v(1))

Example 10: Retrieving indexed Element

gremlin>  g.idx("my-index")[[name:"marko"]]  

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

Example 11: Drop index

gremlin>  g.dropIndex("my-index", Vertex.class)

gRex>     g.dropIndex("my-index", "Vertex.class")

Example 12: Create, Update, Delete - use g.commit()

gRex>     g.addVertex(100, {k1:'v1', 'k2':'v2', k3:'v3'});

gRex>     g.addVertex(200, {k1:'v1', 'k2':'v2', k3:'v3'});

gRex>     g.addEdge(300,100,200,'pal',{weight:'0.75f'})

gRex>     g.updateVertex(100, {k2: 'v4'});

gRex>     g.removeVertex(100, ['k2', 'k3']);

gRex>     g.removeVertex(200);

gRex>     g.commit()

Author

Frank Panetta - Follow @entrendipity

##License ###The MIT License (MIT)

Copyright (c) 2013 entrendipity pty ltd

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.