本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
海王星在线索引重建
通过在线索引重建,您可以在数据库保持完全运行的同时,对 Neptune 索引进行碎片整理并回收未使用的存储空间。这使您可以在不使数据库离线的情况下优化存储成本并提高查询性能。随着时间的推移,插入、更新和删除操作会在数据页中产生未使用空间的空白,从而使索引碎片化。碎片化保持 VolumeBytesUsed 即使删除数据,指标仍然很高。它也会增加 I/O 成本,因为相同的逻辑数据分布在更多的物理存储页面上。联机索引重建可压缩索引以回收此空间并减少碎片化。
在联机重建期间,您的数据库保持完全可用。你可以继续在 Gremlin、OpenCypher 和 SPARQL 中运行并发读写查询。
您可以重建所有索引(四边形和字典),只能重建四边形索引,也可以只重建字典索引。在线索引重建 API 从 Neptune 引擎版本 1.5.0.0 开始可用。
先决条件
引擎版本
在线索引重建 API 需要海王星引擎版本 1.5.0.0 或更高版本。
作家实例
您必须在写入器实例上启动重建,并且写入器必须是预置实例。Neptune 无服务器写入器实例不支持在线索引重建。只读副本不受重建的影响,可以是无服务器的,也可以是预置的。
IAM 权限
如果您的集群使用 IAM 身份验证,则附加到请求主体的 IAM 策略必须允许索引重建操作:
{ "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>/*" }
有关数据平面 IAM 操作的更多信息,请参阅 用于在 Amazon Neptune 中访问数据的 IAM 操作。
何时使用
在大量数据删除(从查询或字典垃圾回收中)之后,当
VolumeBytesUsed尽管数据较少,但仍保持较高水平。当您的数据库接近存储限制并且需要回收空间时。
定期维护(例如,每季度或每年)以保持索引优化。
重建期间会发生什么:
您的数据库保持在线状态。读取查询和写入查询继续在写入器实例上运行。只读副本不受影响。
短暂的查询错误是可能的。在重建期间,某些查询可能会因可重试而失败
CancelledByMaintenanceException。您的应用程序必须捕获此异常,将其视为异常ConcurrentModificationException,然后使用指数退避重试。可能会对性能产生很小的影响 在查询中。重建会争夺缓冲区缓存等资源 I/O。
海王星在重建期间拒绝批量加载 API 调用。如果你打电话给 批量加载 API (
POST /loader) 索引重建正在进行时,请求失败并显示CancelledByMaintenanceException。使用取消重建CancelIndexRebuild然后等待它到达CANCELLED,或者等待重建完成,然后重试加载。海王星在重建期间拒绝快速重置 API 调用。给... 打个电话 快速重置 API (
ExecuteFastReset) 失败CancelledByMaintenanceException索引重建正在进行中。使用取消重建CancelIndexRebuild然后等待它到达CANCELLED,或者等待重建完成,然后重试。
API 参考
在线索引重建包括四个 API: StartIndexRebuild, GetIndexRebuildStatus, ListIndexRebuilds,以及 CancelIndexRebuild。所有这些都必须发送到写入器实例。有关每个操作的完整请求和响应成员,请参阅 海王星数据平面 API 参考。
StartIndexRebuild
启动重建操作。发送 HTTP POST 向 /storage/indexes/rebuilds 终点。
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
该请求接受以下可选查询参数:
-
scope—重建的范围。类型:字符串。有效值:
ALL(四边形和字典),QUADS(仅限四边形索引),或DICTIONARIES(仅限字典索引)。默认值:ALL。 -
concurrency— 用于重建的并行工作人员的数量。类型:整数。有效值: 介于两者之间的整数
1以及写入器实例类型上可用的最大 vCPU 数量。如果该值超过可用 vCPU 的最大值,Neptune 会将其限制为最大值,而不是返回错误。默认值:1。如果您的工作负载很大,请使用较低的并发度来减少与其他工作负载的争用。
-
writeBufferSize— 控制在重建期间跟踪并发写入操作的缓冲区的大小。如果数据库在重建期间写入流量很高,则更大的缓冲区有助于防止操作因缓冲区溢出而失败。类型:字符串。有效值:
LOW(轻度至中度写入活动),MEDIUM(持续写入流量),或HIGH(繁重的写入工作负载)。默认值:LOW。
以下示例显示了几种开始重建的方法:
成功的请求将返回具有初始重建状态的 HTTP 200:
{ "status": "PREPARING", "rebuildId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "scope": "ALL", "concurrency": 1, "writeBufferSize": "LOW", "startTime": "2026-04-22T22:58:45Z" }
保存 rebuildId 从响应中——你可以用它来查询状态和取消重建。一次只能运行一次重建。如果您在重建已在进行时开始重建,则会收到 409 ConflictException。
错误
下表列出了以下错误 StartIndexRebuild 可以返回。
| HTTP 状态 | 错误代码 | 说明 |
|---|---|---|
| 400 | InvalidParameterException | 一个或多个参数无效。 |
| 409 | ConflictException | 此数据库的重建已在进行中。 |
| 429 | ThrottlingException | 由于请求限制而导致请求被拒绝。 |
| 500 | InternalServerException | 出现内部服务错误。 |
GetIndexRebuildStatus
返回重建操作的状态和进度。发送 HTTP GET 向... 申请 rebuildId 附加到路径中。
响应报告重建的当前状态:
{ "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 }
响应包含以下字段:
| 字段 | 说明 |
|---|---|
status | 当前状态: PREPARING, REBUILDING, COMPLETED, FAILED, CANCELLING,或 CANCELLED。 |
rebuildId | 重建操作 (UUID) 的唯一标识符。 |
scope | 重建的范围 (ALL, QUADS,或 DICTIONARIES)。 |
concurrency | 重建操作的并发性。 |
writeBufferSize | 重建操作的写入缓冲区大小 (LOW, MEDIUM,或 HIGH)。 |
startTime | 重建开始时 (ISO-8601)。 |
estimatedEndTime | 预计完成时间 (ISO-8601)。期间出席 REBUILDING 和 CANCELLING。 |
endTime | 当重建达到终端状态时 (ISO-8601)。礼物给 COMPLETED, FAILED,或 CANCELLED。 |
progressPercentage | 重建完成的百分比 (0—100)。 |
failureReason | 失败的原因。仅在以下情况下出现 status 是 FAILED。 |
错误
下表列出了以下错误 GetIndexRebuildStatus 可以返回。
| HTTP 状态 | 错误代码 | 说明 |
|---|---|---|
| 404 | ResourceNotFoundException | 找不到重建 ID。 |
| 429 | ThrottlingException | 由于请求限制而导致请求被拒绝。 |
| 500 | InternalServerException | 出现内部服务错误。 |
ListIndexRebuilds
返回重建操作 ID 的列表。发送 HTTP GET 向 /storage/indexes/rebuilds 终点。
该响应包含 rebuildIds 数组。使用每个 ID GetIndexRebuildStatus 检索详细状态。
{ "rebuildIds": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }
仅保留最新的重建版本。有关更多信息,请参阅 限制。
错误
下表列出了以下错误 ListIndexRebuilds 可以返回。
| HTTP 状态 | 错误代码 | 说明 |
|---|---|---|
| 429 | ThrottlingException | 由于请求限制而导致请求被拒绝。 |
| 500 | InternalServerException | 出现内部服务错误。 |
CancelIndexRebuild
取消正在进行的重建。发送 HTTP POST 向 cancel 重建的子资源。
这个 CancelIndexRebuild API 尽最大努力取消重建。当你调用它时,重建会过渡到 CANCELLING 状态。在此阶段,已经在进行的工作必须在重建之前完成 CANCELLED 状态。这可能需要几分钟到几小时,具体取决于当前的飞行情况。如果重建仍在进行中 PREPARING (尚未开始工作),它直接过渡到 CANCELLED。您的数据库始终保持全面运行。
{ "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 }
错误
下表列出了以下错误 CancelIndexRebuild 可以返回。
| HTTP 状态 | 错误代码 | 说明 |
|---|---|---|
| 400 | InvalidParameterException | 重建未处于可取消状态(例如,它已经处于可取消状态) COMPLETED, FAILED,或 CANCELLED)。 |
| 404 | ResourceNotFoundException | 找不到重建 ID。 |
| 429 | ThrottlingException | 由于请求限制而导致请求被拒绝。 |
| 500 | InternalServerException | 出现内部服务错误。 |
状态生命周期
以下描述显示了从启动到完成或取消可能的状态转换:
重建开始于 PREPARING。来自 PREPARING,它要么直接过渡到 CANCELLED (如果你在任何工作开始之前取消)或前进到 REBUILDING。来自 REBUILDING,重建可以成功完成 (COMPLETED)、失败 (FAILED),或者输入 CANCELLING。一个 CANCELLING 重建终于到了 CANCELLED。
PREPARING—重建正在初始化。REBUILDING—正在积极重建索引表。您的数据库保持全面运行。COMPLETED— 重建成功完成。FAILED—重建遇到错误。您的数据库已全面运行。检查failureReason了解详情。CANCELLING—有人要求取消,但机上工作正在耗尽。这可能需要几分钟到几小时,具体取决于当前的飞行情况。CANCELLED— 重建已取消。您的数据库已全面运行。
存储安全机制
在线索引重建包括内置的安全机制,可防止在重建过程中存储空间耗尽:
带有安全余量的存储预算。重建将80%的安全余量应用于可用体积空间。重建在运行时还需要额外的暂存空间。在最大并发度下,这大约占正在重建的数据的25%;在较低的并发度下,该数量会成比例地减少。预算为这个暂存空间以及重建期间发生的并发写入和事务日志增长预留了余地。
自适应调度。重建过程会持续检查有多少可用体积空间,并相应地调整其并行度。当可用空间紧张时,重建速度会减慢以减少峰值存储消耗。当有更多可用空间时,重建将并行运行更多工作以更快地完成。
Fail-fast 存储空间耗尽时。如果在所有机上工作完成且预算更新后重建无法进行,则重建将立即失败。海王星设定了
failureReason留言给Insufficient storage to perform index rebuild。重建不会静默地跳过工作。100 TB 的默认限制。默认情况下,大于 100 TB 的集群上的索引重建请求会立即失败
VolumeBytesUsed。此限制是一种安全预防措施。在大型集群上进行重建可能需要大量的额外暂存空间(在最大并发性下重建的数据约占大约 25%)。这可能会使集群接近或超过其存储限制。
如果您的集群超过 100 TB 并且需要运行索引重建,请联系 Amazon
支持向海王星团队提起诉讼。我们可以审查您的集群的大小、增长率和工作负载,并与您一起安全地规划重建。视情况而定,我们可能会建议以较低的并发度运行重建以降低暂存空间需求,将重建范围限定为仅限需要重建的索引(scope=QUADS 要么 scope=DICTIONARIES),或者将其安排在流量较低的时段。
典型的 工作流程
使用以下工作流程来评估和优化 Neptune 存储。
-
评估存储使用情况。打电话 GetStorageInfo 了解您当前的存储分布,并寻找与条目数量相关的较大索引大小,这表明存在碎片性。注意当前
VolumeBytesUsed以值为基准。 -
开始重建索引。如果您发现碎片或膨胀,请启动重建并保存
rebuildId来自回应。 -
监控进度。定期轮询重建状态。这个
progressPercentage实地跑道完成以及estimatedEndTime估计重建何时完成。 -
验证结果。重建完成后,调用
GetStorageInfo再次确认存储大小减少了。你也可以跟踪VolumeBytesUsed和VolumeBytesLeftTotalCloudWatch 一段时间内的指标。
最佳实践
实现重试逻辑。在重建期间,某些查询可能会暂时失败
CancelledByMaintenanceException,你应该像对待一样对待它ConcurrentModificationException。使用指数退避重试失败的查询。监控进度。民意调查
GetIndexRebuildStatus跟踪进度和预计完成时间。跑 GetStorageInfo 之前和之后。这使您可以量化回收的空间并跟踪一段时间内的存储效率。你也可以跟踪
VolumeBytesUsed和VolumeBytesLeftTotalCloudWatch 重建期间的指标。将范围定向到容纳可回收空间的组件。使用 GetStorageInfo 查看您的四边形索引或字典是否占据了最大的可回收空间,然后仅使用以下命令重建该组件
scope=QUADS要么scope=DICTIONARIES实现更快、影响更小的重建。使用scope=ALL仅当两者都需要优化时。调整并发性以平衡速度和工作负载影响。更高
concurrency更快地完成。但是,它争夺缓冲区缓存的竞争要激烈得多 I/O。这种竞争会明显减慢您的并发查询速度。从低并发度开始(默认为1) 当重建与生产流量一起运行时,并仅在您有备用实例容量或在维护时段内运行时才增加重建。考虑写入缓冲区的大小。如果在重建期间写入工作量很大,请使用
writeBufferSize=HIGH这样就可以跟踪所有写入工作负载并将其应用于重建的索引。考虑在重建期间扩大写入器实例。重建在较大的写入器实例上运行得更快,因为并行工作程序使用可用的 vCPU 进行扩展,而更大的缓冲池会减少 I/O 当图表超过较小实例的池大小时。如果挂钟时间很重要,请在重建期间暂时使用更大的写入器,之后再缩小规模。
计划取消。取消是尽力而为。当你打电话时
CancelIndexRebuild,已经在进行的工作必须在重建之前完成CANCELLED状态。这所花费的时间可能从几分钟到几小时不等,具体取决于当前的飞行情况。
限制
一次重建一次。每个集群一次只能运行一次索引重建。
暂时查询失败。在重建的短暂内部提交阶段,某些查询可能会失败并导致可重试
CancelledByMaintenanceException。使用指数退避实现重试逻辑。重建历史。当前,内存中只保留最新的重建版本。计划在未来的版本中发布永久重建历史记录。如果引擎重新启动或崩溃,则最新的重建记录将丢失。
限制为 100 TB。如果您的集群超过
VolumeBytesUsed100 TB,请联系 Amazon 支持与海王星团队协调索引重建。预计结束时间为近似值。这个
estimatedEndTime返回者GetIndexRebuildStatus是尽力而为的估计值。实际完成时间可能因数据大小、并发工作负载和存储条件而异。具有更大缓冲池的写入器实例可以更快地完成重建。极其繁重的工作负载可能会导致重建失败。非常繁重的并发工作负载(通过读取或写入查询)可能导致重建失败,这要么是由于对缓冲区缓存等硬件资源的激烈争用,以及 I/O,或者因为写入缓冲区已满。要解决这个问题,请减少工作量,或者缩小重建的范围和并发性并提高重建量
writeBufferSize(直到HIGH最大)。如果重建仍然失败writeBufferSize=HIGH,减少并发写入工作负载,或者在流量较低的时段内运行重建。
常见问题
索引重建会使我的数据库脱机吗?
不是。在联机索引重建期间,您可以运行并发读写查询。无论如何,在整个重建过程中,您的数据库都将保持全面运行 scope 你指定。
索引重建是否支持 OSGP 和 PZSOG 索引?
是。如果你有 OSGP 索引 and/or 启用 PZSOG 索引(用于地理空间数据),在以下情况下重建也会对其进行重建 scope 是 ALL 要么 QUADS。
索引重建需要多长时间?
持续时间取决于索引的总大小和重建期间的写入操作量,因为这些写入也必须重新应用于新索引。您可以通过以下方式监控进度 GetIndexRebuildStatus,它提供了 progressPercentage 和 estimatedEndTime。在繁忙的并发写入活动下, estimatedEndTime 可能不准确。
重建期间我会丢失数据吗?
不是。在线重建旨在保留所有数据。重建期间的并发写入操作通常会提交。
如果重建失败会发生什么?
您的数据库保持全面运行。 GetIndexRebuildStatus 节目 status=FAILED 用 failureReason。常见的故障原因包括:
存储空间不足。该体积无法提供足够的暂存空间来在其安全范围内进行重建。请参阅存储安全机制。
写入缓冲区溢出。重建期间持续的非常繁重的写入工作负载可能会耗尽跟踪更改的内部缓冲区。增加
writeBufferSize(最多HIGH) 或者减少并发写入工作负载并重试。
调查原因后,您可以开始新的重建。
写入器重启或故障转移不会产生 FAILED 状态。在这种情况下,海王星会丢失正在进行的重建及其记录,所以 GetIndexRebuildStatus 回报 ResourceNotFoundException 为此 rebuildId。有关详细信息,请参见 如果我的发动机在重建期间重新启动会怎样? 和 如果在重建期间发生故障转移会怎样?
我可以取消重建吗?
是。使用 CancelIndexRebuild API。取消是尽最大努力——机上工作必须在重建完成之前耗尽 CANCELLED。您的数据库始终保持运行状态。
如果我的发动机在重建期间重新启动会怎样?
重建停止,引擎重启会丢弃其进度, rebuildId。您的数据库恢复到正常运行,您可以开始新的重建。
如果在重建期间发生故障转移会怎样?
如果故障转移在主动重建期间将写入器切换到只读副本,则正在进行的重建将丢失。新的写入器运行状况良好且完全可以运行,并且可以在故障转移完成后开始新的重建。
我可以在重建期间运行其他 Neptune API 吗?
是的,对于大多数 API 来说。 GetStorageInfo、查询 API(Gremlin、OpenCypher、SPARQL)和导出功能继续有效。这个 批量加载 API (POST /loader) 和 快速重置 API (ExecuteFastReset) 在重建期间被拒绝。
我应该多久运行一次索引重建?
当您发现存储空间严重膨胀时,可以考虑运行重建(通过 GetStorageInfo) 或者在执行大量删除操作后查询性能降低。季度审查是一个合理的起点,但最佳频率取决于您的工作量模式。
重建会影响我的只读副本吗?
不是。只读副本不受重建的影响,可以继续正常提供读取查询。
我的集群只接收读取查询,我是否应该克隆它,在克隆上运行重建,然后切换到克隆?
只有当你可以在重建期间暂停对原始集群的所有写入操作,或者集群根本没有写入时,克隆才是有效的替代方案。Neptune 不会将克隆点之后对原始集群所做的任何写入操作复制到克隆,当您切换到克隆作为新的主群集时,这些写入操作就会丢失。对于正在进行写入的工作负载,改为在主服务器上在线运行重建。
如果可以暂停写入,请遵循以下方法:
使用 Neptune 快速克隆功能创建集群的时间点副本。
在不影响活动集群的情况下,以您选择的并发度对克隆运行重建。
重建完成后,更新您的应用程序,使其指向克隆的终端节点。
有关集群克隆的更多信息,请参阅 Neptune 中的数据库克隆。
当其他工作负载同时运行时,为什么重建需要更长的时间,或者为什么我的查询速度会变慢?
重建在很大程度上依赖缓冲区缓存和 I/O,因此它会与您的其他工作负载争夺这些资源。监控 BufferCacheHitRatio CloudWatch 指标,这是缓冲区缓存所服务的请求的百分比。如果缓存命中率降至 99.9% 以下,请考虑升级实例类型以在内存中缓存更多数据,或者减少重建的并发性以减少与其他工作负载的竞争。