屬性圖表結構描述

neptune.graph.pg_schema() 此程序提供 屬性圖形結構的完整概觀。它會傳回所有節點標籤、邊緣標籤、屬性及其資料類型，以及標籤三元組 ({~from, ~type, ~to}描述節點類型如何透過邊緣類型連線的模式）。

此程序目前只能透過 openCypher 端點使用，並探索所有屬性圖形資料的結構描述。

針對下列任務使用此程序：

與 Neptune Analytics 的比較

在 Neptune Analytics 中， neptune.graph.pg_schema() 是同步的。它會計算每次呼叫的結構描述。

在 Neptune 資料庫，您可以透過呼叫 明確觸發非同步結構描述運算neptune.graph.pg_schema.compute()，這會立即傳回。當您使用 輪詢完成時，運算會在背景執行neptune.graph.pg_schema()。計算後，Neptune 會保留結構描述，並在後續讀取時立即傳回結構描述，而無需重新計算。運算仍在進行中時，也提供部分結果。您也可以停止執行中的運算，稍後再繼續。

與圖形摘要 API 的比較

圖形摘要 API 不提供標籤三元組或屬性資料類型。屬性圖表結構描述程序會填滿此間隙。標籤三元組會顯示圖形中的特定關係模式。例如， Company會透過worksAt邊緣Person連線至 。此資訊對於 LLMs 產生語義正確的查詢至關重要。

先決條件

引擎版本

屬性圖表結構描述程序需要 Neptune 引擎 1.4.8.0 版或更新版本。

IAM 許可

每個結構描述操作都需要下列 IAM 動作：

compute() 和 stop()操作需要寫入許可，因為它們會修改用來快取和保留結構描述的內部狀態。

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "neptune-db:ReadDataViaQuery",
      "neptune-db:WriteDataViaQuery"
    ],
    "Resource": "arn:aws:neptune-db:us-east-1:123456789012:cluster-resource-id/*"
  }]
}

若要授予結構描述的唯讀存取權 （無法觸發運算），請僅使用 neptune-db:ReadDataViaQuery。

寫入器和讀取器執行個體

您只能在寫入器執行個體上觸發結構描述運算。僅供讀取複本執行個體可以讀取結構描述 （從寫入器複寫），但無法執行 compute()或 stop()。

API 參考

讀取結構描述

擷取目前的結構描述和運算狀態。

語法:

行為：立即傳回目前的結構描述和狀態。一律非封鎖。如果尚未計算結構描述， 會傳回狀態： "NotStarted"與空白結構描述欄位。如果運算正在進行中， 會傳回狀態為 的部分結果"InProgress"。

回應格式：

回應包含具有下列欄位的結構描述物件：

狀態物件：

結構描述物件：

支援的資料類型：String、Int、Long、Double、Bool、 Date

如果屬性在不同節點之間有多個資料類型 （例如，某些節點會以 age形式存放Int，而其他節點則以 形式存放String)，則所有觀察到的類型都會列在datatypes陣列中。

運算結構描述

觸發背景結構描述運算。

語法:

所需的 IAM 動作： neptune-db:ReadDataViaQuery 和 neptune-db:WriteDataViaQuery

參數：

行為：

回應：傳回顯示狀態的狀態物件： "InProgress" 與 concurrency progressPercentage 欄位。

停止結構描述運算

停止執行中的背景運算。

語法:

所需的 IAM 動作： neptune-db:ReadDataViaQuery 和 neptune-db:WriteDataViaQuery

行為：

回應：傳回顯示狀態的狀態物件："Stopped"使用目前的 progressPercentage。

搭配結構描述結果使用 YIELD

您可以使用 YIELD擷取結構描述欄位，並將其與其他查詢結合。下列範例會擷取所有節點標籤，並計算每個標籤的節點數量。collSort() 函數會依字母順序排序清單：

CALL neptune.graph.pg_schema()
  YIELD schema
  WITH schema.nodeLabels as nl
  UNWIND collSort(nl) as label
  MATCH (n)
  WHERE label in labels(n)
  RETURN label, COUNT(n) as count

輸出範例：

{
  "results": [{
      "label": "airport",
      "count": 3503
    }, {
      "label": "continent",
      "count": 7
    }, {
      "label": "country",
      "count": 237
    }, {
      "label": "version",
      "count": 1
    }]
}

結構描述運算生命週期

非同步操作

結構描述運算是一種非同步操作。當您呼叫 時neptune.graph.pg_schema.compute()，它會立即傳回目前狀態。運算會在背景執行。您可以透過呼叫 來輪詢進度和完成neptune.graph.pg_schema()，這會傳回目前狀態 和 progressPercentage。

州 (States)

結構描述運算會移動到下列狀態：

持續性和重新啟動行為

計算的結構描述會持續存在，並且可以承受引擎重新啟動。重新啟動行為取決於重新啟動時的狀態：

部分結果

當運算正在進行時， pg_schema()會傳回部分結果。這包括任何先前完成的結構描述，與目前運算中探索到的標籤、屬性和三元組合併。這表示您不需要等待完整運算完成，即可擷取有用的結構描述資訊。

僅供讀取複本

僅供讀取複本執行個體可以使用 讀取結構描述CALL neptune.graph.pg_schema()。Neptune 會從寫入器執行個體複寫結構描述，並在寫入器上發現結構描述元素時，在複本上幾乎立即可用。

僅供讀取複本無法執行 compute()或 stop()。這些呼叫會傳回錯誤：

最佳實務

限制

範例輸出

下列範例顯示 air-routes 資料集的結構描述輸出：

awscurl -X POST https://your-neptune-endpoint:port/openCypher \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --region us-east-1 --service neptune-db \
  -d 'query=CALL neptune.graph.pg_schema()'

{
  "results": [{
      "schema": {
        "edgeLabelDetails": {
          "route": {
            "properties": {
              "dist": ["Int"]
            }
          },
          "contains": {
            "properties": {}
          }
        },
        "edgeLabels": ["route", "contains"],
        "status": {
          "concurrency": "16",
          "lastComputedTimestamp": "2026-06-04T23:58:17Z",
          "state": "Completed",
          "progressPercentage": "100"
        },
        "nodeLabels": ["version", "continent", "airport", "country"],
        "labelTriples": [{
            "~type": "route",
            "~from": "airport",
            "~to": "airport"
          }, {
            "~type": "contains",
            "~from": "country",
            "~to": "airport"
          }, {
            "~type": "contains",
            "~from": "continent",
            "~to": "airport"
          }],
        "nodeLabelDetails": {
          "continent": {
            "properties": {
              "type": ["String"],
              "code": ["String"],
              "desc": ["String"]
            }
          },
          "airport": {
            "properties": {
              "type": ["String"],
              "city": ["String"],
              "icao": ["String"],
              "code": ["String"],
              "country": ["String"],
              "lat": ["Double"],
              "longest": ["Int"],
              "runways": ["Int"],
              "desc": ["String"],
              "lon": ["Double"],
              "region": ["String"],
              "elev": ["Int"]
            }
          },
          "country": {
            "properties": {
              "type": ["String"],
              "code": ["String"],
              "desc": ["String"]
            }
          },
          "version": {
            "properties": {
              "date": ["String"],
              "desc": ["String"],
              "author": ["String"],
              "type": ["String"],
              "code": ["String"]
            }
          }
        }
      }
    }]
}