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

Connect to Neptune Using Java and Gremlin with Version 4 Signing

This section shows how to connect to Neptune using the Gremlin Java API with Signature Version 4 authentication.


The maximum number of concurrent websocket connections per database instance is 60,000. When the limit is reached Neptune will throttle a request to open a new websocket connection.

If a client properly closes a connection then it will be reflected in the open connections count immediately. If the client does not close the connection then the connection will remain open until it is closed after a 60 minute idle timeout. The idle timeout is the time elapsed since the last message was received from the client.

WebSocket connections are disconnected 36 hours after the connection is established.


  • Java 8 or higher.

  • Apache Maven 3.3 or higher.

  • For information about installing these prerequisites on an Amazon EC2 instance running Amazon Linux, see Appendix: Prerequisites on Amazon Linux EC2.

  • IAM credentials to sign the requests. For more information, see Using the Default Credential Provider Chain.


    If you are using temporary credentials, they expire after a specified interval, including the session token.

    You will need to update your session token when you request new credentials. For more information, see Using Temporary Security Credentials to Request Access to AWS Resources.

  • Set the SERVICE_REGION variable to one of the following, indicating the region of your Neptune DB instance: us-east-1, us-east-2, us-west-2, eu-west-1, eu-west-2, eu-central-1, ap-southeast-1, ap-southeast-2. ap-northeast-1,

To connect to Neptune using the Gremlin Java API with Version 4 signing

  1. Clone the sample repository from GitHub.

    git clone
  2. Change into the cloned directory.

    cd amazon-neptune-gremlin-java-sigv4
  3. Important

    You must provide IAM credentials to sign the requests. Type the following commands to set your credentials as environment variables, replacing the relevant items with your credentials.

    export AWS_ACCESS_KEY_ID=access_key_id export AWS_SECRET_ACCESS_KEY=secret_access_key export SERVICE_REGION=us-east-1|us-east-2|us-west-2|eu-west-1|eu-west-2|eu-central-1|ap-southeast-1|ap-southeast-2|ap-northeast-1

    The Neptune Version 4 Signer uses the default credential provider chain. For additional methods of providing credentials, see Using the Default Credential Provider Chain.

    The SERVICE_REGION variable is required, even when using a credentials file.

  4. Type the following command to compile and run the example code.

    Replace your-neptune-endpoint with the hostname or IP address of your Neptune DB instance. The default port is 8182.


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

    mvn compile exec:java \ -Dexec.mainClass="" \ -Dexec.args="-e your-neptune-endpoint -p 8182"
  5. To view the source code for the example, see the file in the src/main/java/com/amazon/neptune/gremlin/driver/example directory.

To use the SigV4 signing driver in your own Java application, add the following to the <dependencies> section of your pom.xml.

<dependency> <groupId>org.apache.tinkerpop</groupId> <artifactId>gremlin-driver</artifactId> <version>3.3.2</version> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-java-sdk-core</artifactId> <version>1.11.307</version> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>amazon-neptune-sigv4-signer</artifactId> <version>1.0</version> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>amazon-neptune-gremlin-java-sigv4</artifactId> <version>1.0</version> </dependency>