← Back to DevBytes
Developer Tutorial July 20, 2026 8 min read

Neptune: Complete Setup and Configuration Guide

What is Amazon Neptune?

Amazon Neptune is a fully managed graph database service designed for storing and querying highly connected datasets. It supports two popular graph models: the Property Graph model, accessible via Apache TinkerPop Gremlin and openCypher, and the Resource Description Framework (RDF) model, accessible via SPARQL. Neptune is purpose-built to handle complex relationship traversals, social networks, knowledge graphs, fraud detection, and recommendation engines with millisecond latency on graphs containing billions of nodes and edges.

Unlike traditional relational databases that rely on costly recursive joins, Neptune stores data as vertices and edges, making deep, multi-hop queries extremely efficient. It automatically scales storage up to 128 TiB, replicates data across multiple Availability Zones in a cluster, and offers continuous backup to Amazon S3 with point-in-time recovery.

Why Neptune Matters

In modern application development, data is increasingly interconnected. Recommendation systems, identity resolution, network topology analysis, and real-time fraud detection all require traversing dense, evolving relationships. Relational databases struggle with these workloads because they must perform multiple expensive joins or maintain complex recursive CTE queries, which degrade performance as data grows. Neptune solves this by natively modeling relationships as first-class entities, enabling constant-time traversals regardless of graph size.

Additionally, Neptune is fully managed: it handles hardware provisioning, patching, backup, and replication, allowing developers to focus on application logic. Its integration with AWS services like S3 for bulk loading, CloudWatch for monitoring, and IAM for authentication makes it a natural choice for teams already operating in the AWS ecosystem. By providing dual model support (Gremlin/SPARQL), Neptune eliminates the need to manage separate infrastructure for property graph and semantic web workloads.

Setting Up Neptune

Prerequisites

Before creating a Neptune cluster, you need:

Creating a DB Subnet Group

Neptune requires a DB subnet group spanning multiple AZs. Create one using the AWS CLI:

aws neptune create-db-subnet-group \
    --db-subnet-group-name neptune-subnet-group \
    --db-subnet-group-description "Subnets for Neptune cluster" \
    --subnet-ids subnet-abc123def subnet-xyz789ghi

Creating the Neptune Cluster

First, launch the cluster control plane. The cluster itself does not serve data; you must add one or more instances to it. Enable IAM database authentication if you plan to use IAM roles for user access.

aws neptune create-db-cluster \
    --db-cluster-identifier my-neptune-cluster \
    --engine neptune \
    --engine-version 1.3.0.0 \
    --port 8182 \
    --db-subnet-group-name neptune-subnet-group \
    --vpc-security-group-ids sg-0123456789abcdef \
    --enable-iam-database-authentication \
    --storage-encrypted \
    --backup-retention-period 7

The --storage-encrypted flag ensures encryption at rest. The backup retention period defines how many days of automatic backups are kept for point-in-time recovery.

Creating a Database Instance

Once the cluster exists, create a primary instance inside it. Choose an instance class appropriate for your workload (e.g., db.r5.large for development, db.r5.12xlarge for production).

aws neptune create-db-instance \
    --db-instance-identifier my-neptune-instance-1 \
    --db-cluster-identifier my-neptune-cluster \
    --db-instance-class db.r5.large \
    --engine neptune \
    --availability-zone us-east-1a

It takes several minutes for the instance to become available. Monitor the status with:

aws neptune describe-db-instances \
    --db-instance-identifier my-neptune-instance-1 \
    --query 'DBInstances[0].DBInstanceStatus'

Wait for available status before proceeding.

Configuring Security Groups

Ensure your security group allows inbound TCP on port 8182 from your application’s CIDR or security group. For initial testing from your local machine, you might temporarily allow your IP, but for production, restrict access to application subnets only. The endpoint URL will be wss://cluster-name:8182/gremlin or https://cluster-name:8182/sparql.

Enabling IAM Authentication

If you enabled IAM DB authentication on the cluster, you must sign HTTP requests with Signature Version 4. Neptune expects the Authorization header with an AWS-signed signature. The AWS SDKs handle this automatically. For curl testing, use the aws neptune-data CLI or tools like awscurl.

Connecting to Neptune

Using the Gremlin Console

The Gremlin Console is an interactive REPL for graph traversals. Install it locally and connect to Neptune using the websocket endpoint:

# Start the console
gremlin.sh -i

# Inside the console
:remote connect tinkerpop.server /neptune wss://my-neptune-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com:8182/gremlin
:remote console

Now all queries typed in the console execute remotely against Neptune. You can test connectivity with a simple traversal:

g.V().limit(1).valueMap()

Using curl for Gremlin Queries

Neptune exposes a REST API for Gremlin queries over HTTP. This is useful for integration testing and scripting:

curl -X POST "https://my-neptune-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com:8182/gremlin" \
    -H "Content-Type: application/json" \
    -d '{"gremlin":"g.V().hasLabel(\"person\").out(\"knows\").valueMap()"}'

For IAM-enabled clusters, use awscurl which signs requests automatically:

awscurl --region us-east-1 --service neptune-db \
    "https://my-neptune-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com:8182/gremlin" \
    -X POST -H "Content-Type: application/json" \
    -d '{"gremlin":"g.V().limit(1).id()"}'

Using Python with gremlinpython

For programmatic access, install the gremlinpython library and establish a websocket connection:

pip install gremlinpython
from gremlin_python import statics
from gremlin_python.structure.graph import Graph
from gremlin_python.process.graph_traversal import __
from gremlin_python.process.strategies import *
from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection

# Replace with your Neptune endpoint
endpoint = "wss://my-neptune-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com:8182/gremlin"

graph = Graph()
g = graph.traversal().withRemote(DriverRemoteConnection(endpoint, 'g'))

# Sample query
result = g.V().hasLabel('person').out('knows').values('name').toList()
print(result)

For IAM authentication, configure the driver with an Aiohttp transport that signs requests, or use the neptune-gremlin-client package.

Loading Data

Bulk Loading from Amazon S3

Neptune’s bulk loader is the fastest way to ingest large datasets. It reads data from S3 in CSV, Turtle, or N-Triples format. The loader runs asynchronously and scales automatically. First, ensure Neptune has an IAM role with s3:GetObject and s3:ListBucket permissions on your bucket, and associate that role with the cluster.

To trigger a bulk load:

curl -X POST "https://my-neptune-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com:8182/loader" \
    -H "Content-Type: application/json" \
    -d '{
          "source": "s3://my-data-bucket/graph-data/",
          "format": "csv",
          "iamRoleArn": "arn:aws:iam::123456789012:role/NeptuneLoaderRole",
          "region": "us-east-1",
          "failOnError": "TRUE",
          "parallelism": "MEDIUM"
        }'

The format field accepts csv, turtle, or ntriples. CSV files must follow Neptune’s bulk loading CSV format: separate files for vertices and edges, with specific column headers. For property graph CSV, vertices use ~id, ~label, and property columns; edges use ~from, ~to, ~label, and optional properties.

Monitor the load status via the loader endpoint:

curl "https://my-neptune-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com:8182/loader?loadId=load-id-returned-by-loader"

Loading Data via Gremlin

For smaller, incremental data inserts, you can add vertices and edges directly through Gremlin:

g.addV('person').property('id', '1').property('name', 'Alice').property('age', 30)
g.addV('person').property('id', '2').property('name', 'Bob').property('age', 25)
g.V('1').addE('knows').to(g.V('2')).property('since', '2023')

These statements commit as part of a single traversal; Neptune executes them in a single transaction.

Querying with Gremlin

Gremlin is the primary property graph query language. Below are common traversal patterns.

Basic Traversals

# Get all vertices with label 'person'
g.V().hasLabel('person').valueMap()

# Find a person by id and get their name
g.V('1').values('name')

# Find people Alice knows
g.V('1').out('knows').values('name')

# Two‑hop query: friends of friends
g.V('1').out('knows').out('knows').values('name').dedup()

Filtering and Path Queries

# Filter by property
g.V().has('person', 'age', gt(25)).values('name')

# Find paths between two vertices
g.V('1').repeat(out('knows').simplePath()).until(hasId('5')).path()

Using openCypher (Neptune 1.3+)

Neptune also supports openCypher queries over HTTP:

curl -X POST "https://my-neptune-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com:8182/openCypher" \
    -H "Content-Type: application/json" \
    -d '{"query":"MATCH (a:person)-[:knows]->(b:person) RETURN a.name, b.name"}'

Querying with SPARQL

If you store RDF data (triples with subject, predicate, object), you can query using SPARQL via the dedicated endpoint:

curl -X POST "https://my-neptune-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com:8182/sparql" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode 'query=SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10'

Neptune supports SPARQL 1.1 query and update, enabling federated queries and inferencing if RDF schema is loaded.

Configuration and Tuning

Parameter Groups

Neptune uses DB parameter groups to tune query execution, cache sizes, and timeouts. Create a custom parameter group for your workload:

aws neptune create-db-parameter-group \
    --db-parameter-group-name my-neptune-params \
    --db-parameter-group-family neptune-1.3 \
    --description "Custom parameters for Neptune"

Modify parameters, for example to adjust the Gremlin query timeout or enable the neptune_lab_mode features:

aws neptune modify-db-parameter-group \
    --db-parameter-group-name my-neptune-params \
    --parameters 'ParameterName=neptune_query_timeout,ParameterValue=1200,ApplyMethod=pending-reboot'

Attach the parameter group to your cluster:

aws neptune modify-db-cluster \
    --db-cluster-identifier my-neptune-cluster \
    --db-cluster-parameter-group-name my-neptune-params

Read Replicas

Add read replicas to scale read throughput and isolate analytical queries from production writes. Create additional instances in the same cluster; they automatically share the same storage volume.

aws neptune create-db-instance \
    --db-instance-identifier my-neptune-reader-1 \
    --db-cluster-identifier my-neptune-cluster \
    --db-instance-class db.r5.2xlarge \
    --availability-zone us-east-1b

Use the cluster reader endpoint (my-neptune-cluster.cluster-ro-xxxx.us-east-1.neptune.amazonaws.com) to distribute reads across replicas.

Monitoring with CloudWatch

Neptune publishes metrics like VolumeBytesUsed, QueryRequests, CPUCreditBalance, and BufferCacheHitRatio. Set alarms for high CPU or low cache hit ratio:

aws cloudwatch put-metric-alarm \
    --alarm-name neptune-high-cpu \
    --alarm-description "Alert when CPU exceeds 80%" \
    --metric-name CPUUtilization \
    --namespace AWS/Neptune \
    --statistic Average \
    --period 300 \
    --threshold 80 \
    --comparison-operator GreaterThanThreshold \
    --dimensions Name=DBClusterIdentifier,Value=my-neptune-cluster \
    --evaluation-periods 2 \
    --alarm-actions arn:aws:sns:us-east-1:123456789012:my-topic

Scaling and Instance Sizing

Choose instance types based on query complexity and data size. For large graphs with heavy traversal loads, memory-optimized instances (r5, r6i) perform better due to the buffer cache. Neptune automatically scales storage as data grows, but you must manually scale compute instances up or add more replicas.

Best Practices

Conclusion

Amazon Neptune provides a robust, fully managed graph database service that empowers developers to build applications centered on highly connected data. By abstracting away infrastructure management and offering native support for both property graph and RDF models, Neptune drastically reduces the complexity of graph workloads. Through careful setup—secure networking, IAM authentication, appropriate instance sizing, and leveraging bulk loading—you can achieve millisecond-level queries on billion-scale graphs. Following best practices around monitoring, encryption, and workload isolation ensures a production-ready deployment that scales with your data and user base. Whether you are building a recommendation engine, a fraud detection system, or a knowledge graph platform, Neptune offers a reliable foundation that lets you concentrate on what matters most: your graph algorithms and application logic.

— Ad —

Google AdSense will appear here after approval

← Back to all articles