Neptune 数据面板批量加载程序 API

• StartLoaderJob（操作）

• GetLoaderJobStatus（操作）

• ListLoaderJobs（操作）

• CancelLoaderJob（操作）

• LoaderIdResult（结构）

• dependencies（在 CLI 中：--dependencies）– 一个字符串，类型为：string（UTF-8 编码的字符串）。

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

  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。

  您可以通过这种方式设置多个依赖关系级别，这样，一个作业的失败将导致所有直接或间接依赖于该作业的请求被取消。

• failOnError（在 CLI 中：--fail-on-error）– 一个布尔值，类型为：boolean [布尔值（true 或 false）]。

  failOnError – 用于在出错时切换为完全停止的标志。

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

  默认值："TRUE"。

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

  将此参数设置为 "TRUE" 时，加载程序会在遇到错误时立即停止。截至该点加载的数据仍然存在。

• format（在 CLI 中：--format）– 必需：格式，类型为：string（UTF-8 编码的字符串）。

  数据的格式。有关 Neptune Loader 命令的数据格式的更多信息，请参阅加载数据格式。

  允许的值

  • csv 适用于 Gremlin CSV 数据格式。

  • opencypher 适用于 openCypher CSV 数据格式。

  • ntriples 适用于 N-Triples RDF 数据格式。

  • nquads 适用于 N-Quads RDF 数据格式。

  • rdfxml 适用于 RDF\XML RDF 数据格式。

  • turtle 适用于 Turtle RDF 数据格式。

• iamRoleArn（在 CLI 中：--iam-role-arn）– 必需：一个字符串，类型为：string（UTF-8 编码的字符串）。

  Neptune 数据库实例为访问 S3 桶而代入的 IAM 角色的 Amazon 资源名称 (ARN)。此处提供的 IAM 角色 ARN 应附加到数据库集群（请参阅向 Amazon Neptune 集群添加 IAM 角色）。

• mode（在 CLI 中：--mode）– 一种模式，类型为：string（UTF-8 编码的字符串）。

  加载作业模式。

  允许的值：RESUME、NEW、AUTO

  默认值：AUTO。

  • RESUME – 在 RESUME 模式下，加载程序查找来自此源的先前加载，如果找到一个加载，则恢复该加载任务。如果未找到之前的加载作业，则加载程序将停止。

    加载程序将避免重新加载之前作业中已成功加载的文件。它仅尝试处理失败的文件。如果您从 Neptune 集群中删除了之前加载的数据，则此模式下不加载该数据。如果之前的加载任务成功加载了来自同一源的所有文件，则不会重新加载任何文件，并且加载程序返回成功。

  • NEW – 在 NEW 模式下，将创建新的加载请求而不管任何之前的加载。您可以使用此模式在从 Neptune 集群删除之前加载的数据之后从源重新加载数据，或加载同一个源处可用的新数据。

  • AUTO – 在 AUTO 模式下，加载程序查找来自此同一个源的先前加载任务，如果找到一个加载任务，则恢复该任务，如同在 RESUME 模式中一样。

    如果加载程序没有找到来自同一源的先前加载作业，则会从源加载所有数据，就像在 NEW 模式中一样。

• parallelism（在 CLI 中：--parallelism）– 并行度，类型为：string（UTF-8 编码的字符串）。

  可以设置可选 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（在 CLI 中：--parser-configuration）– 它是键值对的映射数组，其中：

      每个键都是一个字符串，类型为：string（UTF-8 编码的字符串）。

      每个值都是一个字符串，类型为：string（UTF-8 编码的字符串）。

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

  • namedGraphUri – 未指定任何图形时所有 RDF 格式的默认图形（适用于非 quads 格式和无图形的 NQUAD 条目）。

    默认为 https://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph。

  • baseUri – RDF/XML 和 Turtle 格式的基本 URI。

    默认为 https://aws.amazon.com/neptune/default。

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

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

• queueRequest（在 CLI 中：--queue-request）– 一个布尔值，类型为：boolean [布尔值（true 或 false）]。

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

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

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

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

  默认值："FALSE"。

• s3BucketRegion（在 CLI 中：--s-3-bucket-region）– 必需：一个 S3BucketRegion，类型为：string（UTF-8 编码的字符串）。

  S3 桶的 Amazon 区域。这必须与数据库集群的 Amazon 区域相匹配。

• source（在 CLI 中：--source）– 必需：一个字符串，类型为：string（UTF-8 编码的字符串）。

  source 参数接受标识单个文件、多个文件、一个文件夹或多个文件夹的 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 元素等同于 S3 ListObjects API 调用中的前缀参数。它可以识别指定的 S3 桶中名称以该前缀开头的所有对象。可以是单个文件或文件夹，也可以是多个文件和/或文件夹。

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

• updateSingleCardinalityProperties（在 CLI 中：--update-single-cardinality-properties）– 一个布尔值，类型为：boolean [布尔值（true 或 false）]。

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

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

  默认值："FALSE"。

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

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

• userProvidedEdgeIds（在 CLI 中：--user-provided-edge-ids）– 一个布尔值，类型为：boolean [布尔值（true 或 false）]。

  只有在加载包含关系 ID 的 openCypher 数据时，才需要此参数。当加载数据中显式提供 openCypher 关系 ID 时，必须包含此参数并将它设置为 True（推荐）。

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

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

  显式提供关系 ID 非常有用，这样加载程序就可以在 CSV 数据中的错误得到修复后恢复加载，而不必重新加载任何已经加载的关系。如果没有显式分配关系 ID，当必须更正任何关系文件时，加载程序将无法恢复失败的加载，而是必须重新加载所有关系。

• payload – 必需：它是键值对的映射数组，其中：

      每个键都是一个字符串，类型为：string（UTF-8 编码的字符串）。

      每个值都是一个字符串，类型为：string（UTF-8 编码的字符串）。

  包含为加载操作提供标识符的 loadId 名称/值对。

• status – 必需：一个字符串，类型为：string（UTF-8 编码的字符串）。

  HTTP 返回代码，指示加载任务的状态。

错误

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• S3Exception

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

• details（在 CLI 中：--details）– 一个布尔值，类型为：boolean [布尔值（true 或 false）]。

  表示是否要包括总体状态之外的详细信息的标志（TRUE 或 FALSE；默认为 FALSE）。

• errors（在 CLI 中：--errors）– 一个布尔值，类型为：boolean [布尔值（true 或 false）]。

  指示是否包含遇到的错误列表的标志（TRUE 或 FALSE；默认为 FALSE）。

  将对错误的列表进行分页。page 和 errorsPerPage 参数允许浏览所有错误。

• errorsPerPage（在 CLI 中：--errors-per-page）– PositiveInteger，类型为：integer（带符号的 32 位整数），至少为 1。

  每页返回的错误数（正整数；默认为 10）。仅当 errors 参数设置为 TRUE 时才有效。

• loadId（在 CLI 中：--load-id）– 必需：一个字符串，类型为：string（UTF-8 编码的字符串）。

  要获取其状态的加载任务的加载 ID。

• page（在 CLI 中：--page）– PositiveInteger，类型为：integer（带符号的 32 位整数），至少为 1。

  错误页码（正整数；默认为 1）。仅当 errors 参数设置为 TRUE 时才有效。

• payload – 必需：文档，类型为：document（由类似 JSON 的数据模型表示的与协议无关的开放内容）。

  有关加载任务的状态信息，其布局可能如下所示：

  {
            "status" : "200 OK",
            "payload" : {
              "feedCount" : [
                {
                  "LOAD_FAILED" : (number)
                }
              ],
              "overallStatus" : {
                "fullUri" : "s3://(bucket)/(key)",
                "runNumber" : (number),
                "retryNumber" : (number),
                "status" : "(string)",
                "totalTimeSpent" : (number),
                "startTime" : (number),
                "totalRecords" : (number),
                "totalDuplicates" : (number),
                "parsingErrors" : (number),
                "datatypeMismatchErrors" : (number),
                "insertErrors" : (number),
              },
              "failedFeeds" : [
                {
                  "fullUri" : "s3://(bucket)/(key)",
                  "runNumber" : (number),
                  "retryNumber" : (number),
                  "status" : "(string)",
                  "totalTimeSpent" : (number),
                  "startTime" : (number),
                  "totalRecords" : (number),
                  "totalDuplicates" : (number),
                  "parsingErrors" : (number),
                  "datatypeMismatchErrors" : (number),
                  "insertErrors" : (number),
                }
              ],
              "errors" : {
                "startIndex" : (number),
                "endIndex" : (number),
                "loadId" : "(string),
                "errorLogs" : [ ]
              }
            }
          }

• status – 必需：一个字符串，类型为：string（UTF-8 编码的字符串）。

  请求的 HTTP 响应代码。

错误

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

• includeQueuedLoads（在 CLI 中：--include-queued-loads）– 一个布尔值，类型为：boolean [布尔值（true 或 false）]。

  一个可选参数，可用于在请求加载 ID 列表时排除排队加载请求的加载 ID，方法是将该参数设置为 FALSE。默认值为 TRUE。

• limit（在 CLI 中：--limit）– ListLoaderJobsInputLimitInteger，类型为：integer（带符号的 32 位整数），不小于 1 或大于 100。

  要列出的加载 ID 的数量。必须是大于零且不大于 100（这是默认值）的正整数。

• payload – 必填：一个 LoaderIdResult 对象。

  请求的任务 ID 列表。

• status – 必需：一个字符串，类型为：string（UTF-8 编码的字符串）。

  返回任务列表请求的状态。

错误

• UnsupportedOperationException

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• InternalFailureException

• ClientTimeoutException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• loadId（在 CLI 中：--load-id）– 必需：一个字符串，类型为：string（UTF-8 编码的字符串）。

  要删除的加载任务的 ID。

• status – 一个字符串，类型为：string（UTF-8 编码的字符串）。

  取消状态。

错误

• BadRequestException

• InvalidParameterException

• BulkLoadIdNotFoundException

• ClientTimeoutException

• LoadUrlAccessDeniedException

• IllegalArgumentException

• TooManyRequestsException

• UnsupportedOperationException

• InternalFailureException

• PreconditionsFailedException

• ConstraintViolationException

• InvalidArgumentException

• MissingParameterException

字段

• loadIds – 这是一个字符串，类型为：string（UTF-8 编码的字符串）。

  加载 ID 的列表。