Gremlin クエリ結果を Amazon S3 にエクスポートする

エンジンリリース 1.4.3.0 から、Amazon Neptune は Gremlin クエリ結果の Amazon S3 への直接エクスポートをサポートしています。この機能を使用すると、大規模なクエリ結果をクエリレスポンスとして返す代わりに Amazon S3 バケットにエクスポートすることで効率的に処理できます。

クエリ結果を Amazon S3 にエクスポートするには、サービス名 neptune.query.exportToS3 の call() ステップを Gremlin クエリの最後のステップとして使用します。Bytecode を使用する Tinkerpop ドライバーのターミナルステップは、call() ステップの後に追加できます。エクスポートパラメータは文字列値にする必要があります。

注記

call() ステップに neptune.query.exportToS3 があるクエリは、最後のステップとして使用されない場合、失敗します。バイトコードを使用する Gremlin クライアントは、ターミナルステップを使用できます。詳細については、Amazon Neptune ドキュメントの「Gremlin のベストプラクティス」を参照してください。


g.V()
  ...
  .call('neptune.query.exportToS3', [
    'destination': 's3://your-bucket/path/result.json',
    'format': 'GraphSONv3',
    'kmskeyArn': 'optional-kms-key-arn'
  ])

パラメータ

destination: 必須 - 結果が書き込まれる Amazon S3 URI。
format: 必須 - 出力形式。現在、'GraphSONv3' のみをサポートしています。
keyArn: 任意 - Amazon S3 サーバー側の暗号化用のAWS KMSキーの ARN。

例

クエリの例:


g.V().
    hasLabel('Comment').
    valueMap().
    call('neptune.query.exportToS3', [
    'destination': 's3://your-bucket/path/result.json',
    'format': 'GraphSONv3',
    'keyArn': 'optional-kms-key-arn'
  ])

クエリレスポンスの例


{
    "destination":"s3://your-bucket/path/result.json,
    "exportedResults": 100,
    "exportedBytes": 102400
}

前提条件

Neptune DB インスタンスは、ゲートウェイタイプの VPC エンドポイントを介して Amazon S3 にアクセスできる必要があります。
クエリでカスタム AWS KMS 暗号化を使用するには、Neptune の AWS KMS との通信を可能にする AWS KMS 用のインターフェイスタイプの VPC エンドポイントが必要です。
Neptune で IAM 認証を有効にする必要があります。また、ターゲットの Amazon S3 バケットに書き込むための適切な IAM アクセス権限が必要です。この権限がない場合、400 Bad Request エラー「クラスターで S3 Export の IAM 認証が有効になっている必要があります」が発生します。
ターゲットの Amazon S3 バケット
- ターゲットの Amazon S3 バケットはパブリックにすることはできません。Block public accessを有効にする必要があります。
- ターゲットの Amazon S3 送信先は空である必要があります。
- ターゲットの Amazon S3 バケットには、Delete expired object delete markers or incomplete multipart uploads に Delete incomplete multipart uploads のライフサイクルルールが必要です。詳細については、「Amazon S3 lifecycle management update - support for multipart uploads and delete markers」を参照してください。
- ターゲットの Amazon S3 バケットには、Delete expired object delete markers or incomplete multipart uploads をクエリ評価に要する値 (7 日間など) よりも大きい値に設定した Delete incomplete multipart uploads のライフサイクルルールが必要です。これは、不完全なアップロード (直接表示されないがコストが発生する) を、Neptune によって完了または中止できない場合 (インスタンス/エンジンの障害など) に削除するために必要です。詳細については、「Amazon S3 lifecycle management update - support for multipart uploads and delete markers」を参照してください。

重要な考慮事項

エクスポートステップは、Gremlin クエリの最後のステップである必要があります。
指定された Amazon S3 ロケーションにオブジェクトがすでに存在する場合、クエリは失敗します。
エクスポートクエリの最大クエリ実行時間は、11 時間 50 分に制限されています。この機能は、転送アクセスセッションを使用します。トークンの有効期限の問題を回避するため、現在 11 時間 50 分に制限されています。

注記
エクスポートクエリは引き続きクエリタイムアウトに従います。大規模なエクスポートの場合は、適切なクエリタイムアウトを使用する必要があります。
Amazon S3 への新しいオブジェクトのアップロードは、すべて自動的に暗号化されます。
エラーやクラッシュの発生時の不完全なマルチパートアップロードによるストレージコストを回避するには、Amazon S3 バケットで Delete incomplete multipart uploads を使用してライフサイクルルールを設定することをお勧めします。

レスポンスの形式

クエリ結果は直接返されるのではなく、ステータスやエクスポートの詳細など、エクスポートオペレーションに関するメタデータが返されます。Amazon S3 のクエリ結果は GraphSONv3 形式になります。


{
  "data": {
    "@type": "g:List",
    "@value": [
      {
        "@type": "g:Map",
        "@value": [
          "browserUsed",
          {
            "@type": "g:List",
            "@value": [
              "Safari"
            ]
          },
          "length",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Int32",
                "@value": 7
              }
            ]
          },
          "locationIP",
          {
            "@type": "g:List",
            "@value": [
              "192.0.2.0/24"
            ]
          },
          "creationDate",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Date",
                "@value": 1348341961000
              }
            ]
          },
          "content",
          {
            "@type": "g:List",
            "@value": [
              "no way!"
            ]
          }
        ]
      },
      {
        "@type": "g:Map",
        "@value": [
          "browserUsed",
          {
            "@type": "g:List",
            "@value": [
              "Firefox"
            ]
          },
          "length",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Int32",
                "@value": 2
              }
            ]
          },
          "locationIP",
          {
            "@type": "g:List",
            "@value": [
              "203.0.113.0/24"
            ]
          },
          "creationDate",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Date",
                "@value": 1348352960000
              }
            ]
          },
          "content",
          {
            "@type": "g:List",
            "@value": [
              "ok"
            ]
          }
        ]
      },
      
      
      ...
      
      
    ]
  }
}

セキュリティ

Amazon S3 に転送されるすべてのデータは、転送中に SSL を使用して暗号化されます。
エクスポートされたデータのサーバー側の暗号化に AWS KMS キーを指定できます。Amazon S3 は、デフォルトで新しいオブジェクトを暗号化します。バケットが特定の AWS KMS キーを使用するように設定されている場合、そのキーが使用されます。
Neptune は、エクスポートを開始する前に、ターゲットバケットが公開されていないことを確認します。
クロスアカウントエクスポートおよびクロスリージョンエクスポートはサポートされていません。

エラー処理

ターゲットの Amazon S3 バケットはパブリックです。
指定されたオブジェクトは既に存在します。
Amazon S3 バケットへ書き込むための十分なアクセス権限がありません。
クエリの実行が最大時間制限を超えています。

ベストプラクティス

Amazon S3 バケットライフサイクルルールを使用して、不完全なマルチパートアップロードをクリーンアップします。
Neptune ログとメトリクスを使用してエクスポートオペレーションを監視します。Gremlin ステータスエンドポイントをチェックして、クエリが現在実行されているかどうかを確認できます。クライアントがレスポンスを受信していない限り、クエリは実行中と見なされます。

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

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

ドキュメントの表記規則

トラブルシューティング

Gremlin Amazon S3 エクスポート機能へのアクセスの許可