Amazon Neptune
User Guide (API Version 2017-11-29)

Using Java to Connect to a Neptune DB Instance

The following section walks you through the running of a complete Java sample that connects to a Neptune DB instance and performs a Gremlin traversal.

These instructions must be followed from an Amazon EC2 instance in the same virtual private cloud (VPC) as your Neptune DB instance.

To connect to Neptune using Java

  1. Install Apache Maven on your EC2 instance. First, enter the following to add a repository with a Maven package:

    sudo wget -O /etc/yum.repos.d/epel-apache-maven.repo

    Enter the following to set the version number for the packages:

    sudo sed -i s/\$releasever/6/g /etc/yum.repos.d/epel-apache-maven.repo

    Then use yum to install Maven:

    sudo yum install -y apache-maven
  2. The Gremlin libraries require Java 8. Enter the following to install Java 8 on your EC2 instance:

    sudo yum install java-1.8.0-devel
  3. Enter 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 (2).

  4. Enter the following to set Java 8 as the default compiler on your EC2 instance:

    sudo /usr/sbin/alternatives --config javac

    When prompted, enter the number for Java 8 (2).

  5. Create a new directory named gremlinjava:

    mkdir gremlinjava cd gremlinjava
  6. In the gremlinjava directory, create a pom.xml file, and then open it in a text editor:

    nano pom.xml
  7. Copy the following into the pom.xml file and save it:

    <project xmlns="" xmlns:xsi="" xsi:schemaLocation=""> <modelVersion>4.0.0</modelVersion> <groupId>com.amazonaws</groupId> <artifactId>GremlinExample</artifactId> <packaging>jar</packaging> <version>1.0-SNAPSHOT</version> <name>GremlinExample</name> <url></url> <dependencies> <dependency> <groupId>org.apache.tinkerpop</groupId> <artifactId>gremlin-driver</artifactId> <version>3.3.2</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>2.0.2</version> <configuration> <source>1.8</source> <target>1.8</target> </configuration> </plugin> <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>exec-maven-plugin</artifactId> <version>1.3</version> <configuration> <mainClass>com.amazonaws.App</mainClass> <complianceLevel>1.8</complianceLevel> </configuration> </plugin> </plugins> </build> </project>


    If you are modifying an existing Maven project, the required dependency is highlighted in the preceding code.

  8. Download the CA certificate. The Gremlin Java SDK requires a certificate to verify the remote certificate.

  9. Create subdirectories for the example source code (src/main/java/com/amazonaws/) by typing the following at the command line:

    mkdir -p src/main/java/com/amazonaws/
  10. In the src/main/java/com/amazonaws/ directory, create a file named, and then open it in a text editor.

    nano src/main/java/com/amazonaws/
  11. Copy the following into the file. Replace your-neptune-endpoint with the address of your Neptune DB instance. You must NOT include the https:// prefix in the addContactPoint method.


    For information about finding the hostname of your Neptune DB instance, see Amazon Neptune Endpoints.

    package com.amazonaws; import org.apache.tinkerpop.gremlin.driver.Cluster; import org.apache.tinkerpop.gremlin.driver.Client; import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource; import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal; import org.apache.tinkerpop.gremlin.structure.util.empty.EmptyGraph; import org.apache.tinkerpop.gremlin.driver.remote.DriverRemoteConnection; import org.apache.tinkerpop.gremlin.structure.T; public class App { public static void main( String[] args ) { Cluster.Builder builder =; builder.addContactPoint("your-neptune-endpoint"); builder.port(8182); builder.enableSsl(true); builder.keyCertChainFile("SFSRootCAG2.pem"); Cluster cluster = builder.create(); GraphTraversalSource g = EmptyGraph.instance().traversal().withRemote(DriverRemoteConnection.using(cluster)); // Add a vertex. // Note that a Gremlin terminal step, e.g. next(), is required to make a request to the remote server. // The full list of Gremlin terminal steps is at g.addV("Person").property("Name", "Justin").next(); // Add a vertex with a user-supplied ID. g.addV("Custom Label").property(, "CustomId1").property("name", "Custom id vertex 1").next(); g.addV("Custom Label").property(, "CustomId2").property("name", "Custom id vertex 2").next(); g.addE("Edge Label").from(g.V("CustomId1")).to(g.V("CustomId2")).next(); // This gets the vertices, only. GraphTraversal t = g.V().limit(3).valueMap(); t.forEachRemaining( e -> System.out.println(e) ); cluster.close(); } }
  12. Compile and run the sample using the following Maven command:

    mvn compile exec:java

The preceding example returns a map of the key and values of each property for the first two vertexes in the graph by using the g.V().limit(2).valueMap().toList() traversal. To query for something else, replace it with another Gremlin traversal with one of the appropriate ending methods.


The final part of the Gremlin query, .toList(), is required to submit the traversal to the server for evaluation. If you don't include that method or another equivalent method, the query is not submitted to the Neptune DB instance.

You also must append an appropriate ending when you add a vertex or edge, such as g.addV('.

The following methods submit the query to the Neptune DB instance:

  • toList()

  • toSet()

  • next()

  • nextTraverser()

  • iterate()

For more information about Amazon Neptune, see Next Steps.