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包含以逗号分隔的角色列表 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-south-2
- 欧洲地区（爱尔兰）：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-southeast-3
- 亚太地区（马来西亚）：ap-southeast-5
- 亚太地区（孟买）：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— 使用的线程数等于可用线程数 v CPUs 除以 8。
- MEDIUM— 使用的线程数等于可用线程数 v CPUs 除以 2。
- HIGH— 使用的线程数与可用线程数 v 相同CPUs。
- OVERSUBSCRIBE— 使用的线程数是可用线程数 v CPUs 乘以 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 格式的默认图形（适用于非 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/DefaultNamedGraph`	未指定任何图形时所有 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— 只有在加载包含关系的 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 代码。

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

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

文档惯例

加载程序参考

错误