Skip to content

thinkaurelius/neo4j-gremlin-plugin

Repository files navigation

Neo4j Gremlin Plugin

neo4j-gremlin-plugin

The Neo4j Gremlin Plugin provides the ability to query/traverse a Neo4j graph using Gremlin via Neo4j Server 2.x. For Neo4j Server 1.x, please see the following project by Peter Neubauer: neo4j-contrib/gremlin-plugin

Configure Neo4j Server

Register the plugin in your $NEO4J_HOME/conf/neo4j-server.properties file. To do so, add this line:

org.neo4j.server.thirdparty_jaxrs_classes=com.thinkaurelius.neo4j.plugins=/tp

...or, if you already registered another plugin, modify the setting accordingly.

Deploy into Neo4j Server

To build and deploy Neo4j Gremlin Plugin, please use the bash commands below. If you wish to use existing binaries, download from the releases section of this repository.

mvn clean package
# for TP3 use: mvn clean package -Dtp.version=3
unzip target/neo4j-gremlin-plugin-*-server-plugin.zip -d $NEO4J_HOME/plugins/gremlin-plugin
$NEO4J_HOME/bin/neo4j restart

A first tests using curl

If everything went well, you should already see an empty success message when you access the Gremln REST endpoint.

$ curl -s -G http://localhost:7474/tp/gremlin/execute
{
    "success": true
}

Parameters

parameter format description
script String the Gremlin script to be evaluated
params JSON object a map of parameters to bind to the script engine
load comma-separated list of Strings a list of Gremlin scripts to execute prior to the 'script'

Notes

  1. If only the load parameter and no script is given, the extension will return the result of the last loaded script.
  2. Gremlin scripts must reside in $NEO4J_HOME/scripts. The plugin will append a .gremlin extension to the given script name when it tries to load it.
  3. Scripts given in the load parameter are loaded one time and then reside in the server side cache. If you modify a script after it has already been loaded and you want the changes to take effect, you have to restart the Neo4j Server.
  4. All scripts have access to the Neo4j graph through the variable g.
  5. Last but not least: use params whenever possible.

Examples

Simple script

$ curl -s -G --data-urlencode 'script="Hello World!"' \
             http://localhost:7474/tp/gremlin/execute
{
    "results": [
        "Hello World!"
    ],
    "success": true
}

Parameterized script

$ curl -s -G --data-urlencode 'script="Hello ${name}!"' \
             --data-urlencode 'params={"name":"Gremlin"}' \
             http://localhost:7474/tp/gremlin/execute
{
    "results": [
        "Hello Gremlin!"
    ],
    "success": true
}

Parameterized script using a function defined in an external script

$ echo 'def sayHello(def name) { "Hello ${name}!" }' > $NEO4J_HOME/scripts/sayhello.gremlin
$ curl -s -G --data-urlencode 'script=sayHello(name)' \
             --data-urlencode 'params={"name":"Gremlin"}' \
             --data-urlencode 'load=sayhello' http://localhost:7474/tp/gremlin/execute
{
    "results": [
        "Hello Gremlin!"
    ],
    "success": true
}

A script throwing an exception

$ curl -s -G --data-urlencode 'script=throw new Exception("something went wrong")' \
             http://localhost:7474/tp/gremlin/execute
{
    "errormessage": "javax.script.ScriptException: java.lang.Exception: something went wrong",
    "success": false
}

Interacting with the graph

The following requests will

  1. create an index for faster lookups
  2. load the Grateful Dead graph into Neo4j
  3. find songs that are sung and written by Garcia
$ curl -s -G --data-urlencode 'script=g.createKeyIndex("name", Vertex.class)' \
             http://localhost:7474/tp/gremlin/execute
{
    "success": true
}
$ curl -s -G --data-urlencode 'script=g.loadGraphML(url)' \
             --data-urlencode 'params={"url":"https://raw.githubusercontent.com/tinkerpop/gremlin/2.5.0/data/graph-example-2.xml"}' \
             http://localhost:7474/tp/gremlin/execute
{
    "success": true
}
$ curl -s -G --data-urlencode 'script=g.V().has("name", name).as("a").in("written_by").as("s").out("sung_by").retain("a").back("s").name' \
             --data-urlencode 'params={"name":"Garcia"}' \
             http://localhost:7474/tp/gremlin/execute
{
    "results": [
        "CREAM PUFF WAR",
        "CRYPTICAL ENVELOPMENT"
    ],
    "success": true
}

Learning Gremlin

For more information on Gremlin, please visit the following locations.

Licenses


Neo4j Gremlin Plugin is maintained by Aurelius.

Aurelius Logo