속성 그래프 스키마

이 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는 레이블 트리플 또는 속성 데이터 유형을 제공하지 않습니다. 속성 그래프 스키마 프로시저는이 간격을 채웁니다. 레이블 트리플은 그래프에 특정 관계 패턴을 표시합니다. 예를 들어는 worksAt 엣지를 Company 통해에 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

파라미터:

동작:

응답: concurrency 및 progressPercentage 필드와 "InProgress" 함께 상태를 표시하는 상태 객체를 반환합니다.

스키마 계산 중지

실행 중인 백그라운드 계산을 중지합니다.

구문:

필요한 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.

상태

스키마 계산은 다음 상태를 거칩니다.

지속성 및 재시작 동작

계산된 스키마는 지속되고 엔진 재시작 후에도 유지됩니다. 재시작 동작은 재시작 시점의 상태에 따라 달라집니다.

부분 결과

계산이 진행되는 동안는 부분 결과를 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"]
            }
          }
        }
      }
    }]
}