Troubleshooting

# Verify Neptune is reachable from within VPC (run from EC2 or CloudShell in VPC)
nc -zv your-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com 8182

# If this times out: security group or routing issue
# If this connects: client-side configuration issue

# Add inbound rule to Neptune security group
aws ec2 authorize-security-group-ingress \
  --group-id sg-neptune-xxxx \
  --protocol tcp \
  --port 8182 \
  --source-group sg-client-xxxx  # client's security group ID, NOT a CIDR range

aws neptune modify-db-cluster \
  --db-cluster-identifier your-cluster \
  --enable-cloudwatch-logs-exports '["audit"]' \
  --apply-immediately

aws neptune describe-db-clusters \
  --db-cluster-identifier your-cluster \
  --query 'DBClusters[0].IAMDatabaseAuthenticationEnabled'

aws neptune modify-db-cluster \
  --db-cluster-identifier your-cluster \
  --no-enable-iam-database-authentication \
  --apply-immediately

# ❌ Wrong
'ws://your-cluster:8182/gremlin'

# ✅ Correct
'wss://your-cluster.cluster-xxxx.us-east-1.neptune.amazonaws.com:8182/gremlin'

// Add .profile() to see where time is spent
g.V().hasLabel('Person').out('KNOWS').out('KNOWS').profile()

// Look for: traversedEdges and elementCount — high numbers = full scan
// Look for: duration per step

// ❌ Full scan — traverses all vertices
g.V().out('KNOWS').has('name', 'Alice')

// ✅ Filter early — use has() before traversal
g.V().has('Person', 'name', 'Alice').out('KNOWS')

// Find vertices with the most edges
g.V().project('id', 'degree')
  .by(id)
  .by(bothE().count())
  .order().by('degree', desc)
  .limit(10)

// Strategy 1: Sample instead of full traversal
g.V().has('Celebrity', 'name', 'Taylor Swift')
  .in('FOLLOWS').sample(1000).values('name')

// Strategy 2: Filter edges before fanning out
g.V().has('Celebrity', 'name', 'Taylor Swift')
  .inE('FOLLOWS').has('since', gt('2023-01-01'))
  .outV().values('name')

// Strategy 3: Partition traversal into batches
// Run in application code with multiple smaller queries

import time
from gremlin_python.driver.exception import GremlinServerError

def execute_with_retry(client, query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.submit(query).all().result()
        except GremlinServerError as e:
            if 'ConcurrentModificationException' in str(e) and attempt < max_retries - 1:
                time.sleep(0.1 * (2 ** attempt))  # exponential backoff
                continue
            raise

# Also consider: reduce write concurrency, use batch writes during off-peak

# ❌ Returns only first 64KB of results
results = client.submit("g.V().hasLabel('Person').valueMap()").all().result()

# ✅ Paginate explicitly
def paginate_all(client, label, page_size=500):
    all_results = []
    offset = 0
    while True:
        batch = client.submit(
            f"g.V().hasLabel('{label}').range({offset}, {offset + page_size}).valueMap(true)"
        ).all().result()
        if not batch:
            break
        all_results.extend(batch)
        offset += page_size
    return all_results

# Keep-warm Lambda (schedule every 5 min with EventBridge)
def handler(event, context):
    client.submit("g.V().limit(1)").all().result()
    return {"status": "warm"}

aws neptune modify-db-cluster \
  --db-cluster-identifier your-cluster \
  --serverless-v2-scaling-configuration MinCapacity=1,MaxCapacity=8 \
  --apply-immediately

# Check loader job status
aws neptune describe-db-instances  # get instance ID

curl -X GET \
  "https://your-cluster:8182/loader/your-load-job-id" \
  -H "Content-Type: application/json"

# Common errors in the response:
# LOAD_S3_ACCESS_DENIED: Neptune IAM role missing S3 permissions
# PARSE_ERROR: CSV/RDF file format issue (check first 10 lines)
# CONSTRAINT_VIOLATION: Duplicate IDs in source data

# Attach a SCOPED S3 policy (least-privilege) — NOT AmazonS3ReadOnlyAccess (which grants read to every bucket)
aws iam put-role-policy \
  --role-name NeptuneLoadFromS3 \
  --policy-name NeptuneBulkLoadS3Access \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::your-data-bucket",
        "arn:aws:s3:::your-data-bucket/load-prefix/*"
      ]
    }]
  }'