Neptune 加载程序命令

将 Amazon S3 桶中的数据加载到 Neptune 数据库实例中。

要加载数据，必须将 HTTP POST 请求发送到 https://your-neptune-endpoint:port/loader 终端节点。loader 请求的参数可在 POST 正文中或作为 URL 编码的参数发送。

重要

MIME 类型必须为 application/json。

S3 存储桶必须与集群位于同一 AWS 区域。

注意

在使用 Amazon S3 SSE-S3 模式加密数据的情况下，您可从 Amazon S3 加载加密数据。在这种情况下，Neptune 能够模拟您的凭证并代表您发出 s3:getObject 调用。

只要您的 IAM 角色包括访问 AWS KMS的必要权限，您还可以从 Amazon S3 加载使用 SSE-KMS 模式加密的加密数据。如果没有适当的 AWS KMS 权限，批量加载操作将失败并返回LOAD_FAILED响应。

Neptune 目前不支持加载使用 SSE-C 模式加密的 Amazon S3 数据。

您不必等到一个加载任务完成后再开始另一个加载任务。Neptune 可以一次对多达 64 个任务请求进行排队，前提是它们的 queueRequest 参数全部设置为 "TRUE"。任务的队列顺序将是 first-in-first-out (FIFO)。另一方面，如果您不希望对某个加载任务排队，则可以将其 queueRequest 参数设置为 "FALSE"（默认值），这样，如果另一个加载任务已在进行中，该加载任务将失败。

您可以使用 dependencies 参数对只有在队列中指定的先前作业成功完成后才能运行的作业进行排队。如果执行此操作，并且这些指定的任何作业失败，则您的作业将不会运行，其状态将设置为 LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED。

Neptune 加载程序请求语法


{
  "source" : "string",
  "format" : "string",
  "iamRoleArn" : "string",
  "mode": "NEW|RESUME|AUTO",
  "region" : "us-east-1",
  "failOnError" : "string",
  "parallelism" : "string",
  "parserConfiguration" : {
    "baseUri" : "http://base-uri-string",
    "namedGraphUri" : "http://named-graph-string"
  },
  "updateSingleCardinalityProperties" : "string",
  "queueRequest" : "TRUE",
  "dependencies" : ["load_A_id", "load_B_id"]
}

Neptune 加载程序请求参数

source – Amazon S3 URI。

SOURCE 参数接受标识单个文件、多个文件、一个文件夹或多个文件夹的 Amazon S3 URI。Neptune 将每个数据文件加载到任何指定的文件夹中。

URI 可以采用以下任意格式。
- s3://bucket_name/object-key-name
- https://s3.amazonaws.com/bucket_name/object-key-name
- https://s3.us-east-1.amazonaws.com/bucket_name/object-key-name
URI 的object-key-name元素等同于 Amazon S3 ListObjectsAPI 调用中的前缀参数。它可以识别指定的 Amazon S3 桶中名称以该前缀开头的所有对象。可以是单个文件或文件夹，也可以是多个文件和/或文件夹。

指定的一个或多个文件夹可以包含多个顶点文件和多个边缘文件。

例如，如果您在名为的 Amazon S3 存储桶中有以下文件夹结构和文件bucket-name：
```
s3://bucket-name/a/bc
s3://bucket-name/ab/c
s3://bucket-name/ade
s3://bucket-name/bcd
```
如果将 source 参数指定为s3://bucket-name/a，则将加载前三个文件。
```
s3://bucket-name/a/bc
s3://bucket-name/ab/c
s3://bucket-name/ade
```
format – 数据的格式。有关 Neptune Loader 命令的数据格式的更多信息，请参阅使用 Amazon Neptune 批量加载程序收集数据。
允许值
- csv 适用于 Gremlin CSV 数据格式。
- opencypher 适用于 openCypher CSV 数据格式。
- ntriples 适用于 N-Triples RDF 数据格式。
- nquads 适用于 N-Quads RDF 数据格式。
- rdfxml 适用于 RDF\XML RDF 数据格式。
- turtle 适用于 Turtle RDF 数据格式。
iamRoleArn – Neptune 数据库实例为访问 S3 桶而代入的 IAM 角色的 Amazon 资源名称 (ARN)。有关创建对 Amazon S3 具有访问权限的角色，然后将其与 Neptune 集群关联的信息，请参阅先决条件：IAM 角色和 Amazon S3 访问权限。

从引擎版本 1.2.1.0.R3 开始，如果 Neptune 数据库实例和 Amazon S3 存储桶位于不同的账户中，您还可以链接多个 IAM 角色。 AWS 在本例中，iamRoleArn 包含一个逗号分隔的角色 ARN 列表，如在 Amazon Neptune 中串联 IAM 角色中所述。例如：
```
curl -X POST https://localhost:8182/loader \
  -H 'Content-Type: application/json' \
  -d '{
        "source" : "s3://(the target bucket name)/(the target date file name)",
        "iamRoleArn" : "arn:aws:iam::(Account A ID):role/(RoleA),arn:aws:iam::(Account B ID):role/(RoleB),arn:aws:iam::(Account C ID):role/(RoleC)",
        "format" : "csv",
        "region" : "us-east-1"
      }'
```
region— 该region参数必须与集群的 AWS 区域和 S3 存储桶相匹配。

Amazon Neptune 在以下区域中推出：
- 美国东部（弗吉尼亚州北部）：us-east-1
- 美国东部（俄亥俄州）：us-east-2
- 美国西部（北加利福尼亚）：us-west-1
- 美国西部（俄勒冈州）：us-west-2
- 加拿大（中部）：ca-central-1
- 南美洲（圣保罗）：sa-east-1
- 欧洲地区（斯德哥尔摩）：eu-north-1
- 欧洲地区（爱尔兰）：eu-west-1
- 欧洲地区（伦敦）：eu-west-2
- 欧洲地区（巴黎）：eu-west-3
- 欧洲地区（法兰克福）：eu-central-1
- 中东（巴林）：me-south-1
- 中东（阿联酋）：me-central-1
- 以色列（特拉维夫）：il-central-1
- 非洲（开普敦）：af-south-1
- 亚太地区（香港）：ap-east-1
- 亚太地区（东京）：ap-northeast-1
- 亚太地区（首尔）：ap-northeast-2
- 亚太地区（大阪）：ap-northeast-3
- 亚太地区（新加坡）：ap-southeast-1
- 亚太地区（悉尼）：ap-southeast-2
- 亚太地区（孟买）：ap-south-1
- 中国（北京）：cn-north-1
- 中国（宁夏）：cn-northwest-1
- AWS GovCloud （美国西部）：us-gov-west-1
- AWS GovCloud （美国东部）：us-gov-east-1
mode – 加载任务模式。

允许的值：RESUME、NEW、AUTO

默认值：AUTO
- RESUME – 在 RESUME 模式下，加载程序查找来自此源的先前加载，如果找到一个加载，则恢复该加载任务。如果未找到之前的加载作业，则加载程序将停止。
  
  加载程序将避免重新加载之前作业中已成功加载的文件。它仅尝试处理失败的文件。如果您从 Neptune 集群中删除了之前加载的数据，则此模式下不加载该数据。如果之前的加载任务成功加载了来自同一源的所有文件，则不会重新加载任何文件，并且加载程序返回成功。
- NEW – 在 NEW 模式下，将创建新的加载请求而不管任何之前的加载。您可以使用此模式在从 Neptune 集群删除之前加载的数据之后从源重新加载数据，或加载同一个源处可用的新数据。
- AUTO – 在 AUTO 模式下，加载程序查找来自此同一个源的先前加载任务，如果找到一个加载任务，则恢复该任务，如同在 RESUME 模式中一样。
  
  如果加载程序没有找到来自同一源的先前加载作业，则会从源加载所有数据，就像在 NEW 模式中一样。
failOnError – 用于在出错时切换为完全停止的标志。

允许的值："TRUE"、"FALSE"。

默认值："TRUE"。

如果此参数设置为 "FALSE"，则加载程序尝试加载指定位置中的所有数据并跳过任何出错的条目。

将此参数设置为 "TRUE" 时，加载程序会在遇到错误时立即停止。截至该点加载的数据仍然存在。
parallelism – 这是一个可选参数，可以设置用于减少批量加载过程使用的线程数。

允许的值：
- LOW – 所使用的线程数是可用 vCPU 数除以 8。
- MEDIUM – 所使用的线程数是可用 vCPU 数除以 2。
- HIGH – 所使用的线程数与可用 vCPU 数相同。
- OVERSUBSCRIBE – 所使用的线程数是可用 vCPU 数乘以 2。如果使用此值，则批量加载程序将占用所有可用资源。
  
  但是，这并不意味着 OVERSUBSCRIBE 设置会导致 100% 的 CPU 利用率。由于负载操作受到 I/O 限制，因此预期的最高 CPU 利用率在 60% 到 70% 之间。
默认值：HIGH

在加载 openCypher 数据时，parallelism 设置有时会导致线程之间出现死锁。发生这种情况时，Neptune 会返回 LOAD_DATA_DEADLOCK 错误。通常，您可以通过将 parallelism 设为较低的设置并重试加载命令来解决此问题。

parserConfiguration – 具有额外解析程序配置值的可选对象。每个子参数也是可选的：

名称示例值描述

namedGraphUri http://aws.amazon.com/neptune/vocab/v01/ DefaultNamed Graph 未指定任何图形时所有 RDF 格式的默认图形（适用于非 quads 格式和无图形的 NQUAD 条目）。默认值为 http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph

baseUri http://aws.amazon.com/neptune/default RDF/XML 和 Turtle 格式的基本 URI。默认值为 http://aws.amazon.com/neptune/default。

名称	示例值	描述
`namedGraphUri`	`http://aws.amazon.com/neptune/vocab/v01/ DefaultNamed Graph`	未指定任何图形时所有 RDF 格式的默认图形（适用于非 quads 格式和无图形的 NQUAD 条目）。默认值为 `http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph`
`baseUri`	`http://aws.amazon.com/neptune/default`	RDF/XML 和 Turtle 格式的基本 URI。默认值为 `http://aws.amazon.com/neptune/default`。
`allowEmptyStrings`	`true`	加载 CSV 数据时，Gremlin 用户需要能够将空字符串值 ("") 作为节点和边缘属性传递。如果 `allowEmptyStrings` 设置为 `false`（默认值），则此类空字符串将视为 null 且不会加载。如果 `allowEmptyStrings` 设置为 `true`，则加载程序会将空字符串视为有效的属性值并相应地加载它们。

allowEmptyStrings

true

加载 CSV 数据时，Gremlin 用户需要能够将空字符串值 ("") 作为节点和边缘属性传递。如果 allowEmptyStrings 设置为 false（默认值），则此类空字符串将视为 null 且不会加载。

如果 allowEmptyStrings 设置为 true，则加载程序会将空字符串视为有效的属性值并相应地加载它们。

有关更多信息，请参阅 SPARQL 默认图形和命名图形。

updateSingleCardinalityProperties – 这是一个可选参数，用于控制批量加载程序如何处理单基数顶点或边缘属性的新值。加载 openCypher 数据时不支持这样做（请参阅加载 openCypher 数据）。

允许的值："TRUE"、"FALSE"。

默认值："FALSE"。

默认情况下，或者当 updateSingleCardinalityProperties 被显式设置为 "FALSE" 时，加载程序将新值视为错误，因为它违反了单个基数。

另一方面，当 updateSingleCardinalityProperties 设置为 "TRUE" 时，批量加载程序会用新值替换现有值。如果在要加载的源文件中提供了多个边缘或单基数顶点属性值，则批量加载结束时的最终值可以是这些新值中的任何一个值。加载程序仅保证现有值已被其中一个新值替换。
queueRequest – 这是一个可选的标志参数，用于指示是否可以对加载请求进行排队。

您不必等到一个加载任务完成就可以发出下一个任务，因为 Neptune 可以一次对多达 64 个任务进行排队，前提是它们的 queueRequest 参数都设置为 "TRUE"。任务的队列顺序将是 first-in-first-out (FIFO)。

如果省略 queueRequest 参数或将其设置为 "FALSE"，则如果另一个加载作业已在运行，该加载请求将失败。

允许的值："TRUE"、"FALSE"。

默认值："FALSE"。
dependencies – 这是一个可选参数，可以使排队的加载请求取决于队列中的一个或多个先前任务的成功完成。

Neptune 可以一次对多达 64 个加载请求进行排队，前提是它们的 queueRequest 参数设置为 "TRUE"。dependencies 参数允许您使此类排队请求的执行取决于成功完成队列中的一个或多个指定的先前请求。

例如，如果加载 Job-A 和 Job-B 彼此独立，但加载 Job-C 在开始之前要求先完成 Job-A 和 Job-B，请按以下方式进行操作：
1. 不分顺序接连提交 load-job-A 和 load-job-B，并保存它们的加载 ID。
2. 提交 load-job-C，并在其 dependencies 字段中填入前两个作业的加载 ID：
```
  "dependencies" : ["job_A_load_id", "job_B_load_id"]
```
由于 dependencies 参数，批量加载程序在 Job-A 和 Job-B 成功完成前将不会启动 Job-C。如果其中任何一个作业失败，则不会执行作业 C，并将其状态设置为 LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED。

您可以通过这种方式设置多个依赖关系级别，这样，一个作业的失败将导致所有直接或间接依赖于该作业的请求被取消。
userProvidedEdgeIds – 只有在加载包含关系 ID 的 openCypher 数据时，才需要此参数。当加载数据中显式提供 openCypher 关系 ID 时，必须包含此参数并将它设置为 True（推荐）。

如果 userProvidedEdgeIds 不存在或设置为 True，则加载过程中的每个关系文件中都必须存在 :ID 列。

如果 userProvidedEdgeIds 存在且设置为 False，则加载中的关系文件不得包含 :ID 列。相反，Neptune 加载程序会自动为每个关系生成一个 ID。

显式提供关系 ID 非常有用，这样加载程序就可以在 CSV 数据中的错误得到修复后恢复加载，而不必重新加载任何已经加载的关系。如果没有显式分配关系 ID，当必须更正任何关系文件时，加载程序将无法恢复失败的加载，而是必须重新加载所有关系。
accessKey – [弃用] 对 S3 桶和数据文件具有访问权限的 IAM 角色的访问密钥 ID。

建议改用 iamRoleArn 参数。有关创建对 Amazon S3 具有访问权限的角色，然后将其与 Neptune 集群关联的信息，请参阅先决条件：IAM 角色和 Amazon S3 访问权限。

有关更多信息，请参阅访问密钥（访问密钥 ID 和秘密访问密钥）。
secretKey – [已弃用] 建议改用 iamRoleArn 参数。有关创建对 Amazon S3 具有访问权限的角色，然后将其与 Neptune 集群关联的信息，请参阅先决条件：IAM 角色和 Amazon S3 访问权限。

有关更多信息，请参阅访问密钥（访问密钥 ID 和秘密访问密钥）。

加载 openCypher 数据的特殊注意事项

以 CSV 格式加载 openCypher 数据时，必须将格式参数设置为 opencypher。
openCypher 加载不支持 updateSingleCardinalityProperties 参数，因为所有 openCypher 属性都具有单一基数。openCypher 加载格式不支持数组，如果一个 ID 值出现多次，则将其视为重复值或插入错误（见下文）。
Neptune 加载程序按如下方式处理它在 openCypher 数据中遇到的重复项：
- 如果加载程序遇到多个具有相同节点 ID 的行，则使用以下规则将它们合并：
  - 行中的所有标签都将添加到节点中。
  - 对于每个属性，只加载其中一个属性值。选择要加载哪个属性值是不确定的。
- 如果加载程序遇到多个具有相同关系 ID 的行，则只加载其中一行。选择要加载哪一行是不确定的。
- 如果加载程序遇到具有现有节点或关系 ID 的加载数据，则它从不会更新数据库中现有节点或关系的属性值。但是，它的确会加载现有节点或关系中不存在的节点标签和属性。
尽管您不必为关系分配 ID，但这通常是个好主意（请参阅上面的 userProvidedEdgeIds 参数）。如果没有显式关系 ID，加载程序必须重新加载所有关系，以防关系文件出现错误，而不是从失败的地方恢复加载。

此外，如果加载数据不包含显式关系 ID，则加载程序无法检测重复的关系。

以下是 openCypher 加载命令的示例：



curl -X POST https://your-neptune-endpoint:port/loader \
     -H 'Content-Type: application/json' \
     -d '
     {
       "source" : "s3://bucket-name/object-key-name",
       "format" : "opencypher",
       "userProvidedEdgeIds": "TRUE",
       "iamRoleArn" : "arn:aws:iam::account-id:role/role-name",
       "region" : "region",
       "failOnError" : "FALSE",
       "parallelism" : "MEDIUM",
     }'

加载程序响应与正常响应相同。例如：


{
  "status" : "200 OK",
  "payload" : {
    "loadId" : "guid_as_string"
  }
}

Neptune 加载程序响应语法


{
    "status" : "200 OK",
    "payload" : {
        "loadId" : "guid_as_string"
    }
}

200 OK (200 确定)

成功启动的加载任务将返回 200 代码。

Neptune 加载程序错误

当错误出现后，响应的 BODY 中将返回 JSON 对象。message 对象包含对错误的描述。

错误类别

Error 400 – 语法错误将返回 HTTP 400 错误请求错误。此消息描述错误。
Error 500 – 无法处理的有效请求返回 HTTP 500 内部服务器错误。此消息描述错误。

以下是来自加载程序的可能的错误消息，其中包含对错误的描述。

加载程序错误消息

Couldn't find the AWS credential for iam_role_arn (HTTP 400)

未找到凭证。对照 IAM 控制台或 AWS CLI 输出验证提供的证书。确保您已将在 iamRoleArn 中指定的 IAM 角色添加到集群。
S3 bucket not found for source (HTTP 400)

S3 存储桶不存在。请检查存储桶的名称。
The source source-uri does not exist/not reachable (HTTP 400)

在 S3 存储桶中未找到匹配的文件。
Unable to connect to S3 endpoint. Provided source = source-uri and region = aws-region (HTTP 500)

无法连接到 Amazon S3。区域必须与集群区域匹配。确保具有 VPC 端点。有关创建 VPC 端点的信息，请参阅创建 Amazon S3 VPC 端点。
Bucket is not in provided Region (aws-region) (HTTP 400)

存储桶必须与您的 Neptune 数据库实例位于同一 AWS 区域。
Unable to perform S3 list operation (HTTP 400)

提供的 IAM 用户或角色对存储桶或文件夹无 List 权限。检查存储桶上的此策略或访问控制列表 (ACL)。
Start new load operation not permitted on a read replica instance (HTTP 405)

加载是写入操作。在读取/写入集群终端节点上重试加载。
Failed to start load because of unknown error from S3 (HTTP 500)

Amazon S3 返回了未知错误。联系 AWS Support。
Invalid S3 access key (HTTP 400)

访问密钥无效。请检查提供的凭证。
Invalid S3 secret key (HTTP 400)

秘密密钥无效。请检查提供的凭证。
Max concurrent load limit breached (HTTP 400)

如果提交的加载请求没有附带 "queueRequest" : "TRUE"，并且当前正在运行加载作业，则请求将失败并显示此错误。
Failed to start new load for the source "source name". Max load task queue size limit breached. Limit is 64 (HTTP 400)

Neptune 支持一次对多达 64 个加载程序任务进行排队。如果额外的加载请求提交到已经包含 64 个作业的队列，请求将失败并显示此消息。

Neptune 加载程序示例

例请求

下面是使用 curl 命令经由 HTTP POST 发送的请求。它加载 Neptune CSV 格式的文件。有关更多信息，请参阅 Gremlin 加载数据格式。


curl -X POST \
    -H 'Content-Type: application/json' \
    https://your-neptune-endpoint:port/loader -d '
    {
      "source" : "s3://bucket-name/object-key-name",
      "format" : "csv",
      "iamRoleArn" : "ARN for the IAM role you are using",
      "region" : "region",
      "failOnError" : "FALSE",
      "parallelism" : "MEDIUM",
      "updateSingleCardinalityProperties" : "FALSE",
      "queueRequest" : "FALSE"
    }'

例响应


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

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

加载程序参考

获取状态 API