

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

# 快速批量加载（离线加载器）

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

## 何时使用离线加载器
<a name="bulk-load-offline-when"></a>

在以下情况下使用离线加载器 *所有* 以下是正确的：
+ 你正在加载 Gremlin CSV 数据。
+ 目标图形为空，或者你愿意在加载之前完全重置图形。
+ 数据集足够大，负载吞吐量比增量写入可用性更重要。
+ 您的源数据很干净。如果出现任何参照或基数冲突，离线加载器会使整个加载失败。
+ 您可以接受 Neptune 在加载期间阻止读取和写入查询。

使用 [标准批量装载机](bulk-load.md) 当以下任何一项适用时：
+ 你正在加载 RDF， openCypher，或地理空间数据。
+ 你需要追加到现有的非空图中。
+ 你需要恢复之前失败的加载 (`mode=RESUME`）。
+ 你需要对多个加载任务进行排队 (`queueRequest=TRUE`）。
+ 你需要覆盖单基数属性值 (`updateSingleCardinalityProperties=TRUE`）。
+ 您的源数据可能包含错误（例如，重复的边 ID 或缺少顶点引用），您希望跳过这些行，而不是将其视为致命行。

## 先决条件和限制
<a name="bulk-load-offline-prerequisites"></a>

### 引擎版本
<a name="bulk-load-offline-engine-version"></a>

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

### 实例要求
<a name="bulk-load-offline-instance-requirements"></a>

离线加载器具有以下实例要求：
+ 仅使用预置实例。离线加载器不支持无服务器实例。
+ 使用大型实例类型（例如， `db.r6i.12xlarge` 或更大）以避免内存不足故障。离线加载器使用实例上所有可用的 vCPU 和内存。
+ 使用 [海王星 I/O-Optimized 存储](https://docs.amazonaws.cn/neptune/latest/userguide/storage-types.html#provisioned-iops-storage) 以提高大负载的成本效益。

### 限制
<a name="bulk-load-offline-limitations"></a>

离线加载器有以下限制：
+ **Gremlin 仅限 CSV** — 离线加载器仅支持 Gremlin CSV 格式。它不支持 openCypher、RDF 或地理空间格式。
+ **没有压缩文件** — 离线加载器不支持压缩源文件。提供未压缩的 Gremlin CSV 文件。
+ **需要空图** — 目标图表必须为空。使用 `fast reset` 在加载之前清除图表。
+ **一次装载一次** — 每个集群只能运行一个离线负载。海王星拒绝并发加载请求。
+ **没有简历** — 您无法恢复失败的加载。重置图表并从头开始重新启动加载。
+ **没有并行度控制** — 离线加载器始终使用所有可用的 vCPU。它不支持 `parallelism` 参数。如果您将请求包括在内，海王星会拒绝该请求。
+ **查询已屏蔽** — 当离线加载进行时，Neptune 会阻止读写查询。
+ **All-or-nothing 语义学** — 违反参照完整性、重复的边缘 ID 和单基数冲突导致整个加载失败。海王星不保留任何部分数据。

## 开始离线加载
<a name="bulk-load-offline-start"></a>

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

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

```json
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`。

以下示例显示了响应：

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

## 监控离线负载
<a name="bulk-load-offline-monitor"></a>

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

```json
{
  "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` 对象仅在加载过程中出现。在负载达到终端状态后，海王星将其移除。

### 加载阶段
<a name="bulk-load-offline-phases"></a>

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


| 阶段 | 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](load-api-reference-status.md)。

## 离线加载器与标准加载器有何不同
<a name="bulk-load-offline-comparison"></a>

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


| 能力 | 标准散装装载机 | 离线加载器 | 
| --- | --- | --- | 
| 支持的数据格式 | 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 会触发统计数据收集。统计数据可能需要几分钟才能公布。 | 

## 错误处理
<a name="bulk-load-offline-errors"></a>

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

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


| 错误代码 | 阶段 | 说明 | 
| --- | --- | --- | 
| FROM\_OR\_TO\_VERTEX\_ARE\_MISSING | INDEXING | 边引用的顶点 ID 不存在于输入数据中。 | 
| ID\_ASSIGNED\_TO\_MULTIPLE\_EDGES | INDEXING | 两条或多条边共享相同的边缘 ID。 | 
| SINGLE\_CARDINALITY\_VIOLATION | INDEXING | 用单基数声明的属性在同一个顶点上有多个值。 | 
| PARSING\_ERROR | PARSING |  + 字符串属性值以内部命名空间前缀开头，离线加载器目前不支持该前缀。<br />+ 数据类型转换失败，例如中的非数字值 `Int` 专栏。  | 

其他解析错误（例如，格式错误的 CSV 行或超过 55 MB 大小限制的值）的处理依据是 `failOnError` 参数:
+ `failOnError=TRUE` — 任何解析错误都会立即中止加载。
+ `failOnError=FALSE` — Neptune 记录解析错误并跳过受影响的行。继续加载剩余的数据。

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

## 最佳实践
<a name="bulk-load-offline-best-practices"></a>
+ **加载前验证数据** — 在开始加载之前验证您的数据。如果离线加载器检测到完整性违规，则会使整个加载失败。确保所有优势 `~from` 和 `~to` 值引用输入中存在的顶点 ID，边 ID 是唯一的，单基数属性的每个顶点只有一个值。
+ **使用大型实例** — 离线加载器使用所有可用内存和 vCPU。更大的实例（例如， `db.r6i.12xlarge` 或更大）可以更快地加载数据，并避免大型数据集出现内存不足故障。
+ **重试之前使用快速重置** — 如果加载失败，请使用 `fast reset` 在重试之前清除图形。离线加载器需要一个空图。
+ **监控阶段进展** — 民意调查 `GET /loader/{{loadId}}` 跟踪负载处于五个阶段中的哪个阶段。这个 `INDEXING` 阶段是检测到数据完整性违规行为的地方，因此此阶段的故障表示存在数据质量问题。
+ **分离顶点和边缘文件** — 使用顶点文件和边缘文件在不同的前缀下组织您的 Amazon S3 数据。这使得在加载之前更容易验证参照完整性。

**注意**  
对于布尔属性列，离线加载器会处理除以外的任何值 `true` 如同 `false`。有关更多信息，请参阅 [Gremlin 加载数据格式](https://docs.amazonaws.cn/neptune/latest/userguide/bulk-load-tutorial-format-gremlin.html#bulk-load-tutorial-format-gremlin-datatypes)。