cypher-gremlin-server-plugin

Gremlin Server Cypher Plugin

Included in the plugin:

• OpProcessor implementation for Gremlin Server that translates Cypher queries to GraphTraversal
• Gremlin Extensions for Cypher for Gremlin in the form of custom functions and predicates

Installation

The plugin and its dependencies can be automatically downloaded and installed into the Gremlin Server by using bin/gremlin-server.sh install. You can also manually "install" the plugin by copying jar file into the server classpath.

Cypher for Gremlin could be installed on any TinkerPop server with ability to install Gremlin Server plugins. Latest version of Cypher for Gremlin has dependencies on TinkerPop 3.4.2 and Scala 2.12, so for legacy implementations please use previous releases. For more information about compatibility with different Gremlin implementation refer to documentation.

$VERSION depends on target implementation:

Gremlin Server	Cypher for Gremlin
TinkerPop 3.4.x	1.0.4 (latest)
TinkerPop 3.3.x	0.9.13
JanusGraph 0.4.x (Scala 2.12)	1.0.4 (latest)
JanusGraph 0.4.x	1.0.0
JanusGraph 0.3.x	0.9.13
JanusGraph 0.2.x	Not compatible

Automated Installation

Run bin/gremlin-server.sh with install switch and supply the Maven coordinates of the plugin:

bin/gremlin-server.sh install org.opencypher.gremlin cypher-gremlin-server-plugin $VERSION
Installing dependency org.opencypher.gremlin cypher-gremlin-server-plugin $VERSION
...

⚠ If you got error about Custom functions and predicates are not supported on target implementation, follow steps 3-5 of manual instalation.

Manual Installation

Run the following commands from project root.

1. Download compatible release or build the plugin JAR file:

   ./gradlew :tinkerpop:cypher-gremlin-server-plugin:shadowJar

2. Copy plugin JAR file to Gremlin Server lib/ directory:

   cp tinkerpop/cypher-gremlin-server-plugin/build/libs/cypher-gremlin-server-plugin-*-all.jar /path/to/gremlin-server/lib/

3. Register the org.opencypher.gremlin.server.op.cypher.CypherOpProcessor.
4. Add ['org.opencypher.gremlin.process.traversal.CustomPredicates.*','org.opencypher.gremlin.traversal.CustomFunctions.*'] to Gremlin Server configuration file at scriptEngines/gremlin-groovy/staticImports.
5. Add class and method imports for org.apache.tinkerpop.gremlin.jsr223.ImportGremlinPlugin. Example

    scriptEngines:
      gremlin-groovy:
        plugins:
          # ...
          org.apache.tinkerpop.gremlin.jsr223.ImportGremlinPlugin:
            classImports:
              - java.lang.Math
              - org.opencypher.gremlin.traversal.CustomFunctions
              - org.opencypher.gremlin.traversal.CustomPredicate
            methodImports:
              - java.lang.Math#*
              - org.opencypher.gremlin.traversal.CustomPredicate#*
              - org.opencypher.gremlin.traversal.CustomFunctions#*
          # ...

6. Restart Gremlin Server.
7. If the plugin has been installed correctly, you should see the following line among the logs:

   [INFO] OpLoader - Adding the cypher OpProcessor.
   

Usage

Gremlin-Java/Gremlin-Groovy

Recommended way is to use Cypher Client for Gremlin Server, however it is possible to send Cypher using Gremlin Client by creating custom RequestMessage:

Cluster cluster = Cluster.open(configuration);
Client client = cluster.connect();

String cypherQuery = "MATCH (n) RETURN n.name";
RequestMessage request = RequestMessage.build(Tokens.OPS_EVAL)
    .processor("cypher")
    .add(Tokens.ARGS_GREMLIN, cypherQuery)
    .create();

ResultSet results = client.submitAsync(request).get();

Gremlin-Javascript

Example connect using Gremlin-JavaScript 3.4.2+ by setting processor to cypher:

// npm install [email protected]

const gremlin = require('gremlin');
const client = new gremlin.driver.Client('ws://localhost:8182/gremlin', { traversalSource: 'g', processor: 'cypher'});
const cypherQuery = 'MATCH (n) RETURN n.name'

const results = await client.submit(cypherQuery);

for (const result of results) {
  console.log(result);
}

Gremlin-Python

Example connect using Gremlin-Python by creating custom RequestMessage:

from gremlin_python.driver.client import Client
from gremlin_python.driver.request import RequestMessage
from gremlin_python.driver.serializer import GraphSONMessageSerializer

serializer = GraphSONMessageSerializer()
# workaround to avoid exception on any opProcessor other than `standard` or `traversal`:
serializer.cypher = serializer.standard

client = Client('ws://localhost:8182/gremlin', 'g', message_serializer=serializer)

cypherQuery = 'MATCH (n) RETURN n.name'
message = RequestMessage('cypher', 'eval', {'gremlin': cypherQuery})
results = client.submit(message).all().result()

Gremlin.Net

Example connect using Gremlin.Net by creating custom RequestMessage:

var client = new GremlinClient(new GremlinServer("localhost", 8182));
var cypherQuery = "MATCH (n) RETURN n.name";
var requestMessage = RequestMessage.Build(Tokens.OpsEval)
                .AddArgument(Tokens.ArgsGremlin, cypherQuery)
                .Processor("cypher")
                .Create();
var result = await client.SubmitAsync<Dictionary<object, object>>(requestMessage);

Configuration

In most of the cases, the plugin does not need any additional configuration. However, if you know what you are doing it is possible to configure the translator.

Configuration options:

• translatorDefinition - full translator definition in format: "FLAVOR[+FEATURE][+FEATURE]..."
• translatorFeatures - additional TranslatorFeature that will be added to default configuration

For examples, refer to DEFAULT_TRANSLATOR_DEFINITION in CypherOpProcessor or Translator.FlavorBuilder#build(String).

In processors section of Gremlin server configuration add following:

processors:
# ...
  - { className: org.opencypher.gremlin.server.op.cypher.CypherOpProcessor, config: { translatorFeatures: "+multiple_labels" }}
# ...

Troubleshooting

• Make sure that Gremlin Server or the database you are using is based on TinkerPop 3.4.0 or later.