Neptune ローダーコマンド

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

データをロードするには、https://your-neptune-endpoint:port/loaderエンドポイントに HTTP POST リクエストを送信する必要があります。loader リクエストのパラメータは、POST本文で送信することも、 URLでエンコードされたパラメータとして送信することもできます。

重要

MIME タイプはである必要がありますapplication/json。

S3 バケットは同じにある必要があります AWS クラスターとしてのリージョン。

注記

Amazon S3 SSE-S3 モードを使用して暗号化されている場合は、Amazon S3 から暗号化されたデータを読み込むことができます。その場合、Neptune はユーザーの認証情報を偽装し、ユーザーに代わって s3:getObject 呼び出しを発行することができます。

IAM ロールにアクセスに必要なアクセス許可が含まれている限り、 SSE-KMS モードを使用して暗号化された Amazon S3 から暗号化されたデータをロードすることもできます。 AWS KMS。適切でない AWS KMS アクセス許可、一括ロードオペレーションは失敗し、LOAD_FAILEDレスポンスを返します。

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

別のジョブを開始する前に、1 つのロードジョブが完了するのを待つ必要はありません。Neptune は、queueRequest パラメータがすべて "TRUE" に設定されている場合、一度に最大 64 個のロードリクエストをキューに入れることができます。ジョブのキュー順序は first-in-first-out () になりますFIFO。一方、ロードジョブをキューに入れたくない場合は、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 パラメータは、単一のファイル、複数のファイル、フォルダ、または複数のフォルダURIを識別する Amazon S3 を受け入れます。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-name要素は、Amazon S3 ListObjectsAPI呼び出しのプレフィックスパラメータと同等URIです。これは、名前がそのプレフィックスで始まる指定された Amazon S3 バケット内のすべてのオブジェクトを識別します。これは、単一のファイルまたはフォルダ、または複数のファイルやフォルダにすることができます。

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

たとえば、という名前の Amazon S3 バケットに次のフォルダ構造とファイルがある場合ですbucket-name。
```
s3://bucket-name/a/bc
s3://bucket-name/ab/c
s3://bucket-name/ade
s3://bucket-name/bcd
```
ソースパラメータがとして指定されている場合s3://bucket-name/a、最初の 3 つのファイルがロードされます。
```
s3://bucket-name/a/bc
s3://bucket-name/ab/c
s3://bucket-name/ade
```
format - データの形式。Neptune Loader コマンドのデータ形式の詳細については、Amazon Neptune 一括ローダーを使用したデータの取り込みを参照してください。
許可される値
- csv Gremlin CSV データ形式の。
- opencypher openCypher CSV データ形式の。
- ntriples N-Triples RDF データ形式の。
- nquads N-Quads RDF データ形式の。
- rdfxml RDF\XML RDF データ形式の。
- turtle Turtle RDF データ形式の。
iamRoleArn – S3 バケットにアクセスするために Neptune DB インスタンスが引き受ける IAMロールの Amazon リソースネーム (ARN）。Amazon S3 にアクセスできるロールを作成し、Neptune クラスターに関連付ける方法の詳細については、前提条件: IAM ロールと Amazon S3 アクセスを参照してください。

エンジンリリース 1.2.1.0.R3 以降、Neptune DB インスタンスと Amazon S3 バケットが異なるにある場合、複数のIAMロールを連鎖させることもできます。 AWS アカウント。この場合、 iamRoleArnには、「」で説明されているようにARNs、ロールのカンマ区切りリストが含まれていますAmazon Neptune でのIAMロールの連鎖。例:
```
curl -X POST https://localhost:8182/loader \
  -H 'Content-Type: application/json' \
  -d '{
        "source" : "s3://(the target bucket name)/(the target date file name)",
        "iamRoleArn" : "arn:aws:iam::(Account A ID):role/(RoleA),arn:aws:iam::(Account B ID):role/(RoleB),arn:aws:iam::(Account C ID):role/(RoleC)",
        "format" : "csv",
        "region" : "us-east-1"
      }'
```
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-south-2
- 欧州 (アイルランド): eu-west-1
- 欧州 (ロンドン): eu-west-2
- 欧州 (パリ): eu-west-3
- 欧州 (フランクフルト): eu-central-1
- 中東 (バーレーン): me-south-1
- 中東 (UAE): me-central-1
- イスラエル (テルアビブ): il-central-1
- アフリカ (ケープタウン): af-south-1
- アジアパシフィック (香港): ap-east-1
- アジアパシフィック (東京): ap-northeast-1
- アジアパシフィック (ソウル): ap-northeast-2
- アジアパシフィック (大阪): ap-northeast-3
- アジアパシフィック (シンガポール): ap-southeast-1
- アジアパシフィック (シドニー): ap-southeast-2
- アジアパシフィック (ジャカルタ): ap-southeast-3
- アジアパシフィック (ムンバイ): 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 – 使用するスレッドの数は、使用可能なの数を 8 で vCPUs 割ったものです。
- MEDIUM – 使用するスレッドの数は、使用可能なの数を 2 で vCPUs 割ったものです。
- HIGH – 使用されるスレッドの数は、使用可能なの数と同じですvCPUs。
- OVERSUBSCRIBE – 使用するスレッドの数は、使用可能なスレッドの数に 2 を vCPUs 掛けたものです。この値を使用する場合、バルクローダーは利用可能なすべてのリソースを消費します。
  
  ただし、この設定によってCPU使用率が 100% OVERSUBSCRIBEになるわけではありません。ロードオペレーションは I/O バウンドであるため、予想される最大CPU使用率は 60%～70% の範囲です。
デフォルト値: HIGH

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

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

名前値の例説明

namedGraphUri http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph グラフが指定されていない場合のすべてのRDF形式のデフォルトグラフ (非四角形形式およびグラフなしのNQUADエントリの場合）。デフォルトはです。http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph

baseUri http://aws.amazon.com/neptune/default RDF/ URI XML およびタートル形式のベース。デフォルト: http://aws.amazon.com/neptune/default。

名前	値の例	説明
`namedGraphUri`	`http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph`	グラフが指定されていない場合のすべてのRDF形式のデフォルトグラフ (非四角形形式およびグラフなしのNQUADエントリの場合）。デフォルトはです。`http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph`
`baseUri`	`http://aws.amazon.com/neptune/default`	RDF/ URI XML およびタートル形式のベース。デフォルト: `http://aws.amazon.com/neptune/default`。
`allowEmptyStrings`	`true`	Gremlin ユーザーは、CSVデータをロードするときに、空の文字列値 ("") をノードおよびエッジプロパティとして渡す必要があります。`allowEmptyStrings` が `false` (デフォルト) に設定されている場合、そのような空の文字列は NULL として扱われ、ロードされません。 `allowEmptyStrings` が `true` に設定されている場合、ローダーは空の文字列を有効なプロパティ値として扱い、それに応じてロードします。

allowEmptyStrings

true

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

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

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

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

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

デフォルト値: "FALSE"。

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

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

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

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

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

デフォルト値: "FALSE"。
dependencies - これは、キュー内の 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 つのジョブが失敗すると、直接的または間接的に依存するすべてのリクエストがキャンセルされます。
userProvidedEdgeIds – このパラメータは、リレーションシップを含む openCypher データをロードする場合にのみ必要ですIDs。ロードデータに openCypher 関係IDsが明示的に提供されるTrue場合 (推奨）、これを含めてに設定する必要があります。

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

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

リレーションシップをIDs明示的に提供して、ロード済みのリレーションシップを再ロードしなくても、CSVデータのエラーが修正された後にローダーがロードを再開できるようにしておくと便利です。リレーションシップIDsが明示的に割り当てられていない場合、リレーションシップファイルを修正する必要がある場合、ローダーは失敗したロードを再開できず、代わりにすべてのリレーションシップを再ロードする必要があります。
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を持つ複数の行を検出すると、次のルールを使用してマージされます。
  - 行のすべてのラベルがノードに追加されます。
  - 各プロパティには、プロパティ値が 1 つだけ読み込まれます。ロードする値の選択は決定的ではありません。
- ローダーが同じリレーションシップ ID を持つ複数の行を検出すると、そのうちの 1 つだけがロードされます。ロードする行の選択は決定的ではありません。
- ローダーは、既存のノードまたはリレーションシップの ID を持つロード・データに遭遇した場合、データベース内の既存のノードまたはリレーションシップのプロパティ値を更新することはありません。ただし、既存のノードやリレーションシップには存在しないノードラベルやプロパティがロードされます。
リレーションシップIDsに割り当てる必要はありませんが、通常はお勧めします (上記の userProvidedEdgeIds パラメータを参照）。明示的なリレーションシップがない場合IDs、ローダーは、障害が発生した場所からロードを再開するのではなく、リレーションシップファイルにエラーが発生した場合にすべてのリレーションシップを再ロードする必要があります。

また、ロードデータに明示的なリレーションシップが含まれていない場合IDs、ローダーは重複するリレーションシップを検出する方法がありません。

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 ローダーエラー

エラーが発生すると、レスポンス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)

バケットは同じにある必要があります AWS Neptune DB インスタンスとしてのリージョン。
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 コマンドHTTPPOSTを使用してを介して送信されるリクエストです。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"
    }
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ローダーリファレンス

ステータスの取得 API