翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# プロパティグラフスキーマ
`neptune.graph.pg_schema()` この手順では、プロパティグラフ構造の包括的な概要を示します。すべてのノードラベル、エッジラベル、データ型を持つプロパティ、ラベルトリプル (`{~from, ~type, ~to}`ノード型がエッジ型を介して接続する方法を説明するパターン) を返します。
この手順は現在 openCypher エンドポイントを介してのみ使用でき、すべてのプロパティグラフデータのスキーマを検出します。
この手順は、次のようなタスクに使用します。
+ **AI および LLM クエリ生成** – LLMs に、自然言語 (Text-to-Cypher、GraphRAG アプリケーション) から有効な Cypher クエリを生成するために必要なグラフ構造を提供します。
+ **グラフの視覚化と探索** – [Graph Explorer](visualization-graph-explorer.md) などのツールは、スキーマ情報を使用して、データベース全体をスキャンせずにグラフデータのインタラクティブな視覚的表現をレンダリングします。
+ **アプリケーションスキーマ検出** – GraphQL スキーマジェネレーターやデータ検証ツールなど、起動時にグラフ構造を理解する必要があるアプリケーション。
## Neptune Analytics との比較
Neptune Analytics では、 [`neptune.graph.pg_schema()`](https://docs.aws.amazon.com/neptune-analytics/latest/userguide/custom-algorithms-property-graph-schema.html)は同期です。呼び出しごとにスキーマを計算します。
Neptune データベースでは、 を呼び出して非同期スキーマ計算を明示的にトリガーします。`neptune.graph.pg_schema.compute()`これはすぐに を返します。計算は、 を使用して完了をポーリングしている間にバックグラウンドで実行されます`neptune.graph.pg_schema()`。計算後、Neptune はスキーマを保持し、再計算せずに後続の読み取りですぐに返します。計算がまだ進行中は、部分的な結果も使用できます。実行中の計算を停止し、後で再開することもできます。
## Graph Summary API との比較
[Graph Summary API](neptune-graph-summary.md) は、ラベルトリプルまたはプロパティデータ型を提供しません。プロパティグラフスキーマプロシージャはこのギャップを埋めます。ラベルトリプルは、グラフ内の特定の関係パターンを表示します。たとえば、 は`worksAt`エッジ`Company`を介して `Person`に接続します。この情報は、LLMs が意味的に正しいクエリを生成するために重要です。
## 前提条件
### エンジンバージョン
プロパティグラフスキーマプロシージャには、Neptune エンジンバージョン 1.4.8.0 以降が必要です。
### IAM アクセス許可
スキーマオペレーションごとに、次の IAM アクションが必要です。
+ `CALL neptune.graph.pg_schema()` – には が必要です`neptune-db:ReadDataViaQuery`。
+ `CALL neptune.graph.pg_schema.compute()` – には `neptune-db:ReadDataViaQuery`と が必要です`neptune-db:WriteDataViaQuery`。
+ `CALL neptune.graph.pg_schema.stop()` – には `neptune-db:ReadDataViaQuery`と が必要です`neptune-db:WriteDataViaQuery`。
`compute()` および `stop()`オペレーションでは、スキーマのキャッシュと保持に使用される内部状態を変更するため、書き込みアクセス許可が必要です。
**Example IAM ポリシーの例**
次のポリシーは、すべてのスキーマオペレーションに必要な最小限のアクセス許可を付与します。
```
{
"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 リファレンス
### スキーマの読み取り
現在のスキーマと計算ステータスを取得します。
**構文:**
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://{{your-neptune-endpoint}}:{{port}} \
--open-cypher-query "CALL neptune.graph.pg_schema()"
```
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://{{your-neptune-endpoint}}:{{port}}',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_query(
openCypherQuery='CALL neptune.graph.pg_schema()'
)
print(response)
```
------
#### [ awscurl ]
```
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()'
```
------
**動作:** 現在のスキーマとステータスですぐに を返します。常にノンブロッキングです。スキーマが計算されていない場合、 は空のスキーマフィールド`"NotStarted"`で state: を返します。計算が進行中の場合、 は状態 の部分的な結果を返します`"InProgress"`。
**レスポンス形式:**
レスポンスには、次のフィールドを持つスキーマオブジェクトが含まれます。
**ステータスオブジェクト:**
+ `state` (文字列) – 現在のライフサイクル状態: `NotStarted`、`InProgress`、`Completed`、`Stopped`、 `Failed`
+ `concurrency` (文字列) – 計算に使用されるスレッドの数。0 は自動 (ハードウェアに基づいて決定) を意味します。範囲: 1 (最低）～16 (最高）。
+ `lastComputedTimestamp` (文字列) – 最後に成功した計算の ISO-8601 UTC タイムスタンプ (例: `2026-05-29T08:00:00Z`)
+ `progressPercentage` (文字列) – 計算の進行状況: 未開始の場合は 0、計算中は 0～99、完了の場合は 100
+ `errorMessage` (文字列) – リクエストが拒否されたか、計算が失敗した場合にのみ表示されます。理由について説明します。
**スキーマオブジェクト:**
+ `nodeLabels` – グラフ内のすべての一意のノードラベルの配列
+ `edgeLabels` – グラフ内のすべての一意のエッジラベルの配列
+ `nodeLabelDetails` – ノードラベルごとに: プロパティとそのデータ型
+ `edgeLabelDetails` – エッジラベルごとに: プロパティとそのデータ型
+ `labelTriples` – 関係パターンの配列: どのノードタイプがどのエッジタイプを介して接続するかを`{~from, ~type, ~to}`記述する
**サポートされているデータ型:** `String`、`Int`、、`Long`、`Double``Bool`、 `Date`
プロパティに異なるノード間で複数のデータ型がある場合 (たとえば、一部のノードは `age`として格納`Int`され、他のノードは として格納されます`String`)、観測されたすべての型が`datatypes`配列に一覧表示されます。
### コンピューティングスキーマ
バックグラウンドスキーマ計算をトリガーします。
**構文:**
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://{{your-neptune-endpoint}}:{{port}} \
--open-cypher-query "CALL neptune.graph.pg_schema.compute()"
```
オプションの同時実行パラメータの場合:
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://{{your-neptune-endpoint}}:{{port}} \
--open-cypher-query "CALL neptune.graph.pg_schema.compute({concurrency: 2})"
```
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://{{your-neptune-endpoint}}:{{port}}',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_query(
openCypherQuery='CALL neptune.graph.pg_schema.compute()'
)
print(response)
```
------
#### [ awscurl ]
```
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.compute()'
```
オプションの同時実行パラメータの場合:
```
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.compute({concurrency: 2})'
```
------
**必要な IAM アクション:** `neptune-db:ReadDataViaQuery`および `neptune-db:WriteDataViaQuery`
**パラメータ :**
+ `concurrency` (整数、オプション) – バックグラウンド計算のスレッド数。0 (デフォルト) = ハードウェアに基づいて自動的に決定されます。範囲: 1 (最低）～16 (最高）。リソースへの影響を減らすには、小さいインスタンスで低い値を使用します。
**動作:**
+ 現在のステータスですぐに を返します。計算はバックグラウンドで非同期的に実行されます。
+ 状態が の場合に呼び出されると`Stopped`、計算は中断した場所から再開されます。
+ 状態が の場合に呼び出されると`Completed`、 は新しい再計算を開始します。前のスキーマは、新しい計算が完了するまで読み取りの処理を続けます。
+ 計算がすでに の場合に呼び出されると`InProgress`、Neptune はエラーメッセージとともにリクエストを拒否します。
+ アクティブな一括ロード中に呼び出された場合、Neptune はエラーメッセージとともにリクエストを拒否します。
**レスポンス:** 状態を示すステータスオブジェクトを返します。 `"InProgress"` `concurrency`フィールドと `progressPercentage`フィールドがあります。
### スキーマ計算の停止
実行中のバックグラウンド計算を停止します。
**構文:**
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://{{your-neptune-endpoint}}:{{port}} \
--open-cypher-query "CALL neptune.graph.pg_schema.stop()"
```
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://{{your-neptune-endpoint}}:{{port}}',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_query(
openCypherQuery='CALL neptune.graph.pg_schema.stop()'
)
print(response)
```
------
#### [ awscurl ]
```
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.stop()'
```
------
**必要な IAM アクション:** `neptune-db:ReadDataViaQuery`および `neptune-db:WriteDataViaQuery`
**動作:**
+ 実行中の計算を停止します。進行状況が保存されるため、`compute()`再度 を呼び出すときに中断した場所から再開できます。
+ 停止した計算は、エンジンの再起動時に自動的に再開*されません*。を明示的に呼び出す必要があります`compute()`。
**レスポンス:** 状態を示すステータスオブジェクトを返します。現在の `"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`。
### 状態
スキーマ計算は次の状態を移動します。
+ `NotStarted` – スキーマはまだ計算されていません。 は空のスキーマ`pg_schema()`を返します。
+ `InProgress` – バックグラウンド計算が実行されています。 は部分的な結果 (最後の完全なスキーマと現在の計算からの検出の和) `pg_schema()`を返します。
+ `Completed` – 計算が正常に終了しました。完全なスキーマを使用できます。
+ `Stopped` – エンジンの再起動によって中断されたため、 `stop()`または を呼び出して計算が停止されました。部分的な結果を使用できます。進行状況が保存されるため、 を呼び出すと計算は中断した場所から再開できます`compute()`。
+ `Failed` – 計算でエラーが発生しました。最後に正常に計算されたスキーマ (存在する場合) は引き続き使用できます。
### 永続化と再起動の動作
計算されたスキーマは保持され、エンジンの再起動後も存続します。再起動動作は、再起動時の状態によって異なります。
+ `InProgress` – 計算中にエンジンが再起動すると、計算は に移行します`Stopped`。`compute()` を呼び出して、中断した場所から再開します。進行状況は保持され、計算は最後のチェックポイントから続行されます。
+ `Stopped` – 計算は自動的に再開*されません*。中断した場所から続行する`compute()`には、 を呼び出す必要があります。
+ `Completed` – スキーマがロードされ、すぐに使用できます。
### 部分的な結果
計算の進行中、 は部分的な結果`pg_schema()`を返します。これには、現在の計算でこれまでに検出されたラベル、プロパティ、トリプルとマージされた、以前に完了したスキーマが含まれます。つまり、有用なスキーマ情報を取得する前に、完全な計算が完了するまで待つ必要はありません。
### リードレプリカ
リードレプリカインスタンスは、 を使用してスキーマを読み取ることができます`CALL neptune.graph.pg_schema()`。Neptune は、ライターインスタンスからスキーマをレプリケートし、ライターでスキーマ要素が検出されるとすぐにレプリカで使用できるようにします。
リードレプリカは `compute()`または を実行できません`stop()`。これらの呼び出しはエラーを返します。
+ `compute()` – `"Schema cannot be computed on read replica"`
+ `stop()` – `"Schema compute cannot be stopped on read replica"`
## ベストプラクティス
+ **ミューテーション後の再計算** – データが変更されてもスキーマは自動的に更新されません。一括ロードまたは重要なデータミューテーション後にスキーマを再計算します。`lastComputedTimestamp` フィールドを使用して、グラフの最近の変更と比較してスキーマが古くなっているかどうかを判断します。
+ **同時実行** – デフォルトの同時実行値 (0) は、インスタンスハードウェアに自動的に適応します。ほとんどのワークロードでは、これが推奨設定です。バックグラウンド計算がクエリワークロードに影響する場合は、リソース使用量を減らすために低い値 (1 や 2 など) を指定します。
+ **停止と再開** – バックグラウンド計算がクエリワークロードに影響する場合は、 で停止`stop()`し、トラフィックが少ない期間に後で`compute()`再度 を呼び出して再開します。計算は中断した場所から続行されます。
+ **正常に再起動する –** スキーマ計算の進行中にエンジンが再起動すると、計算は に移行します`Stopped`。を呼び出し`compute()`て、中断した場所から再開します。進行状況は保持されます。
+ **大規模なデータベース** – 大規模なストレージボリューム (複数 TB) を持つデータベースの場合、完全なスキーマ計算には時間がかかる場合があります。コンピューティングを開始し、10～20% の進行状況まで実行してから停止できます。このウィンドウ中に収集された部分的な結果は、多くのラベル、プロパティ、トリプルが既に検出された有用なスキーマサンプルを提供します。計算の進行中または停止後に、 で部分スキーマ`pg_schema()`を読み取ります。ワークロードで許可されている場合は、後で再開します。
## 制限事項
+ **削除には再計算が必要** – 削除されたラベル、プロパティ、トリプルは、次の完全な再計算後にのみスキーマから削除されます。それまでは、削除された要素がスキーマ結果に表示されることがあります。
+ **OpenCypher のみ** – この手順は openCypher クエリエンドポイントを介してのみ呼び出すことができます。
+ **一括ロード中に計算できない** – Neptune は、一括ロードオペレーションがアクティブな間、スキーマ計算を拒否します。一括ロードの完了後にコンピューティングをトリガーします。
## サンプル出力
次の例は、エアルートデータセットのスキーマ出力を示しています。
```
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"]
}
}
}
}
}]
}
```