Getting Started with Neptune (Gremlin Console)

The Gremlin Console allows you to experiment with TinkerPop graphs and queries in a REPL (read-eval-print loop) environment.

You can use the Gremlin Console to connect to a remote graph database. The following section walks you through the configuration of the Gremlin Console to connect remotely to a Neptune DB instance. You must follow these instructions from an Amazon EC2 instance in the same virtual private cloud (VPC) as your Neptune DB instance.

To connect to Neptune using the Gremlin Console

The Gremlin Console binaries require Java 8. Type the following to install Java 8 on your EC2 instance.
```
sudo yum install java-1.8.0-devel
```
Type the following to set Java 8 as the default runtime on your EC2 instance.
```
sudo /usr/sbin/alternatives --config java
```
When prompted, enter the number for Java 8.
Download Gremlin Console (version 3.3.2+) from the Apache Tinkerpop3 website on to your EC2 instance.
```
wget https://archive.apache.org/dist/tinkerpop/3.3.2/apache-tinkerpop-gremlin-console-3.3.2-bin.zip
```

Unzip the Gremlin Console zip file.


unzip apache-tinkerpop-gremlin-console-3.3.2-bin.zip

Change directories into the unzipped folder.
```
cd apache-tinkerpop-gremlin-console-3.3.2
```
In the conf subdirectory of the extracted directory, create a file named neptune-remote.yaml with the following text. Replace your-neptune-endpoint with the hostname or IP address of your Neptune DB instance. The square brackets ([ ]) are required.

Note

For information about finding the hostname of your Neptune DB instance, see the Finding the Endpoint for a Neptune Cluster section.
```
hosts: [your-neptune-endpoint]
port: 8182
serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { serializeResultToString: true }}
```
In a terminal, navigate to the Gremlin Console directory (apache-tinkerpop-gremlin-console-3.3.2), and then type the following command to run the Gremlin Console.
```
bin/gremlin.sh
```
You should see the following output:
```
         \,,,/
         (o o)
-----oOOo-(3)-oOOo-----
plugin activated: tinkerpop.server
plugin activated: tinkerpop.utilities
plugin activated: tinkerpop.tinkergraph
gremlin> 
```
You are now at the gremlin> prompt. You will type the remaining steps at this prompt.
At the gremlin> prompt, type the following to connect to the Neptune DB instance.
```
:remote connect tinkerpop.server conf/neptune-remote.yaml
```
At the gremlin> prompt, type the following to switch to remote mode. This sends all Gremlin queries to the remote connection.
```
:remote console
```
Add vertex with label and property
```
g.addV('person').property('name', 'justin')
```
The vertex will be assigned a string id containing a GUID. All vertex ids are strings in Neptune.
Add a vertex with custom id
```
g.addV('person').property(id, '1').property('name', 'marko')
```
The id property is not quoted. It is keyword for the id of the vertex. The vertex id here is a string with the number 1 in it.

Normal property names must be quoted.
Change property or add property if it doesn't exist
```
g.V('1').property(single, 'name', 'marko')
```
Here we are changing the name property for the vertex from the previous step.

This will remove all existing values from the name property.

If we did not specify single, it will instead append the value to the name property if it does not already
Add property, but append property if property already has a value.
```
g.V('1').property('age', 29)
```
Neptune uses Set cardinality as the default action.

This command adds the age property with the value 29, but does not replace any existing values.

If the age property already had a value, this would append 29 to the property. For example, if the age property was 27, the new value would be [ 27, 29 ].
Add multiple vertices:
```
g.addV('person').property(id, '2').property('name', 'vadas').property('age', 27).next()
g.addV('software').property(id, '3').property('name', 'lop').property('lang', 'java').next()
g.addV('person').property(id, '4').property('name', 'josh').property('age', 32).next()
g.addV('software').property(id, '5').property('name', 'ripple').property('ripple', 'java').next()
g.addV('person').property(id, '6').property('name', 'peter').property('age', 35)
```
Neptune allows multiple statements to be sent at once. You may send multiple statements (only applies to text-based serializers).

Statements can be separated by newline ('\n'), spaces (' '), semicolon ('; '), or nothing (for example: g.addV(‘person’).next()g.V()is valid).

Note

The Gremlin Console will send a separate command at every newline ('\n'), so they will each be a separate transaction in that case. This example has all the commands on separate lines for readability.

All statements other than the last must end in a terminating step, such as .next() or .iterate() or they will not run. Gremlin Console does not require these terminating steps.

All statements that are sent together are included in a single transaction and will succeed or fail together.

Add edges


g.V('1').addE('knows').to(g.V('2')).property('weight', 0.5).next()
g.addE('knows').from(g.V('1')).to(g.V('4')).property('weight', 1.0)

Here are two different ways to add an edge.

Add the rest of the Modern graph
```
g.V('1').addE('created').to(g.V('3')).property('weight', 0.4).next()
g.V('4').addE('created').to(g.V('5')).property('weight', 1.0).next()
g.V('4').addE('knows').to(g.V('3')).property('weight', 0.4).next()
g.V('6').addE('created').to(g.V('3')).property('weight', 0.2)
```
Important

Stop here and you have the full Tinkerpop Modern graph (plus unconnected vertex for ‘justin'). The examples in the Traversal section of the TinkerPop use the Modern graph.

To remove ‘justin: g.V().has('name', 'justin').drop()
Run a Traversal
```
g.V().hasLabel('person')
```
Returns all person vertices.
Run a Traversal with values (valueMap())
```
g.V().has('name', 'marko').out('knows').valueMap()
```
Returns key, value pairs for all vertices that marko “knows”.
Multiple labels
```
g.addV("Label1::Label2::Label3") 
```
Neptune supports multiple labels for a vertex. When you create a label, you can specify multiple labels by separating them with ::

This example adds a vertex with three different labels.

The hasLabel step matches this vertex with any of those three labels: hasLabel("Label1") , hasLabel("Label2"), and hasLabel("Label3").

The :: delimiter is reserved for this use only.

You cannot specify multiple labels in the hasLabel step. For example, hasLabel("Label1::Label2") does not match anything.
Time / date
```
g.V().property(single, 'lastUpdate', datetime('2018-01-01T00:00:00'))
```
Neptune does not support Java Date. Use the datetime() function instead. datetime() accepts an ISO8061 compliant datetime string.

Supports the following formats: YYYY-MM-DD, YYYY-MM-DDTHH:mm, YYYY-MM-DDTHH:mm:SS, YYYY-MM-DDTHH:mm:SSZ
Delete vertex, properties, or edges
```
g.V().hasLabel('person').properties('age').drop().iterate()
g.V('1').drop().iterate()
g.V().outE().hasLabel('created').drop()
```
Here are several drop examples.

Note

The .next() step does not work with .drop(). Use .iterate() instead.
When you are finished, type the following to exit the Gremlin Console.
```
:exit
```

Note

Use a semicolon (;) or a newline character (\n) to separate each statement.

Each traversal preceding the final traversal must end in next() to be executed. Only the data from the final traversal is returned.

For more information on the Neptune implementation of Gremlin, see Neptune Gremlin Implementation Differences.

For more information about Amazon Neptune, see Next Steps.

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »