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 個のロードリクエストをキューに入れることができます。ジョブのキュー順序は 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 パラメータは、単一のファイル、複数のファイル、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
URI object-key-name の要素は、Amazon S3 ListObjectsAPI 呼び出しのプレフィックスパラメータと同じです。これは、名前がそのプレフィックスで始まる指定された Amazon S3 バケット内のすべてのオブジェクトを識別します。これは、単一のファイルまたはフォルダ、または複数のファイルやフォルダにすることができます。

特定のフォルダには複数の頂点ファイルおよび複数のエッジファイルが含まれている場合があります。
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 この場合、Amazon Neptune で IAM ロールを連鎖するで説明されているように、iamRoleArn にはロール ARN のカンマ区切りのリストが含まれます。例:
```
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-west-1
- 欧州 (ロンドン): eu-west-2
- 欧州 (パリ): eu-west-3
- 欧州 (フランクフルト): eu-central-1
- 中東 (バーレーン): me-south-1
- 中東 (アラブ首長国連邦): 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-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 で割った値です。
- 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.

名前	値の例	説明
`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 データをロードするときに、ノードおよびエッジプロパティとして空の文字列値 ("") を渡す必要があります。`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 — このパラメータは、リレーションシップ 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 コンソールまたは出力と照合して確認します。iamRoleArn で指定した IAM ロールをクラスターに追加したことを確認します。
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"
    }
}

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

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

ドキュメントの表記規則

ローダーリファレンス

Get-Status API