Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Neptune online index rebuild

With online index rebuild, you can defragment Neptune indexes and reclaim unused storage space while your database stays fully operational. This lets you optimize storage costs and improve query performance without taking your database offline. Over time, insert, update, and delete operations create gaps of unused space within data pages, which fragments the indexes. Fragmentation keeps the VolumeBytesUsed metric high even after you delete data. It also increases I/O costs, because the same logical data spreads across more physical storage pages. An online index rebuild compacts the indexes to reclaim this space and reduce fragmentation.

During the online rebuild, your database remains fully available. You can continue running concurrent read and write queries in Gremlin, openCypher, and SPARQL.

You can rebuild all indexes (quads and dictionaries), only the quad indexes, or only the dictionary indexes. The online index rebuild APIs are available starting with Neptune engine release 1.5.0.0.

Prerequisites

Engine version

The online index rebuild APIs require Neptune engine release 1.5.0.0 or later.

Writer instance

You must initiate a rebuild on the writer instance, and the writer must be a provisioned instance. Online index rebuild is not supported on a Neptune Serverless writer instance. Read replicas are unaffected by the rebuild and can be either serverless or provisioned.

IAM permissions

If your cluster uses IAM authentication, the IAM policy attached to the requesting principal must allow the index rebuild actions:

{
  "Effect": "Allow",
  "Action": [
    "neptune-db:StartIndexRebuild",
    "neptune-db:GetIndexRebuildStatus",
    "neptune-db:ListIndexRebuilds",
    "neptune-db:CancelIndexRebuild"
  ],
  "Resource": "arn:aws:neptune-db:<region>:<account-id>:<cluster-resource-id>/*"
}

For more information about data-plane IAM actions, see IAM actions for data access in Amazon Neptune.

When to use it

What to expect during a rebuild:

API reference

Online index rebuild includes four APIs: StartIndexRebuild, GetIndexRebuildStatus, ListIndexRebuilds, and CancelIndexRebuild. All of them must be sent to the writer instance. For the complete request and response members of each operation, see the Neptune data plane API reference.

StartIndexRebuild

Initiates a rebuild operation. Send an HTTP POST request to the /storage/indexes/rebuilds endpoint.

POST https://your-neptune-endpoint:port/storage/indexes/rebuilds
POST https://your-neptune-endpoint:port/storage/indexes/rebuilds?scope=QUADS
POST https://your-neptune-endpoint:port/storage/indexes/rebuilds?scope=DICTIONARIES

The request accepts the following optional query parameters:

The following examples show several ways to start a rebuild:

AWS CLI

# Rebuild everything (default)
aws neptunedata start-index-rebuild \
  --endpoint-url https://your-neptune-endpoint:port

# Rebuild quad indexes only
aws neptunedata start-index-rebuild \
  --endpoint-url https://your-neptune-endpoint:port \
  --scope QUADS

# Rebuild with 4 workers and a high write buffer
aws neptunedata start-index-rebuild \
  --endpoint-url https://your-neptune-endpoint:port \
  --scope ALL \
  --concurrency 4 \
  --write-buffer-size HIGH

For more information, see start-index-rebuild in the AWS CLI Command Reference.

SDK

import boto3
import json
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

# Rebuild everything (default)
response = client.start_index_rebuild()

# Rebuild quad indexes only
response = client.start_index_rebuild(Scope='QUADS')

# Rebuild with 4 workers and a high write buffer
response = client.start_index_rebuild(
    Scope='ALL',
    Concurrency=4,
    WriteBufferSize='HIGH'
)

print(json.dumps(response, indent=2, default=str))

awscurl

# Rebuild everything (default)
awscurl https://your-neptune-endpoint:port/storage/indexes/rebuilds \
  --region us-east-1 \
  --service neptune-db \
  -X POST

# Rebuild quad indexes only
awscurl "https://your-neptune-endpoint:port/storage/indexes/rebuilds?scope=QUADS" \
  --region us-east-1 \
  --service neptune-db \
  -X POST

# Rebuild with 4 workers and a high write buffer
awscurl "https://your-neptune-endpoint:port/storage/indexes/rebuilds?concurrency=4&writeBufferSize=HIGH" \
  --region us-east-1 \
  --service neptune-db \
  -X POST

Prerequisites

This example assumes that your AWS credentials are configured in your environment. Replace us-east-1 with the Region of your Neptune cluster.

curl

# Rebuild everything (default)
curl -X POST https://your-neptune-endpoint:port/storage/indexes/rebuilds

# Rebuild quad indexes only
curl -X POST "https://your-neptune-endpoint:port/storage/indexes/rebuilds?scope=QUADS"

# Rebuild with 4 workers and a high write buffer
curl -X POST "https://your-neptune-endpoint:port/storage/indexes/rebuilds?concurrency=4&writeBufferSize=HIGH"

A successful request returns HTTP 200 with the initial rebuild state:

{
  "status": "PREPARING",
  "rebuildId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scope": "ALL",
  "concurrency": 1,
  "writeBufferSize": "LOW",
  "startTime": "2026-04-22T22:58:45Z"
}

Save the rebuildId from the response—you use it to query status and to cancel the rebuild. Only one rebuild can run at a time. If you start a rebuild while one is already in progress, you receive a 409 ConflictException.

Errors

The following table lists the errors that StartIndexRebuild can return.

GetIndexRebuildStatus

Returns the status and progress of a rebuild operation. Send an HTTP GET request with the rebuildId appended to the path.

AWS CLI

aws neptunedata get-index-rebuild-status \
  --endpoint-url https://your-neptune-endpoint:port \
  --rebuild-id rebuildId

For more information, see get-index-rebuild-status in the AWS CLI Command Reference.

SDK

import boto3
import json
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

response = client.get_index_rebuild_status(
    RebuildId='rebuildId'
)

print(json.dumps(response, indent=2, default=str))

awscurl

awscurl https://your-neptune-endpoint:port/storage/indexes/rebuilds/rebuildId \
  --region us-east-1 \
  --service neptune-db

Prerequisites

This example assumes that your AWS credentials are configured in your environment. Replace us-east-1 with the Region of your Neptune cluster.

curl

curl -G https://your-neptune-endpoint:port/storage/indexes/rebuilds/rebuildId

The response reports the current state of the rebuild:

{
  "status": "REBUILDING",
  "rebuildId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scope": "ALL",
  "concurrency": 1,
  "writeBufferSize": "LOW",
  "startTime": "2026-04-22T02:00:05Z",
  "estimatedEndTime": "2026-04-23T02:00:05Z",
  "progressPercentage": 45
}

The response contains the following fields:

Errors

The following table lists the errors that GetIndexRebuildStatus can return.

ListIndexRebuilds

Returns the list of rebuild operation IDs. Send an HTTP GET request to the /storage/indexes/rebuilds endpoint.

AWS CLI

aws neptunedata list-index-rebuilds \
  --endpoint-url https://your-neptune-endpoint:port

For more information, see list-index-rebuilds in the AWS CLI Command Reference.

SDK

import boto3
import json
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

response = client.list_index_rebuilds()

print(json.dumps(response, indent=2, default=str))

awscurl

awscurl https://your-neptune-endpoint:port/storage/indexes/rebuilds \
  --region us-east-1 \
  --service neptune-db

Prerequisites

This example assumes that your AWS credentials are configured in your environment. Replace us-east-1 with the Region of your Neptune cluster.

curl

curl -G https://your-neptune-endpoint:port/storage/indexes/rebuilds

The response contains a rebuildIds array. Use each ID with GetIndexRebuildStatus to retrieve detailed status.

{
  "rebuildIds": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ]
}

Errors

The following table lists the errors that ListIndexRebuilds can return.

CancelIndexRebuild

Cancels an in-progress rebuild. Send an HTTP POST request to the cancel sub-resource of the rebuild.

AWS CLI

aws neptunedata cancel-index-rebuild \
  --endpoint-url https://your-neptune-endpoint:port \
  --rebuild-id rebuildId

For more information, see cancel-index-rebuild in the AWS CLI Command Reference.

SDK

import boto3
import json
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

response = client.cancel_index_rebuild(
    RebuildId='rebuildId'
)

print(json.dumps(response, indent=2, default=str))

awscurl

awscurl https://your-neptune-endpoint:port/storage/indexes/rebuilds/rebuildId/cancel \
  --region us-east-1 \
  --service neptune-db \
  -X POST

Prerequisites

This example assumes that your AWS credentials are configured in your environment. Replace us-east-1 with the Region of your Neptune cluster.

curl

curl -X POST https://your-neptune-endpoint:port/storage/indexes/rebuilds/rebuildId/cancel

The CancelIndexRebuild API makes a best-effort attempt to cancel the rebuild. When you call it, the rebuild transitions to CANCELLING status. During this phase, work that is already in progress must finish before the rebuild reaches CANCELLED status. This can take from minutes to hours depending on what is currently in flight. If the rebuild is still in PREPARING (no work has started), it transitions directly to CANCELLED. Your database remains fully operational throughout.

{
  "status": "CANCELLING",
  "rebuildId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scope": "ALL",
  "concurrency": 1,
  "writeBufferSize": "LOW",
  "startTime": "2026-04-22T02:00:05Z",
  "estimatedEndTime": "2026-04-22T22:00:00Z",
  "progressPercentage": 37
}

Errors

The following table lists the errors that CancelIndexRebuild can return.

Status lifecycle

The following description shows the possible state transitions from initiation through completion or cancellation:

A rebuild starts in PREPARING. From PREPARING, it either transitions directly to CANCELLED (if you cancel before any work starts) or advances to REBUILDING. From REBUILDING, the rebuild can complete successfully (COMPLETED), fail (FAILED), or enter CANCELLING. A CANCELLING rebuild eventually reaches CANCELLED.

Storage safety mechanisms

The online index rebuild includes built-in safety mechanisms to prevent storage exhaustion during the rebuild process:

If your cluster exceeds 100 TB and you need to run an index rebuild, contact AWS Support to open a case with the Neptune team. We can review your cluster's size, growth rate, and workload, and work with you to plan the rebuild safely. Depending on the situation, we might recommend running the rebuild at reduced concurrency to lower scratch-space needs, scoping the rebuild to only the indexes that need it (scope=QUADS or scope=DICTIONARIES), or scheduling it during a lower-traffic window.

Typical workflow

Use the following workflow to assess and optimize your Neptune storage.

Best practices

Limitations

Frequently asked questions

Does the index rebuild take my database offline?

No. During an online index rebuild, you can run concurrent read and write queries. Your database remains fully operational throughout the rebuild, regardless of the scope you specify.

Does the index rebuild support the OSGP and PZSOG indexes?

Yes. If you have the OSGP index and/or the PZSOG index (for geospatial data) enabled, the rebuild rebuilds them too when scope is ALL or QUADS.

How long does an index rebuild take?

The duration depends on the total size of your indexes and the volume of write operations during the rebuild, because those writes must be reapplied to the new indexes as well. You can monitor progress with GetIndexRebuildStatus, which provides progressPercentage and estimatedEndTime. Under heavy concurrent write activity, estimatedEndTime might not be accurate.

Will I lose data during the rebuild?

No. The online rebuild is designed to preserve all data. Concurrent writes during the rebuild are committed normally.

What happens if the rebuild fails?

Your database remains fully operational. GetIndexRebuildStatus shows status=FAILED with a failureReason. Common failure causes include:

After investigating the cause, you can start a new rebuild.

A writer restart or failover does not produce a FAILED status. In those cases, Neptune loses the in-progress rebuild and its record, so GetIndexRebuildStatus returns ResourceNotFoundException for that rebuildId. For details, see What happens if my engine restarts during a rebuild? and What happens if a failover occurs during the rebuild?

Can I cancel a rebuild?

Yes. Use the CancelIndexRebuild API. Cancellation is best-effort— in-flight work must drain before the rebuild reaches CANCELLED. Your database remains operational throughout.

What happens if my engine restarts during a rebuild?

The rebuild stops, and the engine restart discards its progress and rebuildId. Your database recovers to normal operation, and you can start a new rebuild.

What happens if a failover occurs during the rebuild?

If a failover switches the writer to a read replica during an active rebuild, the in-progress rebuild is lost. The new writer is healthy and fully operational, and you can start a new rebuild after the failover completes.

Can I run other Neptune APIs during the rebuild?

Yes for most APIs. GetStorageInfo, the query APIs (Gremlin, openCypher, SPARQL), and export continue to work. The bulk load API (POST /loader) and the fast reset API (ExecuteFastReset) are rejected during a rebuild.

How often should I run an index rebuild?

Consider running a rebuild when you observe significant storage bloat (through GetStorageInfo) or degraded query performance after heavy delete operations. Quarterly reviews are a reasonable starting point, but the optimal frequency depends on your workload patterns.

Does the rebuild affect my read replicas?

No. Read replicas are not affected by the rebuild and continue to serve read queries normally.

My cluster only receives read queries—should I clone it, run the rebuild on the clone, and switch to the clone?

Cloning is a valid alternative only if you can pause all writes to the original cluster for the duration of the rebuild, or the cluster has no writes at all. Neptune does not replicate to the clone any writes made to the original cluster after the clone point — those writes are lost when you switch to the clone as your new primary. For workloads with ongoing writes, run the rebuild online on the primary instead.

If you can pause writes, follow this approach:

For more information about cluster cloning, see Database Cloning in Neptune.

Why does the rebuild take longer, or why do my queries slow down, when other workloads run at the same time?

The rebuild relies heavily on the buffer cache and I/O, so it competes for those resources with your other workloads. Monitor the BufferCacheHitRatio CloudWatch metric, which is the percentage of requests served by the buffer cache. If the cache hit ratio drops under 99.9%, consider upgrading the instance type to cache more data in memory, or reduce the concurrency of the rebuild to lessen competition with other workloads.