Neptune 加载器命令 - Amazon Neptune
请求语法请求参数响应语法错误示例

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

Neptune 加载器命令

将数据从 Amazon S3 存储桶加载到 Neptune 数据库实例。

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

重要

MIME 类型必须为 application/json。

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

注意

如果加密数据是使用 Amazon S3SSE-S3 模式加密的，则可以从 Amazon S3 加载加密数据。在这种情况下，Neptune 可以冒充您的凭证并代表您s3:getObject拨打电话。

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

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

您不必等到一个加载任务完成后再开始另一个加载任务。Neptune 一次可以将多达 64 个任务请求排队，前提是它们的queueRequest参数都设置为"TRUE"。另一方面，如果您不希望加载作业进入队列，则可以将其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 存储桶中名称以该前缀开头的所有对象。可以是单个文件或文件夹，也可以是多个文件和/或文件夹。

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

  • format— 数据的格式。有关 NeptuneLoader 命令的数据格式的更多信息，请参阅使用Amazon Neptune 批量加载器提取数据。

    允许的值

  • iamRoleArn— 由 Neptune 数据库实例担任的 IAM 角色的 Amazon 资源名称 (ARN)，以访问 S3 存储桶。有关创建有权访问 Amazon S3 的角色然后将其与 Neptune 集群关联的信息，请参阅先决条件：IAM 角色和Amazon S3 访问权限。

  • 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

    • 非洲（开普敦）：af-south-1

    • 亚太地区（香港）：ap-east-1

    • 亚太地区（东京）：ap-northeast-1

    • 亚太地区（首尔）：ap-northeast-2

    • 亚太地区（新加坡）：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 The default graph for all RDF formats when no graph is specified (for non-quads formats and NQUAD entries with no graph). The default is http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph
    baseURI http://aws.amazon.com/neptune/default The base URI for RDF/XML and Turtle formats. The default is http://aws.amazon.com/neptune/default.
    allowEmptyStrings true

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

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

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

  • updateSingleCardinalityProperties— 这是一个可选参数，用于控制批量加载器如何处理单基数顶点或边属性的新值。这不支持加载 OpencyPher 数据（参见加载OpencyPHER数据）。

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

    默认值："FALSE"。

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

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

  • queueRequest— 这是一个可选的标志参数，用于指示加载请求是否可以排队。

    在发布下一个加载任务之前，您不必等待一个加载任务完成，因为 Neptune 一次可以将多达 64 个任务排队，前提是它们的queueRequest参数都设置为"TRUE"。

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

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

    默认值："FALSE"。

  • dependencies— 这是一个可选参数，它可以使队列中的加载请求取决于队列中先前一项或多项任务的成功完成。

    如果queueRequest参数设置为，Neptune 一次可以将多达 64 个加载请求排队"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 关系 IDTrue 时，必须将其包含并设置为该值（推荐）。

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

    当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— 语法错误返回 HTTP400 错误请求错误。此消息描述错误。

  • Error 500— 无法处理的有效请求返回 HTTP500 内部服务器错误。此消息描述错误。

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

加载程序错误消息

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

    未找到凭证。根据 IAM 控制台或AWS CLI输出验证提供的证书。确保您已将中指定的 IAM 角色iamRoleArn添加到集群。

  • 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"
    }
}