Neptune ローダーコマンド - Amazon Neptune

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Neptune ローダーコマンド

Amazon S3 バケットから Neptune DB インスタンスにデータをロードします。

データをロードするには、POST エンドポイントに、HTTP 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 にアクセスするために必要なアクセス権限が含まれている限り、SSE-KMS モードを使用して暗号化された Amazon S3 から、暗号化されたデータをロードすることもできます。適切な AWS KMS アクセス権限がない場合、一括ロードオペレーションは失敗し、LOAD_FAILED レスポンスを返します。

Neptune は現在 SSE-C モードを使用して暗号化された Amazon S3 データのロードをサポートしていません。

別のジョブを開始する前に、1 つのロードジョブが完了するのを待つ必要はありません。Neptune は、queueRequest パラメータがすべて "TRUE" に設定されている場合、一度に最大 64 個のロードリクエストをキューに入れることができます。一方、ロードジョブをキューに入れたくない場合は、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 パラメータは、単一のファイル、複数のファイル、1 つのフォルダ、または複数のフォルダを識別する 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

    -object-key-nameURI の要素はプレフィックスAmazon S3 のパラメータListObjectsAPI 呼び出し。これは、名前がそのプレフィックスで始まる指定された Amazon S3 バケット内のすべてのオブジェクトを識別します。これは、単一のファイルまたはフォルダ、または複数のファイルやフォルダにすることができます。

    特定のフォルダには複数の頂点ファイルおよび複数のエッジファイルが含まれている場合があります。

  • format - データの形式。Neptune Loader コマンドのデータ形式の詳細については、Amazon Neptune 一括ローダーを使用したデータの取り込み を参照してください。

    許可される値

  • iamRoleArn - S3 バケットにアクセスするために、Neptune DB インスタンスによって想定される IAM ロールの Amazon リソースネーム (ARN)。Amazon S3 にアクセスできるロールを作成し、Neptune クラスターに関連付ける方法の詳細については、前提条件: IAM ロールと Amazon S3 アクセス を参照してください。

  • region - region パラメータはクラスターおよび S3 バケットの AWS リージョンと一致する必要があります。

    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 - ロードジョブモード。

    使用できる値: RESUMENEWAUTO

    デフォルト値: AUTO

    • RESUME   -   RESUME モードでは、ローダーはこのソースからの以前のロードを検索し、見つかった場合は、そのロードジョブを再開します。以前のロードジョブが見つからない場合、ローダーは停止します。

      ローダーは、以前のジョブで正常にロードされたファイルの再ロードを回避します。失敗したファイルの処理のみを試行します。以前にロードしたデータを Neptune クラスターから削除している場合、そのデータはこのモードでは再ロードされません。以前のロードジョブが同じソースからすべてのファイルを正常にロードした場合、何も再ロードされず、ローダーは成功を返します。

    • NEW   -   NEW モードでは、以前のロードに関係なく、新しいロードリクエストが作成されます。このモードを使用して、以前にロードされたデータを Neptune クラスターから削除した後にソースからすべてのデータを再ロードしたり、同じソースから利用可能な新しいデータをロードしたりするために使用できます。

    • AUTO - AUTO モードでは、ローダーは同じソースから以前のロードジョブを検索し、見つかった場合は、RESUME モードと同様にそのジョブを再開します。

      ローダーが同じソースから以前のロードジョブを見つけられない場合、NEW モードの場合と同様に、ソースからすべてのデータがロードされます。

  • failOnError - エラー時に完全な停止を切り替えるフラグ。

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

    デフォルト値: "TRUE"

    このパラメータを "FALSE" に設定すると、ローダーは指定された場所のすべてのデータをロードし、エラーのあるエントリはスキップします。

    このパラメータを "TRUE" に設定すると、ローダーはエラー発生時にすぐに停止します。その時点までロードされたデータは保持されます。

  • 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 - 追加のパーサー設定値のあるオプションのオブジェクト。それぞれの子パラメータもオプションです。

    名前 値の例 説明
    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

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

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

    詳細については、「SPARQL デフォルトグラフと名前が付いたグラフ」を参照してください。

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

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

    デフォルト値: "FALSE"

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

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

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

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

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

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

    デフォルト値: "FALSE"

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

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

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

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

    2. dependencies フィールドで 2 つのジョブの load-id を付けて load-job-C を送信します。

    "dependencies" : [\"job_A_load_id\", \"job_B_load_id\"]

    dependencies パラメータのため、Job-AJob-B が正常に完了するまで、バルクローダーは Job-C を起動しません。いずれかが失敗すると、Job-C は実行されず、そのステータスは LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED に設定されます。

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

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

    メトリックuserProvidedEdgeIds不在またはに設定されているTrue:ID列はロード内のすべてのリレーションシップファイルに存在する必要があります。

    メトリックuserProvidedEdgeIds存在し、に設定されているFalse、ロード中のリレーションシップファイルしてはいけないにはが含まれています:ID列。代わりに、Neptune ローダーは各リレーションシップの ID を自動的に生成します。

    CSV データのエラーが修正された後にローダーがロードを再開できるように、リレーションシップ ID を明示的に指定すると便利です。すでにロードされているリレーションシップをリロードする必要はありません。リレーションシップ ID が明示的に割り当てられていない場合、リレーションシップファイルを修正する必要があれば、ローダーは失敗したロードを再開できず、代わりにすべてのリレーションシップを再ロードする必要があります。

  • accessKey   –   [非推奨] S3 バケットおよびデータファイルにアクセスするための IAM ロールのアクセスキー ID。

    代わりに、iamRoleArn パラメータを使用することをお勧めします。Amazon S3 にアクセスできるロールを作成し、Neptune クラスターに関連付ける方法の詳細については、前提条件: IAM ロールと Amazon S3 アクセス を参照してください。

    詳細については、「アクセスキー (アクセスキー ID とシークレットアクセスキー)」を参照してください。

  • secretKey   –   [非推奨] 代わりに iamRoleArn パラメータを使用することをお勧めします。Amazon S3 にアクセスできるロールを作成し、Neptune クラスターに関連付ける方法の詳細については、前提条件: IAM ロールと Amazon S3 アクセス を参照してください。

    詳細については、「アクセスキー (アクセスキー ID とシークレットアクセスキー)」を参照してください。

openCypher データのロードに関する特別な考慮事項

  • openCypher データを CSV 形式でロードする場合、形式パラメータを opencypher に設定する必要があります。

  • すべての openCypher プロパティが単一のカーディナリティを持つため、updateSingleCardinalityProperties パラメータはopenCypher のロードではサポートされていません。openCypher ロードフォーマットは配列をサポートしておらず、ID 値が複数回表示される場合は、重複エラーまたは挿入エラーとして扱われます (下記参照)。

  • Neptune ローダーは openCypher データで検出された重複を次のように処理します。

    • ローダーが同じノード ID を持つ複数の行を検出すると、次のルールを使用してマージされます。

      • 行のすべてのラベルがノードに追加されます。

      • 各プロパティについて、プロパティ値の 1 つだけがロードされます。ロードするオブジェクトの選択は決定的ではありません。

    • ローダーが同じリレーションシップ ID を持つ複数の行を検出すると、そのうちの 1 つだけがロードされます。ロードするものの選択は決定的ではありません。

    • ローダーは、既存のノードまたはリレーションシップの 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 コードが返されます。

Neptune ローダーエラー

エラーが発生すると、JSON オブジェクトがレスポンスの BODY に返されます。message オブジェクトには、エラーの説明が含まれています。

エラーカテゴリ

  • Error 400 - 構文エラーは HTTP 400 無効なリクエストエラーを返します。エラーを説明するメッセージ。

  • Error 500 - 処理できない有効なリクエストは、HTTP 500 内部サーバーエラーを返します。エラーを説明するメッセージ。

以下は、ローダーからエラーの説明とともに返される可能性があるエラーメッセージです。

ローダーエラーメッセージ

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

    認証情報が見つかりませんでした。IAM コンソール、または AWS CLI 出力に提供された認証情報を確認します。

  • 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 DB インスタンスの 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" } }