Schéma du graphe de propriétés

La neptune.graph.pg_schema() procédure fournit une vue d'ensemble complète de la structure de votre graphe de propriétés. Il renvoie toutes les étiquettes de nœuds, les étiquettes de bords, les propriétés avec leurs types de données et les triplets d'étiquettes ({~from, ~type, ~to}modèles qui décrivent comment les types de nœuds se connectent via les types de bords).

Cette procédure est actuellement disponible uniquement via le point de terminaison OpenCypher et découvre le schéma de toutes les données des graphes de propriétés.

Utilisez cette procédure pour des tâches telles que :

Comparaison avec Neptune Analytics

Dans Neptune Analytics, neptune.graph.pg_schema() est synchrone. Il calcule le schéma à chaque appel.

Dans Neptune Database, vous déclenchez explicitement un calcul de schéma asynchrone en appelantneptune.graph.pg_schema.compute(), qui renvoie immédiatement. Le calcul s'exécute en arrière-plan pendant que vous interrogez pour terminer le sondage à l'aide neptune.graph.pg_schema() de. Une fois calculé, Neptune conserve le schéma et le renvoie instantanément lors des lectures suivantes sans recalcul. Des résultats partiels sont également disponibles alors que le calcul est toujours en cours. Vous pouvez également arrêter un calcul en cours et le reprendre ultérieurement.

Comparaison avec l'API Graph Summary

L'API Graph Summary ne fournit pas de triplets d'étiquettes ni de types de données de propriété. La procédure de schéma du graphe de propriétés comble cette lacune. Les triplets d'étiquettes indiquent les modèles de relation spécifiques de votre graphique. Par exemple, a Person se connecte à a Company via une worksAt arête. Ces informations sont essentielles pour que les LLM puissent générer des requêtes sémantiquement correctes.

Conditions préalables

Version de moteur

La procédure de schéma du graphe de propriétés nécessite la version 1.4.8.0 ou ultérieure du moteur Neptune.

Autorisations IAM

Les actions IAM suivantes sont requises pour chaque opération de schéma :

Les stop() opérations compute() et nécessitent des autorisations d'écriture car elles modifient l'état interne utilisé pour mettre en cache et conserver le schéma.

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

Pour accorder un accès en lecture seule au schéma (sans possibilité de déclencher le calcul), utilisez only. neptune-db:ReadDataViaQuery

Instances pour les rédacteurs et les lecteurs

Vous ne pouvez déclencher le calcul du schéma que sur l'instance d'écriture. Les instances de réplication en lecture peuvent lire le schéma (qui est répliqué depuis l'enregistreur) mais ne peuvent pas exécuter compute() oustop().

Référence des API

Lire le schéma

Récupère le schéma actuel et l'état du calcul.

Syntaxe :

Comportement : renvoie immédiatement le schéma et l'état actuels. Toujours non bloquant. Si aucun schéma n'a été calculé, renvoie state : "NotStarted" avec des champs de schéma vides. Si un calcul est en cours, renvoie des résultats partiels avec l'état :"InProgress".

Format de réponse :

La réponse contient un objet de schéma avec les champs suivants :

Objet d'état :

Objet du schéma :

Types de données pris en charge : StringInt,Long,Double,Bool, Date

Si une propriété possède plusieurs types de données sur différents nœuds (par exemple, certains nœuds stockent en age tant que Int et d'autres en tant queString), tous les types observés sont répertoriés dans le datatypes tableau.

Schéma de calcul

Déclenche un calcul de schéma en arrière-plan.

Syntaxe :

Actions IAM requises : neptune-db:ReadDataViaQuery et neptune-db:WriteDataViaQuery

Paramètres :

Comportement :

Réponse : Renvoie l'objet d'état affichant l'état : "InProgress" avec les progressPercentage champs concurrency et.

Arrêter le calcul du schéma

Arrête un calcul en arrière-plan en cours d'exécution.

Syntaxe :

Actions IAM requises : neptune-db:ReadDataViaQuery et neptune-db:WriteDataViaQuery

Comportement :

Réponse : Renvoie l'objet d'état indiquant l'état : "Stopped" avec le courantprogressPercentage.

Utilisation de YIELD avec les résultats du schéma

Vous pouvez les utiliser YIELD pour extraire des champs de schéma et les combiner avec d'autres requêtes. L'exemple suivant récupère toutes les étiquettes de nœuds et compte le nombre de nœuds pour chaque étiquette. La collSort() fonction trie la liste par ordre alphabétique :

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

Exemple de sortie :

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

Cycle de vie du calcul des schémas

Fonctionnement asynchrone

Le calcul du schéma est une opération asynchrone. Lorsque vous appelezneptune.graph.pg_schema.compute(), il revient immédiatement avec l'état actuel. Le calcul s'exécute en arrière-plan. Vous effectuez un sondage pour connaître la progression et l'achèvement en appelantneptune.graph.pg_schema(), ce qui renvoie l'état actuel etprogressPercentage.

States

Le calcul du schéma passe par les états suivants :

Comportement de persistance et de redémarrage

Le schéma calculé est conservé et survit aux redémarrages du moteur. Le comportement de redémarrage dépend de l'état au moment du redémarrage :

Résultats partiels

Lorsqu'un calcul est en cours, pg_schema() renvoie des résultats partiels. Il s'agit notamment de tout schéma précédemment terminé fusionné avec les étiquettes, les propriétés et les triplets découverts jusqu'à présent dans le calcul en cours. Cela signifie que vous n'avez pas à attendre la fin d'un calcul complet pour récupérer des informations de schéma utiles.

Réplicas en lecture

Les instances Read Replica peuvent lire le schéma à l'aide deCALL neptune.graph.pg_schema(). Neptune réplique le schéma à partir de l'instance d'écriture et le rend disponible sur les répliques presque immédiatement à mesure que des éléments de schéma sont découverts sur l'enregistreur.

Les répliques en lecture ne peuvent pas être exécutées compute() oustop(). Ces appels renvoient une erreur :

Bonnes pratiques

Limitations

Exemple de sortie.

L'exemple suivant montre la sortie du schéma pour le jeu de données sur les routes aériennes :

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