Schéma du graphe de propriétés

Le neptune.graph.pg_schema() Cette 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 d'arêtes).

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 la base de données Neptune, vous déclenchez explicitement un calcul de schéma asynchrone en appelant neptune.graph.pg_schema.compute(), qui revient immédiatement. Le calcul s'exécute en arrière-plan pendant que vous interrogez pour terminer le sondage à l'aide de neptune.graph.pg_schema(). 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

Le API de résumé des graphiques 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, un Person se connecte à Company via un worksAt bord. 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 :

Le compute() et stop() les opérations 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 uniquement 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 s'exécuter compute() ou stop().

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 l'état : "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 : String, Int, 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 age comme Int et d'autres comme String), 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 indiquant l'état : "InProgress" avec le concurrency et progressPercentage champs.

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 courant progressPercentage.

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

Vous pouvez utiliser YIELD pour extraire les champs du 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. Le 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. Quand tu appelles neptune.graph.pg_schema.compute(), il revient immédiatement avec le statut actuel. Le calcul s'exécute en arrière-plan. Vous effectuez un sondage pour connaître les progrès et les résultats en appelant neptune.graph.pg_schema(), qui renvoie l'état actuel et progressPercentage.

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

Pendant qu'un calcul est en cours, pg_schema() renvoie des résultats partiels. Ceux-ci incluent 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 de réplication en lecture peuvent lire le schéma à l'aide de CALL 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 s'exécuter compute() ou stop(). 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"]
            }
          }
        }
      }
    }]
}