Property graph schema

The neptune.graph.pg_schema() procedure provides a comprehensive overview of your property graph structure. It returns all node labels, edge labels, properties with their data types, and label triples ({~from, ~type, ~to} patterns that describe how node types connect through edge types).

This procedure is currently available only through the openCypher endpoint and discovers the schema for all property graph data.

Use this procedure for tasks such as:

Comparison with Neptune Analytics

In Neptune Analytics, neptune.graph.pg_schema() is synchronous. It computes the schema on every call.

In Neptune Database, you explicitly trigger an asynchronous schema computation by calling neptune.graph.pg_schema.compute(), which returns immediately. The computation runs in the background while you poll for completion using neptune.graph.pg_schema(). Once computed, Neptune persists the schema and returns it instantly on subsequent reads without recomputation. Partial results are also available while the computation is still in progress. You can also stop a running computation and resume it later.

Comparison with the Graph Summary API

The Graph Summary API does not provide label triples or property data types. The property graph schema procedure fills this gap. Label triples show the specific relationship patterns in your graph. For example, a Person connects to a Company via a worksAt edge. This information is critical for LLMs to generate semantically correct queries.

Prerequisites

Engine version

The property graph schema procedure requires Neptune engine version 1.4.8.0 or later.

IAM permissions

The following IAM actions are required for each schema operation:

The compute() and stop() operations require write permissions because they modify internal state used to cache and persist the schema.

{
  "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/*"
  }]
}

To grant read-only access to the schema (without the ability to trigger computation), use only neptune-db:ReadDataViaQuery.

Writer and reader instances

You can trigger schema computation only on the writer instance. Read replica instances can read the schema (which is replicated from the writer) but cannot run compute() or stop().

API reference

Read schema

Retrieves the current schema and computation status.

Syntax:

Behavior: Returns immediately with the current schema and status. Always non-blocking. If no schema has been computed, returns state: "NotStarted" with empty schema fields. If a computation is in progress, returns partial results with state: "InProgress".

Response format:

The response contains a schema object with the following fields:

Status object:

Schema object:

Supported data types: String, Int, Long, Double, Bool, Date

If a property has multiple data types across different nodes (for example, some nodes store age as Int and others as String), all observed types are listed in the datatypes array.

Compute schema

Triggers a background schema computation.

Syntax:

IAM actions required: neptune-db:ReadDataViaQuery and neptune-db:WriteDataViaQuery

Parameters:

Behavior:

Response: Returns the status object showing state: "InProgress" with the concurrency and progressPercentage fields.

Stop schema computation

Stops a running background computation.

Syntax:

IAM actions required: neptune-db:ReadDataViaQuery and neptune-db:WriteDataViaQuery

Behavior:

Response: Returns the status object showing state: "Stopped" with the current progressPercentage.

Using YIELD with schema results

You can use YIELD to extract schema fields and combine them with other queries. The following example retrieves all node labels and counts the number of nodes for each label. The collSort() function sorts the list alphabetically:

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

Sample output:

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

Schema computation lifecycle

Asynchronous operation

Schema computation is an asynchronous operation. When you call neptune.graph.pg_schema.compute(), it returns immediately with the current status. The computation runs in the background. You poll for progress and completion by calling neptune.graph.pg_schema(), which returns the current state and progressPercentage.

States

The schema computation moves through the following states:

Persistence and restart behavior

The computed schema is persisted and survives engine restarts. The restart behavior depends on the state at the time of restart:

Partial results

While a computation is in progress, pg_schema() returns partial results. These include any previously completed schema merged with the labels, properties, and triples discovered so far in the current computation. This means you do not have to wait for a full computation to complete before retrieving useful schema information.

Read replicas

Read replica instances can read the schema using CALL neptune.graph.pg_schema(). Neptune replicates the schema from the writer instance and makes it available on replicas almost immediately as schema elements are discovered on the writer.

Read replicas cannot run compute() or stop(). These calls return an error:

Best practices

Limitations

Sample output

The following example shows the schema output for the air-routes dataset:

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"]
            }
          }
        }
      }
    }]
}