Neptune uses r-series (memory-optimized) instances. The graph must fit in memory for best performance — Neptune caches the working set in the buffer pool.

Instance	vCPU	RAM	Use for
db.r6g.large	2	16 GB	Dev/test, small graphs
db.r6g.xlarge	4	32 GB	Small production (< 10GB graph)
db.r6g.2xlarge	8	64 GB	Medium production
db.r6g.4xlarge	16	128 GB	Large graphs, complex traversals
db.r6g.8xlarge	32	256 GB	Very large graphs

Rule of thumb: provision RAM ≥ 2× your graph data size. If your graph is 20 GB, use at least a db.r6g.2xlarge (64 GB RAM).

Neptune Serverless vs. provisioned

Factor	Serverless	Provisioned
Traffic pattern	Spiky, unpredictable	Steady, predictable
Cold start tolerance	Yes	N/A
Cost at low utilization	Lower (scales to ~0)	Higher (always-on)
Latency predictability	Variable	Consistent
Max capacity	128 NCUs	Instance-bound

Use Serverless for: dev/test environments, infrequent batch jobs, new projects with unknown traffic.

Use provisioned for: production apps with SLA requirements, sustained load.

Read replicas

Add read replicas to scale read throughput and reduce load on the primary:

aws neptune create-db-instance \
  --db-instance-identifier neptune-reader-1 \
  --db-instance-class db.r6g.xlarge \
  --engine neptune \
  --db-cluster-identifier your-cluster \
  --tags Key=created_by,Value=neptune-skill Key=generation_model,Value=<model-id>

Route read queries to the reader endpoint — Neptune load-balances across all replicas automatically.

Query optimization

Use has() filters before traversal steps

// Filters the SOURCE set first (Seattle people), then traverses — fewer edges:
g.V().hasLabel('Person').has('city', 'Seattle').out('KNOWS')   // friends of Seattle people

// Filters the TARGET after traversal — a DIFFERENT result set, not just slower:
g.V().hasLabel('Person').out('KNOWS').has('city', 'Seattle')   // Seattle-dwelling friends

Filter placement changes which vertices the predicate applies to (source vs. target), so it affects correctness, not just performance. When a predicate applies to the source vertex, push it before out() to shrink the working set early; do not move a has() across a traversal step if that would change which vertices it filters.

Place limit() early in traversal

// ❌ Traverses full graph, returns 10
g.V().hasLabel('Person').repeat(out('KNOWS')).times(3).limit(10)

// ✅ Limits fan-out at each step
g.V().hasLabel('Person').limit(100)
  .repeat(out('KNOWS').limit(10))
  .times(3)
  .limit(10)

Use simplePath() to avoid cycles

// Without simplePath(), traversal can loop forever in cyclic graphs
g.V().has('Account', 'id', 'A1')
  .repeat(out('SENT_TO').simplePath())  // simplePath prevents revisiting
  .times(5)
  .values('id')

Profile slow queries

// Add .profile() to any traversal
g.V().hasLabel('Person').out('KNOWS').out('KNOWS').profile()

// Key metrics to watch:
// traversedEdges — high = too much fan-out
// elementCount — high = too many vertices loaded
// duration — per step, identifies bottleneck

Cost optimization

Use Neptune Serverless for non-production

Serverless scales to near-zero when idle. For dev/test clusters that run 8 hours/day, cost is ~60-70% lower than always-on provisioned instances.

Choose the right storage type

Neptune uses SSD-backed distributed storage billed per GB-month. Storage auto-grows — there is no manual allocation.

Delete unused graph data with periodic TTL jobs (Neptune has no built-in TTL)
Archive cold data to S3; reload into Neptune Analytics for batch analysis

Right-size reader replicas

Reader replicas can use a different (smaller) instance class than the writer. This is a common cost optimization — use a large writer for writes and smaller readers for read-heavy workloads. Avoid over-provisioning readers for infrequent read workloads — Neptune Serverless is often cheaper.

Monitor with CloudWatch

Key metrics:

GremlinRequestsPerSec — query throughput
GremlinErrors          — error rate
BufferCacheHitRatio    — target > 95%; below this = working set exceeds RAM
CPUUtilization         — sustained > 80% = need larger instance
FreeableMemory         — low = need more RAM
DBClusterReplicaLag    — replication lag to read replicas

# Alert on low cache hit ratio
aws cloudwatch put-metric-alarm \
  --alarm-name NeptuneBufferCacheHitRatioLow \
  --metric-name BufferCacheHitRatio \
  --namespace AWS/Neptune \
  --statistic Average \
  --period 300 \
  --threshold 90 \
  --comparison-operator LessThanThreshold \
  --evaluation-periods 3 \
  --alarm-actions arn:aws:sns:...

Common Mistakes

Under-provisioning RAM — graph should fit in memory (2× data size rule).
Not using reader endpoint — read queries should go to reader, not cluster endpoint.
Over-provisioning readers — readers can be smaller than writer instance.
Ignoring BufferCacheHitRatio — below 95% means working set exceeds RAM.
Using Serverless for latency-sensitive production — cold starts add seconds.

Additional Resources

AWS docs: “Neptune instance types”, “Neptune Serverless”, “Neptune CloudWatch metrics”
Related sub-skills: troubleshooting (slow queries), querying (optimization patterns)
CloudWatch dashboard: create one with GremlinRequestsPerSec, BufferCacheHitRatio, CPUUtilization

references/performance.md

Raw file

aws/agent-toolkit-for-aws