기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 속성 그래프 스키마
이 `neptune.graph.pg_schema()` 절차에서는 속성 그래프 구조에 대한 포괄적인 개요를 제공합니다. 모든 노드 레이블, 엣지 레이블, 데이터 유형이 있는 속성 및 레이블 트리플(`{~from, ~type, ~to}`노드 유형이 엣지 유형을 통해 연결되는 방식을 설명하는 패턴)을 반환합니다.
이 절차는 현재 openCypher 엔드포인트를 통해서만 사용할 수 있으며 모든 속성 그래프 데이터의 스키마를 검색합니다.
다음과 같은 작업에이 절차를 사용합니다.
+ **AI 및 LLM 쿼리 생성** - LLMs 자연어(Text-to-Cypher 생성하는 데 필요한 그래프 구조를 제공합니다. GraphRAG
+ **그래프 시각화 및 탐색 **- [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은 스키마를 유지하고 재계산 없이 후속 읽기에서 즉시 반환합니다. 계산이 진행 중인 동안 부분 결과도 사용할 수 있습니다. 실행 중인 계산을 중지하고 나중에 재개할 수도 있습니다.
## 그래프 요약 API와의 비교
[그래프 요약 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"`와 함께 상태를 반환합니다. 계산이 진행 중인 경우는 상태가 인 부분 결과를 반환합니다`"InProgress"`.
**응답 형식:**
응답에는 다음 필드가 있는 스키마 객체가 포함됩니다.
**상태 객체:**
+ `state` (문자열) - 현재 수명 주기 상태: `NotStarted`, `InProgress`, `Completed`, `Stopped`, `Failed`
+ `concurrency` (문자열) - 계산에 사용되는 스레드 수입니다. 0은 auto(하드웨어에 따라 결정됨)를 의미합니다. 범위: 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은 오류 메시지와 함께 요청을 거부합니다.
**응답:** `concurrency` 및 `progressPercentage` 필드와 `"InProgress"` 함께 상태를 표시하는 상태 객체를 반환합니다.
### 스키마 계산 중지
실행 중인 백그라운드 계산을 중지합니다.
**구문:**
------
#### [ 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은 대량 로드 작업이 활성화되어 있는 동안 스키마 계산을 거부합니다. 대량 로드가 완료된 후 컴퓨팅을 트리거합니다.
## 샘플 출력
다음 예제는 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"]
}
}
}
}
}]
}
```