Gestion des statistiques à utiliser par le DFE Neptune

Note

La prise en charge d'openCypher dépend du moteur de requête DFE de Neptune.

Le moteur DFE a d'abord été disponible en mode laboratoire dans la version 1.0.3.0 du moteur Neptune. À partir de la version 1.0.5.0 du moteur Neptune, il a été activé par défaut, mais uniquement pour une utilisation avec les indicateurs de requête et pour la prise en charge d'openCypher.

Depuis la version 1.1.1.0 du moteur Neptune, le moteur DFE n'est plus en mode laboratoire et est désormais contrôlé à l'aide du paramètre d'instance neptune_dfe_query_engine dans le groupe de paramètres de base de données d'une instance.

Le moteur DFE utilise les informations relatives aux données d'un graphe Neptune pour effectuer des compromis efficaces lors de la planification de l'exécution des requêtes. Ces informations prennent la forme de statistiques qui incluent ce que l'on appelle des ensembles de caractéristiques et des statistiques de prédicats qui contribuent à guider la planification des requêtes.

À partir de la version 1.2.1.0 du moteur, vous pouvez récupérer des informations récapitulatives sur votre graphique à partir de ces statistiques à l'aide de l'GetGraphSummaryAPI ou du summary point de terminaison.

Ces statistiques DFE sont générées chaque fois que plus de 10 % des données de votre graphe ont changé ou lorsque les dernières statistiques datent de plus de 10 jours. Cependant, ces déclencheurs pourraient changer à l'avenir.

Note

La génération de statistiques est désactivée sur les instances T3 et T4g, car elle peut dépasser la capacité de mémoire de ces types d'instances.

Vous pouvez gérer la génération de statistiques DFE via l'un des points de terminaison suivants :

• https://your-neptune-host:port/rdf/statistics (pour SPARQL).

• https://your-neptune-host:port/propertygraph/statistics (pour Gremlin et openCypher) et sa version alternative : https://your-neptune-host:port/pg/statistics.

Note

Depuis la version 1.1.1.0 du moteur, le point de terminaison de statistiques Gremlin (https://your-neptune-host:port/gremlin/statistics) est obsolète et a été remplacé par le point de terminaison propertygraph ou pg. Il reste pris en charge pour des raisons de rétrocompatibilité, mais il pourrait être supprimé dans les futures versions.

Depuis la version 1.2.1.0 du moteur, le point de terminaison de statistiques SPARQL (https://your-neptune-host:port/sparql/statistics) est obsolète et a été remplacé par le point de terminaison rdf. Il reste pris en charge pour des raisons de rétrocompatibilité, mais il pourrait être supprimé dans les futures versions.

Dans les exemples ci-dessous, $STATISTICS_ENDPOINT représente l'une de ces URL de point de terminaison.

Note

Si un point de terminaison de statistiques DFE se trouve sur une instance de lecteur, les seules demandes qu'il peut traiter sont les demandes de statut. Les autres demandes échoueront avec une exception ReadOnlyViolationException.

Limites de taille pour la génération des statistiques DFE

Actuellement, la génération des statistiques DFE s'arrête si l'une des limites de taille suivantes est atteinte :

• Le nombre d'ensembles de caractéristiques générés ne doit pas dépasser 50 000.

• Le nombre de statistiques de prédicat générées ne doit pas dépasser un million.

Ces limites sont susceptibles de changer.

Statut actuel des statistiques du DFE

Vous pouvez vérifier le statut actuel des statistiques DFE à l'aide de la demande curl suivante :

curl -G "$STATISTICS_ENDPOINT"

La réponse à une demande de statut comporte les champs suivants :

• status : code de retour HTTP de la demande. Si la demande aboutit, le code est 200. Pour obtenir une liste des erreurs courantes, consultez Erreurs courantes.

• payload:

  • autoCompute : (valeur booléenne) indique si la génération automatique des statistiques est activée ou non.

  • active : (valeur booléenne) indique si la génération des statistiques est activée.

  • statisticsId  : indique l'ID de la génération de statistiques en cours d'exécution. La valeur -1 indique qu'aucune statistique n'a été générée.

  • date : heure UTC à laquelle les dernières statistiques DFE ont été générées, au format ISO 8601.

    Note

    Avant la version 1.2.1.0 du moteur, elle était représentée avec une précision à la minute, mais depuis la version 1.2.1.0 du moteur, elle est représentée avec une précision à la milliseconde (par exemple, 2023-01-24T00:47:43.319Z).

  • note : remarque concernant les problèmes liés à la non-validité des statistiques.

  • signatureInfo : contient des informations sur les ensembles de caractéristiques générés dans les statistiques (avant la version 1.2.1.0 du moteur, ce champ était nommé summary). Elles ne sont généralement pas directement exploitables :

    • signatureCount : nombre total de signatures pour tous les ensembles de caractéristiques.

    • instanceCount : nombre total d'instances d'ensembles de caractéristiques.

    • predicateCount : nombre total de prédicats uniques.

La réponse à une demande de statut quand aucune statistique n'a été générée ressemble à ceci :

{
  "status" : "200 OK",
  "payload" : {
    "autoCompute" : true,
    "active" : false,
    "statisticsId" : -1
   }
}

Si des statistiques DFE sont disponibles, la réponse ressemble à ceci :

{
  "status" : "200 OK",
  "payload" : {
    "autoCompute" : true,
    "active" : true,
    "statisticsId" : 1588893232718,
    "date" : "2020-05-07T23:13Z",
    "summary" : {
      "signatureCount" : 5,
      "instanceCount" : 1000,
      "predicateCount" : 20
    }
  }
}

Si la génération des statistiques DFE a échoué, par exemple parce qu'elle a dépassé la limite de taille des statistiques, la réponse ressemble à ceci :

{
  "status" : "200 OK",
  "payload" : {
    "autoCompute" : true,
    "active" : false,
    "statisticsId" : 1588713528304,
    "date" : "2020-05-05T21:18Z",
    "note" : "Limit reached: Statistics are not available"
  }
}

Désactivation de la génération automatique des statistiques DFE

Par défaut, la génération automatique des statistiques DFE est activée lorsque vous activez le DFE.

Vous pouvez désactiver la génération automatique comme suit :

curl -X POST "$STATISTICS_ENDPOINT" -d '{ "mode" : "disableAutoCompute" }'

Si la demande aboutit, voice ce à quoi correspondent le code de réponse HTTP 200 et la réponse :

{
  "status" : "200 OK"
}

Pour confirmer que la génération automatique est désactivée, émettez une demande de statut et vérifiez que le champ autoCompute de la réponse est défini sur false.

La désactivation de la génération automatique des statistiques ne met pas fin à un calcul de statistiques en cours.

Si vous demandez de désactiver la génération automatique vers une instance de lecteur plutôt que vers l'instance d'enregistreur de votre cluster de bases de données, la demande échoue avec le code de retour HTTP 400 et génère la sortie suivante :

{
  "detailedMessage" : "Writes are not permitted on a read replica instance",
  "code" : "ReadOnlyViolationException",
  "requestId":"8eb8d3e5-0996-4a1b-616a-74e0ec32d5f7"
}

Pour obtenir une liste des autres erreurs courantes, consultez Erreurs courantes.

Réactivation de la génération automatique des statistiques DFE

Par défaut, la génération automatique des statistiques DFE est déjà activée lorsque vous activez le DFE. Si vous désactivez la génération automatique, vous pouvez la réactiver ultérieurement comme suit :

curl -X POST "$STATISTICS_ENDPOINT" -d '{ "mode" : "enableAutoCompute" }'

Si la demande aboutit, voice ce à quoi correspondent le code de réponse HTTP 200 et la réponse :

{
  "status" : "200 OK"
}

Pour confirmer que la génération automatique est activée, émettez une demande de statut et vérifiez que le champ autoCompute de la réponse est défini sur true.

Déclenchement manuel de la génération de statistiques DFE

Vous pouvez lancer la génération de statistiques DFE manuellement comme suit :

curl -X POST "$STATISTICS_ENDPOINT" -d '{ "mode" : "refresh" }'

Si la requête aboutit, le résultat est le suivant, avec le code de retour HTTP 200 :

{
  "status" : "200 OK",
  "payload" : {
    "statisticsId" : 1588893232718
  }
}

Le statisticsId dans la sortie contient l'ID de l'exécution de la génération de statistiques en cours. Si une exécution était déjà en cours au moment de la demande, cette demande renvoie l'ID de cette exécution plutôt que d'en lancer une nouvelle. Une seule génération de statistiques peut avoir lieu à la fois.

En cas de basculement lors de la génération des statistiques DFE, le nouveau nœud d'enregistreur relève le dernier point de contrôle traité et reprend l'exécution des statistiques à partir de là.

Utilisation de la StatsNumStatementsScanned CloudWatch métrique pour surveiller le calcul des statistiques

La StatsNumStatementsScanned CloudWatch métrique renvoie le nombre total d'instructions analysées pour le calcul des statistiques depuis le démarrage du serveur. Elle est mise à jour à chaque tranche de calcul des statistiques.

Chaque fois que le calcul des statistiques est déclenché, ce nombre augmente. Quand aucun calcul n'est effectué, il reste constant. L'examen d'un diagramme de valeurs StatsNumStatementsScanned au fil du temps donne donc une idée assez claire de la date et de la rapidité du calcul des statistiques :

Lorsque le calcul est en cours, la pente du graphe indique la vitesse (plus la pente est raide, plus les statistiques sont calculées rapidement).

Si le graphe est simplement une ligne plate à 0, la fonctionnalité de statistiques a été activée, mais aucune statistique n'a été calculée. Si la fonctionnalité de statistiques a été désactivée ou si vous utilisez une version du moteur qui ne prend pas en charge le calcul des statistiques, StatsNumStatementsScanned n'existe pas.

Comme indiqué précédemment, vous pouvez désactiver le calcul des statistiques à l'aide de l'API de statistiques. Toutefois, la désactivation de cette fonctionnalité peut empêcher la mise à jour des statistiques, ce qui peut entraîner une génération inappropriée du plan de requête pour le moteur DFE.

Surveillance de Neptune à l'aide d'Amazon CloudWatchReportez-vous à la section pour plus d'informations sur son utilisation CloudWatch.

Utilisation de l'authentification AWS Identity and Access Management (IAM) avec les points de terminaison de statistiques DFE

Vous pouvez accéder aux points de terminaison de statistiques DFE en toute sécurité grâce à l'authentification IAM à l'aide d'awscurl ou de tout autre outil compatible avec HTTPS et IAM. Consultez Utilisation d'informations d'identification temporaires awscurl pour se connecter en toute sécurité à un cluster de bases de données avec l'authentification IAM activée pour découvrir comment configurer les informations d'identification appropriées. Une fois que y avez accès, vous pouvez effectuer une demande de statut comme celle-ci :

awscurl "$STATISTICS_ENDPOINT" \
    --region (your region) \
    --service neptune-db

Ou vous pouvez, par exemple, créer un fichier JSON nommé request.json qui contient :

{ "mode" : "refresh" }

Vous pouvez ensuite lancer manuellement la génération de statistiques comme suit :

awscurl "$STATISTICS_ENDPOINT" \
    --region (your region) \
    --service neptune-db \
    -X POST -d @request.json

Suppression des statistiques DFE

Vous pouvez supprimer toutes les statistiques de la base de données en envoyant une demande HTTP DELETE au point de terminaison de statistiques :

curl -X "DELETE" "$STATISTICS_ENDPOINT"

Voici les codes de retour HTTP valides :

• 200 : la suppression a été effectuée avec succès.

  Dans ce cas, une réponse typique ressemblerait à ce qui suit :

  {
    "status" : "200 OK",
    "payload" : {
        "active" : false,
        "statisticsId" : -1
    }
  }

• 204 : il n'y avait aucune statistique à supprimer.

  Dans ce cas, la réponse est vide (aucune réponse).

Si vous envoyez une demande de suppression à un point de terminaison de statistiques sur un nœud de lecteur, une exception ReadOnlyViolationException est renvoyée.

Codes d'erreur courants pour les demandes de statistiques DFE

Voici une liste des erreurs courantes qui peuvent survenir lorsque vous envoyez une demande à un point de terminaison de statistiques :

• AccessDeniedException – Code de retour : 400. Message : Missing Authentication Token.

• BadRequestException (pour Gremlin et openCypher) : code de retour : 400. Message : Bad route: /pg/statistics.

• BadRequestException (pour les données RDF) : code de retour : 400. Message : Bad route: /rdf/statistics.

• InvalidParameterException – Code de retour : 400. Message : Statistics command parameter 'mode' has unsupported value 'the invalid value'.

• MissingParameterException – Code de retour : 400. Message : Content-type header not specified..

• ReadOnlyViolationException – Code de retour : 400. Message : Writes are not permitted on a read replica instance.

Par exemple, si vous effectuez une demande alors que le DFE et les statistiques ne sont pas activés, vous obtiendrez une réponse comme celle-ci :

{
  "code" : "BadRequestException",
  "requestId" : "b2b8f8ee-18f1-e164-49ea-836381a3e174",
  "detailedMessage" : "Bad route: /sparql/statistics"
}