グラフサマリーを取得する mode パラメータプロパティグラフサマリー RDF グラフサマリーサンプルの PG サマリーサンプルの RDF サマリー IAM とグラフサマリー一般的なグラフサマリーエラー

グラフに関する簡単なサマリーレポートを取得する

Neptune グラフサマリー API は、グラフに関する以下の情報を取得します。

プロパティ (PG) グラフの場合、グラフサマリー API は、ノードおよびエッジラベルとプロパティキーの読み取り専用リストを、ノード、エッジ、プロパティの数とともに返します。
リソース記述フレームワーク (RDF) グラフの場合、グラフサマリー API は、クラスと述語キーの読み取り専用リストを、クワッド、主語、述語の数とともに返します。

注記

グラフサマリー API は、Neptune エンジンリリース 1.2.1.0 で導入されました。

グラフサマリー API を使用すると、グラフのデータサイズと内容を大まかに把握できます。また、%summary Neptune Workbench マジックを使用して、Neptune ノートブック内でインタラクティブに API を使用することもできます。グラフアプリケーションでは、API を使用して、検出されたノードやエッジのラベルを検索の一部として指定することで、検索結果を改善できます。

グラフサマリーデータは、実行時に Neptune DFE エンジンによって計算された DFE 統計から抽出され、DFE 統計が利用可能な場合はいつでも利用できます。Neptune DB クラスターを新規作成すると、統計がデフォルトで有効になります。

注記

メモリを節約するため、t3 および t4 インスタンスタイプ (つまり、db.t3.medium および db.t4g.medium インスタンスタイプ) では、統計の生成が無効になっています。そのため、どちらのインスタンスタイプでもグラフサマリーデータは使用できません。

DFE 統計のステータスは、統計ステータス API を使用して確認できます。統計の自動生成が無効になっていない限り、統計は定期的に自動更新されます。

グラフサマリーをリクエストするときに統計をできるだけ最新の状態に保ちたい場合は、サマリーを取得する直前に、手動で統計の更新をトリガーできます。統計の計算中にグラフが変化する場合、必然的に少し遅れますが、それほど遅れることはありません。

グラフサマリー API を使用してグラフの概要情報を取得する

Gremlin または openCypher を使用してクエリを行うプロパティグラフの場合、プロパティグラフのサマリーエンドポイントからグラフの概要を取得できます。このエンドポイントには長い URI と短い URI の両方があります。

https://your-neptune-host:port/propertygraph/statistics/summary
https://your-neptune-host:port/pg/statistics/summary

SPARQL を使用してクエリを行う RDF グラフの場合、RDF サマリーエンドポイントからグラフの概要を取得できます。

https://your-neptune-host:port/rdf/statistics/summary

これらのエンドポイントは読み取り専用であり、HTTP GET 操作のみをサポートします。$GRAPH_SUMMARY_ENDPOINT がクエリしたいエンドポイントのアドレスに設定されている場合、次のように curl と HTTP GET を使用してサマリーデータを取得できます。


curl -G "$GRAPH_SUMMARY_ENDPOINT"

グラフの概要を取得しようとしたときに、使用できる統計がない場合、応答は次のようになります。


{
  "detailedMessage": "Statistics are not available. Summary can only be generated after statistics are available.",
  "requestId": "48c1f788-f80b-b69c-d728-3f6df579a5f6",
  "code": "StatisticsNotAvailableException"
}

グラフサマリー API の `mode` URL クエリパラメータ

グラフサマリー API は、mode という名前の URL クエリパラメータを受け付けます。このパラメータには、basic (デフォルト) と detailed の 2 つの値のいずれかを指定できます。RDF グラフの場合、detailed モードグラフサマリーレスポンスには追加の subjectStructures フィールドが含まれます。プロパティグラフの場合、詳細グラフサマリーレスポンスには、nodeStructures と edgeStructures という 2 つの追加フィールドが含まれます。

detailed グラフサマリーレスポンスをリクエストするには、以下の mode パラメータを含めてください。


curl -G "$GRAPH_SUMMARY_ENDPOINT?mode=detailed"

mode パラメータが存在しない場合、デフォルトで basic モードが使用されるため、明示的に ?mode=basic を指定することも可能ですが、必須ではありません。

プロパティグラフ (PG) のグラフサマリーレスポンス

空のプロパティグラフの場合、詳細なグラフサマリーレスポンスは次のようになります。


{
  "status" : "200 OK",
  "payload" : {
    "version" : "v1",
    "lastStatisticsComputationTime" : "2023-01-10T07:58:47.972Z",
    "graphSummary" : {
      "numNodes" : 0,
      "numEdges" : 0,
      "numNodeLabels" : 0,
      "numEdgeLabels" : 0,
      "nodeLabels" : [ ],
      "edgeLabels" : [ ],
      "numNodeProperties" : 0,
      "numEdgeProperties" : 0,
      "nodeProperties" : [ ],
      "edgeProperties" : [ ],
      "totalNodePropertyValues" : 0,
      "totalEdgePropertyValues" : 0,
      "nodeStructures" : [ ],
      "edgeStructures" : [ ]
    }
  }
}

プロパティグラフ (PG) サマリーレスポンスには以下のフィールドがあります。

status — リクエストの HTTP リターンコード。リクエストが成功した場合、コードは 200 です。

共通エラーリストについては、一般的なグラフサマリーエラーを参照してください。
payload
- version - このグラフサマリーレスポンスのバージョン。
- lastStatisticsComputationTime - Neptune が最後に統計を計算した時刻のタイムスタンプ (ISO 8601 形式)。
- graphSummary
  - numNodes - グラフ内のノードの数。
  - numEdges - グラフ内のエッジの数。
  - numNodeLabels - グラフ内の異なるノードラベルの数。
  - numEdgeLabels - グラフ内の異なるエッジラベルの数。
  - nodeLabels - グラフ内の異なるノードラベルのリスト。
  - edgeLabels - グラフ内の異なるエッジラベルのリスト。
  - numNodeProperties - グラフ内の異なるノードプロパティの数。
  - numEdgeProperties - グラフ内の異なるエッジプロパティの数。
  - nodeProperties - グラフ内の異なるノードプロパティのリストと、各プロパティが使用されるノードの数。
  - edgeProperties - グラフ内の異なるエッジプロパティのリストと、各プロパティが使用されるエッジの数。
  - totalNodePropertyValues - すべてのノードプロパティの使用回数の合計。
  - totalEdgePropertyValues - すべてのエッジプロパティの使用回数の合計。
  - nodeStructures — このフィールドは、リクエストで mode=detailed が指定されている場合にのみ表示されます。ノード構造のリストを含み、各ノード構造は以下のフィールドを含みます。
    
    count - この特定の構造を持つノードの数。
    nodeProperties - この特定の構造に存在するノードプロパティのリスト。
    distinctOutgoingEdgeLabels - この特定の構造に存在する個別の出力エッジラベルのリスト。
  - edgeStructures — このフィールドは、リクエストで mode=detailed が指定されている場合にのみ表示されます。エッジ構造のリストを含み、各エッジ構造は以下のフィールドを含みます。
    
    count - この特定の構造を持つエッジの数。
    edgeProperties - この特定の構造に存在するエッジプロパティのリスト。

RDF グラフのグラフサマリーレスポンス

空の RDF グラフの場合、詳細なグラフサマリーレスポンスは次のようになります。


{
  "status" : "200 OK",
  "payload" : {
    "version" : "v1",
    "lastStatisticsComputationTime" : "2023-01-10T07:58:47.972Z",
    "graphSummary" : {
      "numDistinctSubjects" : 0,
      "numDistinctPredicates" : 0,
      "numQuads" : 0,
      "numClasses" : 0,
      "classes" : [ ],
      "predicates" : [ ],
      "subjectStructures" : [ ]
    }
  }
}

RDF グラフサマリーレスポンスには以下のフィールドがあります。

status — リクエストの HTTP リターンコード。リクエストが成功した場合、コードは 200 です。

共通エラーリストについては、一般的なグラフサマリーエラーを参照してください。
payload
- version - このグラフサマリーレスポンスのバージョン。
- lastStatisticsComputationTime - Neptune が最後に統計を計算した時刻のタイムスタンプ (ISO 8601 形式)。
- graphSummary
  - numDistinctSubjects — グラフ内の異なるサブジェクトの数。
  - numDistinctPredicates — グラフ内の異なる述語の数。
  - numQuads - グラフ内のクワッドの数。
  - numClasses - グラフ内のクラスの数。
  - classes — グラフ内のクラスのリスト。
  - predicates — グラフ内の述語のリストと述語の数。
  - subjectStructures — このフィールドは、リクエストで mode=detailed が指定されている場合にのみ表示されます。サブジェクト構造のリストを含み、各構造は以下のフィールドを含みます。
    
    count - この特定の構造の出現回数。
    predicates - この特定の構造に存在する述語のリスト。

サンプルのプロパティグラフ (PG) サマリーレスポンス

以下は、サンプルプロパティグラフの航空路データセットを含むプロパティグラフの詳細なサマリーレスポンスです。


{
  "status" : "200 OK",
  "payload" : {
    "version" : "v1",
    "lastStatisticsComputationTime" : "2023-03-01T14:35:03.804Z",
    "graphSummary" : {
      "numNodes" : 3748,
      "numEdges" : 51300,
      "numNodeLabels" : 4,
      "numEdgeLabels" : 2,
      "nodeLabels" : [
        "continent",
        "country",
        "version",
        "airport"
      ],
      "edgeLabels" : [
        "contains",
        "route"
      ],
      "numNodeProperties" : 14,
      "numEdgeProperties" : 1,
      "nodeProperties" : [
        {
          "desc" : 3748
        },
        {
          "code" : 3748
        },
        {
          "type" : 3748
        },
        {
          "country" : 3503
        },
        {
          "longest" : 3503
        },
        {
          "city" : 3503
        },
        {
          "lon" : 3503
        },
        {
          "elev" : 3503
        },
        {
          "icao" : 3503
        },
        {
          "region" : 3503
        },
        {
          "runways" : 3503
        },
        {
          "lat" : 3503
        },
        {
          "date" : 1
        },
        {
          "author" : 1
        }
      ],
      "edgeProperties" : [
        {
          "dist" : 50532
        }
      ],
      "totalNodePropertyValues" : 42773,
      "totalEdgePropertyValues" : 50532,
      "nodeStructures" : [
        {
          "count" : 3471,
          "nodeProperties" : [
            "city",
            "code",
            "country",
            "desc",
            "elev",
            "icao",
            "lat",
            "lon",
            "longest",
            "region",
            "runways",
            "type"
          ],
          "distinctOutgoingEdgeLabels" : [
            "route"
          ]
        },
        {
          "count" : 161,
          "nodeProperties" : [
            "code",
            "desc",
            "type"
          ],
          "distinctOutgoingEdgeLabels" : [
            "contains"
          ]
        },
        {
          "count" : 83,
          "nodeProperties" : [
            "code",
            "desc",
            "type"
          ],
          "distinctOutgoingEdgeLabels" : [ ]
        },
        {
          "count" : 32,
          "nodeProperties" : [
            "city",
            "code",
            "country",
            "desc",
            "elev",
            "icao",
            "lat",
            "lon",
            "longest",
            "region",
            "runways",
            "type"
          ],
          "distinctOutgoingEdgeLabels" : [ ]
        },
        {
          "count" : 1,
          "nodeProperties" : [
            "author",
            "code",
            "date",
            "desc",
            "type"
          ],
          "distinctOutgoingEdgeLabels" : [ ]
        }
      ],
      "edgeStructures" : [
        {
          "count" : 50532,
          "edgeProperties" : [
            "dist"
          ]
        }
      ]
    }
  }
}

サンプルの RDF グラフサマリーレスポンス

以下は、サンプルの RDF 航空路データセットを含む RDF グラフの詳細なサマリーレスポンスです。


{
  "status" : "200 OK",
  "payload" : {
    "version" : "v1",
    "lastStatisticsComputationTime" : "2023-03-01T14:54:13.903Z",
    "graphSummary" : {
      "numDistinctSubjects" : 54403,
      "numDistinctPredicates" : 19,
      "numQuads" : 158571,
      "numClasses" : 4,
      "classes" : [
        "http://kelvinlawrence.net/air-routes/class/Version",
        "http://kelvinlawrence.net/air-routes/class/Airport",
        "http://kelvinlawrence.net/air-routes/class/Continent",
        "http://kelvinlawrence.net/air-routes/class/Country"
      ],
      "predicates" : [
        {
          "http://kelvinlawrence.net/air-routes/objectProperty/route" : 50656
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/dist" : 50656
        },
        {
          "http://kelvinlawrence.net/air-routes/objectProperty/contains" : 7004
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/code" : 3747
        },
        {
          "http://www.w3.org/2000/01/rdf-schema#label" : 3747
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/type" : 3747
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/desc" : 3747
        },
        {
          "http://www.w3.org/1999/02/22-rdf-syntax-ns#type" : 3747
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/icao" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/lat" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/region" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/runways" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/longest" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/elev" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/lon" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/country" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/city" : 3502
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/author" : 1
        },
        {
          "http://kelvinlawrence.net/air-routes/datatypeProperty/date" : 1
        }
      ],
      "subjectStructures" : [
        {
          "count" : 50656,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/dist"
          ]
        },
        {
          "count" : 3471,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/city",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/code",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/country",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/desc",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/elev",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/icao",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/lat",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/lon",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/longest",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/region",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/runways",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/type",
            "http://kelvinlawrence.net/air-routes/objectProperty/route",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2000/01/rdf-schema#label"
          ]
        },
        {
          "count" : 238,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/code",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/desc",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/type",
            "http://kelvinlawrence.net/air-routes/objectProperty/contains",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2000/01/rdf-schema#label"
          ]
        },
        {
          "count" : 31,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/city",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/code",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/country",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/desc",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/elev",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/icao",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/lat",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/lon",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/longest",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/region",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/runways",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/type",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2000/01/rdf-schema#label"
          ]
        },
        {
          "count" : 6,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/code",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/desc",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/type",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2000/01/rdf-schema#label"
          ]
        },
        {
          "count" : 1,
          "predicates" : [
            "http://kelvinlawrence.net/air-routes/datatypeProperty/author",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/code",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/date",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/desc",
            "http://kelvinlawrence.net/air-routes/datatypeProperty/type",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2000/01/rdf-schema#label"
          ]
        }
      ]
    }
  }
}

グラフサマリーエンドポイントでの AWS Identity and Access Management (IAM) 認証の使用

グラフサマリーエンドポイントには、awscurl または、HTTP および IAM で動作するその他のツールを使用して IAM 認証で安全にアクセスできます。適切な認証情報を設定する方法については、「一時的な認証情報で awscurl を使用して、IAM 認証が有効になっている DB クラスターに安全に接続する」を参照してください。設定が完了したら、次のようなリクエストを行うことができます。


awscurl "$GRAPH_SUMMARY_ENDPOINT" \
    --region (your region) \
    --service neptune-db

重要

一時的な認証情報を作成する IAM ID またはロールには、GetGraphSummary IAM アクションを許可する IAM ポリシーがアタッチされている必要があります。

よく発生する IAM エラーのリストについては、「IAM 認証エラー」を参照してください。

グラフサマリーリクエストが返す可能性のある一般的なエラーコード

Neptune サービスのエラーコード	HTTP ステータス	メッセージ	エラーシナリオ	緩和
`AccessDeniedException`	403	認証トークンが見つかりません。	署名されていない、または正しく署名されていないリクエストが IAM が有効な Neptune データベースに送信されました。	送信する前に SigV4 でリクエストに署名してください (「IAM とグラフサマリー」を参照)。
`AccessDeniedException`	403	ユーザー: `(ユーザー ARN)` は、リソース: `(リソース ARN)` に対して neptune-db:GetGraphSummary を実行することを承認されていません。	IAM ポリシーでは、IAM が有効になっている Neptune データベースにグラフサマリーリクエストが送信された場合、GetGraphSummary アクションは許可されません。	リクエストを行うユーザーまたはロールにアタッチされている IAM ポリシーが `GetGraphSummary` アクションを許可していることを確認してください。
`BadRequestException`	400	統計は無効になっているため、グラフサマリーも無効になっています。	統計が無効になっているバースト可能なインスタンスタイプ (`t3` または `t4g`) でサマリーを取得しようとしています。	統計の生成が有効になっているインスタンスタイプを使用してください (`t3` と `t4g` を除くすべてのサポート対象インスタンス)。
`BadRequestException`	400	不正なルート: `/rdf/statistics/summarypathapi`	無効なパスに送信されたリクエスト。	グラフサマリーエンドポイントには正しいルートを使用してください。
`InvalidParameterException`	400	リクエストに未知のパラメータが含まれています: '`(不明なパラメータ)`'。	リクエストで無効なパラメータが指定されている場合。	リクエストには有効なパラメータ (`mode` など) のみを使用してください。
`InvalidParameterException`	400	URI クエリパラメータ 'mode' にサポートされていない値 '`(無効な値)`' があります。	リクエストの URL パラメータ 'mode' の後に無効な値が続く場合。	URL パラメータ 'mode' を指定するときには、有効な値 (`basic` や `detailed` など) を使用してください。
`MethodNotAllowedException`	405	許されないメソッド。	`GET` 以外の HTTP メソッド (`POST` や `DELETE` など) を使用してサマリーエンドポイントを呼び出す。	サマリーエンドポイントを呼び出すときには、HTTP `GET` メソッドを使用してください。
`StatisticsNotAvailableException`	400	統計はまだ計算されていません。統計の計算が完了すると、グラフサマリーが使用可能になります。	リクエストがサマリーエンドポイントに送信されたとき、利用できる統計がありません。	統計の生成が完了するまで待ちます。統計生成のステータスは、統計ステータス API を使用して確認できます。
`StatisticsNotAvailableException`	400	統計の上限に達したため、グラフサマリーは使用できません。	統計サイズ制限に達したため、統計の生成が停止しました。	このグラフに関するグラフサマリーは使用可能ではありません。

例えば、IAM 認証が有効になっている Neptune データベースで、必要なアクセス許可がリクエスタの IAM ポリシーにないとき、グラフサマリーエンドポイントにリクエストを行うと、次のようなレスポンスを受信します。


{
  "detailedMessage": "User: arn:aws:iam::(account ID):(user or user name) is not authorized to perform: neptune-db:GetGraphSummary on resource: arn:aws:neptune-db:(region):(account ID):(cluster resource ID)/*",
  "requestId": "7ac2b98e-b626-d239-1d05-74b4c88fce82",
  "code": "AccessDeniedException"
}

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

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

ドキュメントの表記規則

DFE 統計

JDBC 接続