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. 使用兩任務其 dependencies 欄位中的載入 ID 提交 load-job-C：

    "dependencies" : ["(job_A_load_id)", "(job_B_load_id)"]

  由於 dependencies 參數的關係，大量載入器在 Job-A 和 Job-B 順利完成之前，將不會啟動 Job-C。如果其中任何一個失敗，則不執行 Job-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 Resource Name (ARN)。這裡提供的 IAM 角色 ARN 應附加至資料庫叢集 (請參閱將 IAM 角色新增至 Amazon Neptune 叢集。

• 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 資料時，Gemlin 使用者必須能夠傳遞空字串值 ("") 做為節點和邊緣屬性。如果 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 呼叫中的 prefix 參數。它會識別所指定 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 編碼的字串)。

  指示載入工作狀態的傳回碼。

錯誤

• 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 ?st?。

  每一頁傳回的錯誤數目 (正整數；預設值為 10)。僅在 errors 參數設定為 TRUE 時才有效。

• loadId (在 CLI 中：--load-id) – 必要：字串，類型為：string (UTF-8 編碼的字串)。

  要取得其狀態之載入工作的載入 ID。

• page (在 CLI 中：--page) – PositiveInteger，類型為：integer (帶有正負號的 32 位元整數)，至少 1 ?st?。

  錯誤頁號碼 (正整數；預設值為 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))。

  選用參數，在將此參數設定為 FALSE，請求載入 ID 清單時，此參數可以用來排除佇列中載入請求的載入 ID。預設值為 TRUE。

• limit (在 CLI 中：--limit) – ListLoaderJobsInputLimitInteger，類型為：integer (帶有正負號的 32 位元整數)，不小於 1 或大於 100 ?st?s。

  要列出的載入 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 的清單。