Neptune データプレーンバルクローダー API

• StartLoaderJob (アクション)

• GetLoaderJobStatus (アクション)

• ListLoaderJobs (アクション)

• CancelLoaderJob (アクション)

• LoaderIdResult (構造)

• dependencies (CLI では: --dependencies) — タイプ string の文字列 (UTF-8 でエンコードされた文字列)。

  これは、キュー内の 1 つ以上の前のジョブが正常に完了することを条件に、キューに入れられたロードリクエストを作成することができるオプションのパラメータです。

  Neptune は、queueRequest パラメータが "TRUE" に設定されている場合、一度に最大 64 個のロードリクエストをキューに入れることができます。dependencies パラメータを使用すると、キュー内で指定された 1 つ以上前のリクエストが正常に完了したかどうかに応じて、キューに入れられたそのようなリクエストを実行できます。

  たとえば、ロード Job-A と Job-B が互いに独立しているものの、ロード Job-C を開始する前に Job-A および Job-B を終了する必要がある場合は、次の手順を実行します。

  1. 任意の順序で load-job-A と load-job-B を 1 つずつ送信し、load-id を保存します。

  2. dependencies フィールドで 2 つのジョブの load-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 に設定されます。

  この方法で複数のレベルの依存関係を設定できます。これにより、1 つのジョブが失敗すると、直接的または間接的に依存するすべてのリクエストがキャンセルされます。

• failOnError (CLI では: --fail-on-error) — タイプ boolean のブール値 (ブール値 (真または偽) の値)。

  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 でエンコードされた文字列)。

  S3 バケットにアクセスするために、Neptune DB インスタンスによって想定される IAM ロールの Amazon リソースネーム (ARN)。ここで指定した IAM ロール ARN は DB クラスターにアタッチする必要があります (「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 - 使用されるスレッドの数は、コア数を 8 で割った値です。

  • MEDIUM - 使用されるスレッドの数は、コア数を 2 で割った値です。

  • HIGH - 使用されるスレッドの数は、コア数と同じです。

  • OVERSUBSCRIBE - 使用されるスレッドの数は、コア数に 2 をかけた値です。この値を使用する場合、バルクローダーは利用可能なすべてのリソースを消費します。

    ただし、これは、OVERSUBSCRIBE 設定すると、CPU 使用率が 100% になります。ロードオペレーションは I/O バウンドであるため、予想される CPU 最高使用率は 60% ～ 70% の範囲にあります。

  デフォルト値: HIGH

  parallelism openCypher データをロードするときに、設定によってスレッド間でデッドロックが発生することがあります。こうなると、Neptune は LOAD_DATA_DEADLOCK というエラーを返します。通常、この問題は次のようにして修正できます。parallelism より低い設定にし、ロードコマンドを再試行します。

• parserConfiguration (CLI では: --parser-configuration) - キと値のペアのマップ配列。

      各キーは、タイプ string の文字列 (UTF-8 でエンコードされた文字列) です。

      各値は、タイプ string の文字列 (UTF-8 でエンコードされた文字列) です。

  parserConfiguration - 追加のパーサー設定値のあるオプションのオブジェクト。それぞれの子パラメータもオプションです。

  • namedGraphUri - グラフが指定されていない場合の、すべての RDF 形式のデフォルトのグラフ (四角形でない形式、およびグラフのない NQUAD エントリ)。

    デフォルトは https://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph です。

  • baseUri - RDF/XML および Turtle 形式の基本 URI。

    デフォルトは https://aws.amazon.com/neptune/default です。

  • allowEmptyStrings - Gremlin ユーザーは、CSV データを読み込むときに、ノードおよびエッジのプロパティとして空の文字列値 ("") を渡す必要があります。allowEmptyStrings が false (デフォルト) に設定されている場合、そのような空の文字列は NULL として扱われ、ロードされません。

    allowEmptyStrings が true に設定されている場合、ローダーは空の文字列を有効なプロパティ値として扱い、それに応じてロードします。

• queueRequest (CLI では: --queue-request) — タイプ boolean のブール値 (ブール値 (真または偽) の値)。

  これは、ロードリクエストをキューに入れることができるかどうかを示すオプションのフラグパラメータです。

  queueRequest パラメータをすべて "TRUE"に設定している場合、Neptune は一度に最大 64 個のジョブをキューに入れることができるので、次のジョブを発行する前に 1 つのロードジョブが完了するのを待つ必要はありません。ジョブのキューの順序は、FIFO (先入れ先出し) です。

  queueRequest パラメータを省略するるか、"FALSE" に設定した場合、別のロードジョブがすでに実行されていると、ロードリクエストは失敗します。

  使用できる値: "TRUE"、"FALSE"。

  デフォルト値: "FALSE"。

• s3BucketRegion (CLI では: --s-3-bucket-region) — 必須: string タイプの S3BucketRegion (UTF-8 でエンコードされた文字列)。

  S3 バケットの Amazon リージョン。これは DB クラスターの Amazon リージョンと一致する必要があります。

• source (CLI では: --source) — 必須: string タイプの文字列 (UTF-8 でエンコードされた文字列)。

  source パラメータは、単一のファイル、複数のファイル、1 つのフォルダ、または複数のフォルダを識別する 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 のブール値 (ブール値 (真または偽) の値)。

  updateSingleCardinalityProperties は、バルクローダーが単一濃度の頂点またはエッジプロパティの新しい値を処理する方法を制御するオプションのパラメータです。これは openCypher データのロードではサポートされていません。

  使用できる値: "TRUE"、"FALSE"。

  デフォルト値: "FALSE"。

  デフォルトでは、または updateSingleCardinalityProperties が明示的に "FALSE" に設定されている場合、ローダーは単一の濃度に違反するため、新しい値をエラーとして扱います。

  一方、updateSingleCardinalityProperties が "TRUE" に設定されている場合、バルクローダーは既存の値を新しい値に置き換えます。ロードされるソースファイルで複数のエッジまたは単一濃度の頂点プロパティ値が指定されている場合、バルクロードの終了時の最終値は、これらの新しい値のいずれかになります。ローダーは、既存の値が新しい値の 1 つに置き換えられたことを保証します。

• userProvidedEdgeIds (CLI では: --user-provided-edge-ids) — タイプ boolean のブール値 (ブール値 (真または偽) の値)。

  このパラメータは、リレーションシップ ID を含む openCypher データをロードする場合にのみ必要です。openCypher 関係 ID がロードデータに明示的に指定されている場合 (推奨)、必ず含められ True に設定されています。

  userProvidedEdgeIds がないか、True に設定されている場合、:ID 列は、ロード内のすべてのリレーションシップファイルにある必要があります。

  userProvidedEdgeIds があり、False に設定されている場合、ロード内のリレーションシップファイルに :ID 列があってはなりません。代わりに、Neptune ローダーは各リレーションシップの ID を自動的に生成します。

  CSV データのエラーが修正された後にローダーがロードを再開できるように、リレーションシップ ID を明示的に指定すると便利です。すでにロードされているリレーションシップをリロードする必要はありません。リレーションシップ 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、デフォルトは FALSE)。

• errors (CLI では: --errors) — タイプ boolean のブール値 (ブール値 (真または偽) の値)。

  発生したエラーのリストを含めるかどうかを示すフラグ (TRUE または FALSE、デフォルトは FALSE)。

  エラーのリストはページ分割されます。page および errorsPerPage パラメータで、すべてのエラーをページ分割できます。

• errorsPerPage (CLI では: --errors-per-page) — タイプ integer の PositiveInteger (符号付き32ビット整数)、少なくとも 1? st?。

  各ページで返されるエラーの数 (正の整数、デフォルトは 10)。errors パラメータが TRUE に設定されている場合にのみ有効です。

• loadId (CLI では: --load-id) — 必須: string タイプの文字列 (UTF-8 でエンコードされた文字列)。

  ステータスを取得するロードジョブのロード ID。

• page (CLI では: --page) — タイプ integer の PositiveInteger (符号付き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 のブール値 (ブール値 (真または偽) の値)。

  パラメータを FALSE に設定することによってロード ID のリストをリクエストしたときに、キューに入れられたロードリクエストのロード ID を除外するために使用できるオプションのパラメータ。デフォルト値は TRUE です。

• limit (CLI では: --limit) — ListLoaderJobsInputLimitInteger、タイプ integer (符号付き 32 ビット整数)、1 以上か 1024 以上？ st? s。

  一覧表示されるロード ID の数。0 より大きく、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 のリスト。