View a markdown version of this page

快速批量加载(离线加载器) - Amazon Neptune
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

快速批量加载(离线加载器)

亚马逊 Neptune 离线加载器是标准批量加载器的高性能变体。用它来装大容量的初始负载 Gremlin CSV 数据集。加载器从 Amazon 简单存储服务读取文件,并直接在实例上构建图形索引结构。加载完成后,海王星会以原子方式将新索引交换到位。由于它绕过了每行事务写入路径,因此它加载大型数据集的速度比标准批量加载器快得多。

何时使用离线加载器

在以下情况下使用离线加载器 所有 以下是正确的:

  • 你正在加载 Gremlin CSV 数据。

  • 目标图形为空,或者你愿意在加载之前完全重置图形。

  • 数据集足够大,负载吞吐量比增量写入可用性更重要。

  • 您的源数据很干净。如果出现任何参照或基数冲突,离线加载器会使整个加载失败。

  • 您可以接受 Neptune 在加载期间阻止读取和写入查询。

使用 标准批量装载机 当以下任何一项适用时:

  • 你正在加载 RDF, openCypher,或地理空间数据。

  • 你需要追加到现有的非空图中。

  • 你需要恢复之前失败的加载 (mode=RESUME)。

  • 你需要对多个加载任务进行排队 (queueRequest=TRUE)。

  • 你需要覆盖单基数属性值 (updateSingleCardinalityProperties=TRUE)。

  • 您的源数据可能包含错误(例如,重复的边 ID 或缺少顶点引用),您希望跳过这些行,而不是将其视为致命行。

先决条件和限制

引擎版本

离线加载器需要海王星引擎版本 1.5.0.0 或更高版本。

实例要求

离线加载器具有以下实例要求:

  • 仅使用预置实例。离线加载器不支持无服务器实例。

  • 使用大型实例类型(例如, db.r6i.12xlarge 或更大)以避免内存不足故障。离线加载器使用实例上所有可用的 vCPU 和内存。

  • 使用 海王星 I/O-Optimized 存储 以提高大负载的成本效益。

限制

离线加载器有以下限制:

  • Gremlin 仅限 CSV — 离线加载器仅支持 Gremlin CSV 格式。它不支持 openCypher、RDF 或地理空间格式。

  • 没有压缩文件 — 离线加载器不支持压缩源文件。提供未压缩的 Gremlin CSV 文件。

  • 需要空图 — 目标图表必须为空。使用 fast reset 在加载之前清除图表。

  • 一次装载一次 — 每个集群只能运行一个离线负载。海王星拒绝并发加载请求。

  • 没有简历 — 您无法恢复失败的加载。重置图表并从头开始重新启动加载。

  • 没有并行度控制 — 离线加载器始终使用所有可用的 vCPU。它不支持 parallelism 参数。如果您将请求包括在内,海王星会拒绝该请求。

  • 查询已屏蔽 — 当离线加载进行时,Neptune 会阻止读写查询。

  • All-or-nothing 语义学 — 违反参照完整性、重复的边缘 ID 和单基数冲突导致整个加载失败。海王星不保留任何部分数据。

开始离线加载

用同样的 /loader 端点作为标准批量加载器。添加 "loadType": "offline" 到请求正文选择离线加载器。

以下示例显示了一个请求:

POST https://your-neptune-endpoint:port/loader Content-Type: application/json { "source": "s3://amzn-s3-demo-bucket/graph-data/", "format": "csv", "iamRoleArn": "arn:aws:iam::123456789012:role/NeptuneLoadFromS3", "region": "us-west-2", "loadType": "offline", "failOnError": "TRUE" }

离线加载器支持以下参数:

  • source — 您的数据文件的 Amazon S3 URI。

  • format – 必须为 csv。

  • iamRoleArn — 具有亚马逊 S3 存储桶读取权限的 IAM 角色 ARN。

  • region — Amazon Web Services 区域 亚马逊 S3 存储桶的。

  • loadType — 设置为 offline 使用离线加载器。

  • failOnError — 控制解析错误时的行为。什么时候 TRUE,任何解析错误都会立即中止加载。

以下标准加载器参数是 不 离线加载器支持: parallelism, mode, queueRequest, dependencies, updateSingleCardinalityProperties,以及 edgeOnlyLoad。

以下示例显示了响应:

{ "status": "200 OK", "payload": { "loadId": "ef478d76-d9da-4d94-8ff1-08d9d4863aa5" } }

监控离线负载

用同样的 GET /loader/loadId 端点作为标准批量加载器。在加载过程中,响应中会包含额外的 progress 报告当前阶段的对象。

{ "payload": { "overallStatus": { "status": "LOAD_IN_PROGRESS", "fullUri": "s3://amzn-s3-demo-bucket/graph-data/", "totalRecords": 1234567, "totalDuplicates": 0, "parsingErrors": 0, "insertErrors": 0, "progress": { "phase": "BUILDING_GRAPH", "phaseNumber": 3, "totalPhases": 5 } } } }

这个 progress 对象仅在加载过程中出现。在负载达到终端状态后,海王星将其移除。

加载阶段

离线加载器分五个连续阶段处理数据。

阶段 Name 说明
1 PARSING Neptune 读取源文件并收集独特的字符串。
2 BUILDING_DICTIONARY Neptune 构建了排序后的字符串到标识符字典。
3 BUILDING_GRAPH Neptune 再次读取数据,并使用字典将行转换为图形语句。
4 INDEXING Neptune 对语句进行排序并建立图形索引。在此阶段检测到参照和基数违规。
5 FINALIZING Neptune 以原子方式将新索引交换到位并解除对查询的阻止。

所有其他状态字段 (status, fullUri, totalRecords, totalDuplicates, parsingErrors, insertErrors,以及可用的错误日志 errors=true) 与标准加载器中的含义相同。请参阅海王星装载机 Get-Status API。

离线加载器与标准加载器有何不同

下表比较了离线加载器和标准批量加载器的关键行为。

能力 标准散装装载机 离线加载器
支持的数据格式 Gremlin CSV, openCypher、RDF(nTriples、nQuads、 RDF/XML,乌龟) Gremlin 仅限 CSV
目标图形状态 空或非空(附加) 仅为空。首先重置图形。
并行加载 最多 64 个排队的任务 (queueRequest=TRUE) 每个集群一次加载一次
失败后恢复 是的(mode=RESUME 要么 mode=AUTO) 不支持。重置图形并重新启动加载。
并行度控制 User-configurable 通过 parallelism 不可配置。使用所有可用的 vCPU。
进度报告 仅限 status status 再加一个 progress 有五个阶段的物体
查询加载期间的可用性 您可以在整个加载过程中运行读取和写入查询 海王星在加载期间阻止查询
引用完整性 海王星跳过了每行缺失的顶点引用 整个加载失败了 FROM_OR_TO_VERTEX_ARE_MISSING
重复的边缘 ID 海王星每行跳过重复项 整个加载失败了 ID_ASSIGNED_TO_MULTIPLE_EDGES
Single-cardinality 冲突 海王星每行都会跳过冲突 整个加载失败了 SINGLE_CARDINALITY_VIOLATION
Post-load 统计数据 加载完成后立即可用 加载完成后,Neptune 会触发统计数据收集。统计数据可能需要几分钟才能公布。

错误处理

离线加载器使用全有或全无的语义。如果在此期间检测到任何数据完整性违规行为 INDEXING 阶段,整个加载失败,不保留任何数据。图形返回到其预加载状态(空)。

无论如何,以下错误都会导致整个加载失败 failOnError 设置。

错误代码 阶段 说明
FROM_OR_TO_VERTEX_ARE_MISSING INDEXING 边引用的顶点 ID 不存在于输入数据中。
ID_ASSIGNED_TO_MULTIPLE_EDGES INDEXING 两条或多条边共享相同的边缘 ID。
SINGLE_CARDINALITY_VIOLATION INDEXING 用单基数声明的属性在同一个顶点上有多个值。
PARSING_ERROR PARSING
  • 字符串属性值以内部命名空间前缀开头,离线加载器目前不支持该前缀。

  • 数据类型转换失败,例如中的非数字值 Int 专栏。

其他解析错误(例如,格式错误的 CSV 行或超过 55 MB 大小限制的值)的处理依据是 failOnError 参数:

  • failOnError=TRUE — 任何解析错误都会立即中止加载。

  • failOnError=FALSE — Neptune 记录解析错误并跳过受影响的行。继续加载剩余的数据。

使用 GET /loader/loadId?errors=true 在加载失败后检索详细的错误信息。

最佳实践

  • 加载前验证数据 — 在开始加载之前验证您的数据。如果离线加载器检测到完整性违规,则会使整个加载失败。确保所有优势 ~from 和 ~to 值引用输入中存在的顶点 ID,边 ID 是唯一的,单基数属性的每个顶点只有一个值。

  • 使用大型实例 — 离线加载器使用所有可用内存和 vCPU。更大的实例(例如, db.r6i.12xlarge 或更大)可以更快地加载数据,并避免大型数据集出现内存不足故障。

  • 重试之前使用快速重置 — 如果加载失败,请使用 fast reset 在重试之前清除图形。离线加载器需要一个空图。

  • 监控阶段进展 — 民意调查 GET /loader/loadId 跟踪负载处于五个阶段中的哪个阶段。这个 INDEXING 阶段是检测到数据完整性违规行为的地方,因此此阶段的故障表示存在数据质量问题。

  • 分离顶点和边缘文件 — 使用顶点文件和边缘文件在不同的前缀下组织您的 Amazon S3 数据。这使得在加载之前更容易验证参照完整性。

注意

对于布尔属性列,离线加载器会处理除以外的任何值 true 如同 false。有关更多信息,请参阅 Gremlin 加载数据格式。