Neptune 加载程序命令

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

要加载数据，必须向https://your-neptune-endpoint:port/loader端点发送HTTPPOST请求。loader请求的参数可以在POST正文中发送，也可以作为URL编码参数发送。

重要

MIME类型必须是application/json。

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

注意

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

您也可以从 Amazon S3 加载使用该SSE-KMS模式加密的加密数据，前提是您的IAM角色包含必要的访问权限 AWS 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— 亚马逊 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
的object-key-name元素等同URI于 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用于 T urtle RDF 数据格式。
iamRoleArn— 由 Neptune 数据库实例代入访问 S3 存储桶的IAM角色的 Amazon 资源名称 (ARN)。有关创建对 Amazon S3 具有访问权限的角色，然后将其与 Neptune 集群关联的信息，请参阅先决条件：IAM角色和 Amazon S3 访问权限。

从引擎版本 1.2.1.0.R3 开始，IAM如果 Neptune 数据库实例和 Amazon S3 存储桶位于不同的账户中，您还可以链接多个角色。 AWS 在本例中，iamRoleArn包含以逗号分隔的角色列表ARNs，如中所述。在 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
- 中东 (UAE): 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— 使用的线程数等于可用线程数 vCPUs 除以 8。
- MEDIUM— 使用的线程数等于可用线程数 vCPUs 除以 2。
- HIGH— 使用的线程数与可用线程数相同vCPUs。
- OVERSUBSCRIBE— 使用的线程数等于可用线程数 vCPUs 乘以 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/DefaultNamedGraph 未指定图形时所有RDF格式的默认图表（适用于非四边形格式和没有图形的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/DefaultNamedGraph`	未指定图形时所有RDF格式的默认图表（适用于非四边形格式和没有图形的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`	Gremlin 用户在加载CSV数据时需要能够将空字符串值 (“”) 作为节点和边缘属性传递。如果 `allowEmptyStrings` 设置为 `false`（默认值），则此类空字符串将视为 null 且不会加载。如果 `allowEmptyStrings` 设置为 `true`，则加载程序会将空字符串视为有效的属性值并相应地加载它们。

allowEmptyStrings

true

Gremlin 用户在加载CSV数据时需要能够将空字符串值 (“”) 作为节点和边缘属性传递。如果 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— 只有在加载包含关系 openCypher 的数据时才需要此参数IDs。当加载数据中明确提供 openCypher 关系True时IDs，必须将其包含并设置为（推荐）。

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

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

IDs显式提供关系很有用，这样加载器就可以在修复CSV数据错误后恢复加载，而不必重新加载任何已经加载的关系。如果IDs尚未明确分配关系，则如果必须更正任何关系文件，加载程序将无法恢复失败的加载，而是必须重新加载所有关系。
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 的加载数据，则它从不会更新数据库中现有节点或关系的属性值。但是，它的确会加载现有节点或关系中不存在的节点标签和属性。
尽管您不必IDs为关系赋值，但这通常是个好主意（参见上面的userProvidedEdgeIds参数）。如果没有明确的关系IDs，加载器必须重新加载所有关系，以防关系文件出现错误，而不是从失败的地方恢复加载。

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

以下是 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— 语法错误会返回HTTP400错误的请求错误。此消息描述错误。
Error 500— 无法处理的有效请求会返回HTTP500内部服务器错误。此消息描述错误。

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

加载程序错误消息

Couldn't find the AWS credential for iam_role_arn(HTTP400)

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

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

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

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

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

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

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

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

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

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

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

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

Neptune 加载程序示例

例请求

以下是HTTPPOST使用curl命令发送的请求。它加载一个 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