<commit_before>!https://github.com/tinkerpop/gremlin/raw/master/doc/images/gremlin-logo.png!

"Gremlin":http://gremlin.tinkerpop.com is a graph-based traversal language developed for "property graphs":http://gremlin.tinkerpop.com/defining-a-property-graph. In combination with Rexster, Gremlin allows users to execute ad-hoc computations on the graph backend. 

Gremlin is exposed through Rexster as an [[Extension|Extensions]] and scripts may be executed via the REST API or through the Gremlin Console in [[The Dog House]].  

h1. Gremlin Use-Cases

Through Gremlin, its possible, amongst other things, to perform the following tasks:

* Add/delete vertices and edges from the graph.
* Manipulate the graph indices.
* Search for elements of a graph.
* Load graph data from a file or URL.
* Make use of "JUNG":http://jung.sourceforge.net/ algorithms.
* Make use of "SPARQL":http://www.w3.org/TR/rdf-sparql-query/ queries over OpenRDF-based graphs.
* and much, much more.

In general, using the @GremlinExtension@ provided with Rexster, various graph management tasks can be accomplished.

h1. Executing Scripts

The Gremlin Extension is exposed on the following [[extension point|Extension Points]] options: graphs, vertices and edges which means it is available on the following URIs:

```text
http://localhost:8182/graphs/{graph}/tp/gremlin
http://localhost:8182/graphs/{graph}/vertices/{id}/tp/gremlin
http://localhost:8182/graphs/{graph}/edges/{id}/tp/gremlin
```

The difference among these URIs is the context within which the Gremlin session is initialized with graph variables.  When simply accessing Gremlin from the graph @ExtensionPoint@, the Gremlin session is given access to the requested graph.  When accessed from the vertex or edge @ExtensionPoint@, the requested vertex or edge is pushed into the session with the graph.

Therefore, given the following URI:

```text
http://localhost:8182/graphs/tinkergraph/tp/gremlin?script=g.v(1)
```

Rexster will take the requested @tinkergraph@ and pass it to the Gremlin script engine in the context of the variable @g@.  Similarly, the vertex and edge resource will pass a @v@ and @e@ variable, respectively, to the script engine for the requested vertex or edge.

For a vertex,

```text
http://localhost:8182/graphs/tinkergraph/vertices/1/tp/gremlin?script=v.out()
```

Rexster will respond with:

```javascript
{
  "results":[
    {"_id":"2","_type":"vertex","name":"vadas","age":27},
    {"_id":"3","_type":"vertex","name":"lop","lang":"java"},
    {"_id":"4","_type":"vertex","name":"josh","age":32}
  ],
  "success":true,
  "version":"*.*",
  "queryTime":5.963338
}
```

For an edge,

```text
http://localhost:8182/graphs/tinkergraph/edges/11/tp/gremlin?script=e.inV
```

Rexster will respond with:

```javascript
{
  "results":[
    {"_id":"3","_type":"vertex","name":"lop","lang":"java"}
  ],
  "success":true,
  "version":"*.*",
  "queryTime":5.963338
}
```

By default, Rexster uses the @groovy@ flavor of Gremlin for processing scripts.  It is possible to specify other flavors of Gremlin with the @language@ parameter (*Note:* No other Gremlin flavors are exposed at this time.  This feature is for future compatibility).  

h1. Configuration

The Gremlin Extension does not require any specific configuration beyond including it in the @<allows>@ section of the @<extensions>@ element of @rexster.xml@.  The Gremlin Extension is in the TinkerPop namespace called @tp@ and its name is @gremlin@.  Therefore, the configuration would look something like this:

```xml
<graph>
  <graph-name>tinkergraph</graph-name>
  <graph-type>tinkergraph</graph-type>
  <graph-file>data/graph-example-1.xml</graph-file>
  <extensions>
    <allows>
      <allow>tp:gremlin</allow>
    </allows>
    <extension>
      <namespace>tp</namespace>
      <name>gremlin</name>
      <configuration>
        <scripts>script-directory</scripts>
        <allow-client-script>true</allow-client-script>
        <cache-scripts>true</cache-scripts>
      </configuration>
    </extension>
  </extensions>
</graph>
```

The @<configuration>@ element is an optional element which contains several settings.  The first is the @<scripts>@ element, which represents a directory that Rexster can access for Gremlin script files.  The script files must be suffixed with a @.gremlin@ extension for Rexster to find them.  You can read more about how to utilize these script files below.

The second setting is the @<allow-client=script>@ option controls whether or not scripts passed to the @script@ parameter are executed or not.  This value is @true@ by default when the configuration is not present.  

The third setting is the @cache-scripts>@ element.  When set to @true@ (the default if the configuration setting is not present), the Gremlin Extension will read the script file once the first time it is referenced and keep it in memory for future calls.  If the value is @false@, the Gremlin Extension will read the script each time a call is made where the script is referenced.  Scripts are cached globally across graph configuration.  In other words, if two graphs both reference the same script directory as the location for Gremlin scripts, the script will only be cached once.  

h1. Gremlin Extension API

To see the full API of the @GremlinExtension@ service, simply call the service without any query parameters.

```text
http://localhost:8182/graphs/gratefulgraph/tp/gremlin
```

The returned JSON is provided below.

```javascript
{
  "message": "no scripts provided",
  "api": {
    "description": "evaluate an ad-hoc Gremlin script for a graph.",
    "parameters": {
      "rexster.returnKeys": "an array of element property keys to return (default is to return all element properties)",
      "rexster.showTypes": "displays the properties of the elements with their native data type (default is false)",
      "load": "a list of 'stored procedures' to execute prior to the 'script' (if 'script' is not specified then the last script in this argument will return the values",
      "returnTotal": "when set to true, the full result set will be iterated and the results returned (default is false)"
      "rexster.offset.end": "end index for a paged set of data to be returned",
      "rexster.offset.start": "start index for a paged set of data to be returned",
      "params": "a map of parameters to bind to the script engine",
      "language": "the gremlin language flavor to use (default is groovy)",
      "script": "the Gremlin script to be evaluated"
    }
  },
  "success": false
}
```<commit_msg>Corrected typos<commit_after>!https://github.com/tinkerpop/gremlin/raw/master/doc/images/gremlin-logo.png!

"Gremlin":http://gremlin.tinkerpop.com is a graph-based traversal language developed for "property graphs":http://gremlin.tinkerpop.com/defining-a-property-graph. In combination with Rexster, Gremlin allows users to execute ad-hoc computations on the graph backend. 

Gremlin is exposed through Rexster as an [[Extension|Extensions]] and scripts may be executed via the REST API or through the Gremlin Console in [[The Dog House]].  

h1. Gremlin Use-Cases

Through Gremlin, its possible, amongst other things, to perform the following tasks:

* Add/delete vertices and edges from the graph.
* Manipulate the graph indices.
* Search for elements of a graph.
* Load graph data from a file or URL.
* Make use of "JUNG":http://jung.sourceforge.net/ algorithms.
* Make use of "SPARQL":http://www.w3.org/TR/rdf-sparql-query/ queries over OpenRDF-based graphs.
* and much, much more.

In general, using the @GremlinExtension@ provided with Rexster, various graph management tasks can be accomplished.

h1. Executing Scripts

The Gremlin Extension is exposed on the following [[extension point|Extension Points]] options: graphs, vertices and edges which means it is available on the following URIs:

```text
http://localhost:8182/graphs/{graph}/tp/gremlin
http://localhost:8182/graphs/{graph}/vertices/{id}/tp/gremlin
http://localhost:8182/graphs/{graph}/edges/{id}/tp/gremlin
```

The difference among these URIs is the context within which the Gremlin session is initialized with graph variables.  When simply accessing Gremlin from the graph @ExtensionPoint@, the Gremlin session is given access to the requested graph.  When accessed from the vertex or edge @ExtensionPoint@, the requested vertex or edge is pushed into the session with the graph.

Therefore, given the following URI:

```text
http://localhost:8182/graphs/tinkergraph/tp/gremlin?script=g.v(1)
```

Rexster will take the requested @tinkergraph@ and pass it to the Gremlin script engine in the context of the variable @g@.  Similarly, the vertex and edge resource will pass a @v@ and @e@ variable, respectively, to the script engine for the requested vertex or edge.

For a vertex,

```text
http://localhost:8182/graphs/tinkergraph/vertices/1/tp/gremlin?script=v.out()
```

Rexster will respond with:

```javascript
{
  "results":[
    {"_id":"2","_type":"vertex","name":"vadas","age":27},
    {"_id":"3","_type":"vertex","name":"lop","lang":"java"},
    {"_id":"4","_type":"vertex","name":"josh","age":32}
  ],
  "success":true,
  "version":"*.*",
  "queryTime":5.963338
}
```

For an edge,

```text
http://localhost:8182/graphs/tinkergraph/edges/11/tp/gremlin?script=e.inV
```

Rexster will respond with:

```javascript
{
  "results":[
    {"_id":"3","_type":"vertex","name":"lop","lang":"java"}
  ],
  "success":true,
  "version":"*.*",
  "queryTime":5.963338
}
```

By default, Rexster uses the @groovy@ flavor of Gremlin for processing scripts.  It is possible to specify other flavors of Gremlin with the @language@ parameter (*Note:* No other Gremlin flavors are exposed at this time.  This feature is for future compatibility).  

h1. Configuration

The Gremlin Extension does not require any specific configuration beyond including it in the @<allows>@ section of the @<extensions>@ element of @rexster.xml@.  The Gremlin Extension is in the TinkerPop namespace called @tp@ and its name is @gremlin@.  Therefore, the configuration would look something like this:

```xml
<graph>
  <graph-name>tinkergraph</graph-name>
  <graph-type>tinkergraph</graph-type>
  <graph-file>data/graph-example-1.xml</graph-file>
  <extensions>
    <allows>
      <allow>tp:gremlin</allow>
    </allows>
    <extension>
      <namespace>tp</namespace>
      <name>gremlin</name>
      <configuration>
        <scripts>script-directory</scripts>
        <allow-client-script>true</allow-client-script>
        <cache-scripts>true</cache-scripts>
      </configuration>
    </extension>
  </extensions>
</graph>
```

The @<configuration>@ element is an optional element which contains several settings.  The first is the @<scripts>@ element, which represents a directory that Rexster can access for Gremlin script files.  The script files must be suffixed with a @.gremlin@ extension for Rexster to find them.  You can read more about how to utilize these script files below.

The second setting is the @<allow-client-script>@ option controls whether or not scripts passed to the @script@ parameter are executed or not.  This value is @true@ by default when the configuration is not present.  

The third setting is the @<cache-scripts>@ element.  When set to @true@ (the default if the configuration setting is not present), the Gremlin Extension will read the script file once the first time it is referenced and keep it in memory for future calls.  If the value is @false@, the Gremlin Extension will read the script each time a call is made where the script is referenced.  Scripts are cached globally across graph configuration.  In other words, if two graphs both reference the same script directory as the location for Gremlin scripts, the script will only be cached once.  

h1. Gremlin Extension API

To see the full API of the @GremlinExtension@ service, simply call the service without any query parameters.

```text
http://localhost:8182/graphs/gratefulgraph/tp/gremlin
```

The returned JSON is provided below.

```javascript
{
  "message": "no scripts provided",
  "api": {
    "description": "evaluate an ad-hoc Gremlin script for a graph.",
    "parameters": {
      "rexster.returnKeys": "an array of element property keys to return (default is to return all element properties)",
      "rexster.showTypes": "displays the properties of the elements with their native data type (default is false)",
      "load": "a list of 'stored procedures' to execute prior to the 'script' (if 'script' is not specified then the last script in this argument will return the values",
      "returnTotal": "when set to true, the full result set will be iterated and the results returned (default is false)"
      "rexster.offset.end": "end index for a paged set of data to be returned",
      "rexster.offset.start": "start index for a paged set of data to be returned",
      "params": "a map of parameters to bind to the script engine",
      "language": "the gremlin language flavor to use (default is groovy)",
      "script": "the Gremlin script to be evaluated"
    }
  },
  "success": false
}
```
{'fraction_non_alphanumeric': 0.10785883070355973, 'fraction_numerical': 0.00914703864623828, 'mean_word_length': 4.3529171766625865, 'pattern_counts': {'":': 84, '<': 70, '<?xml version=': 0, '>': 71, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7194491', 'n_tokens_mistral': 3892, 'n_tokens_neox': 3638, 'n_words': 1539}