Verwalten von Statistiken, die die Neptune-DFE-Engine verwenden soll

Anmerkung

Die Unterstützung von openCypher ist von der DFE-Abfrage-Engine in Neptune abhängig.

Die DFE-Engine war zunächst im Labor-Modus in der Neptune-Engine-Version 1.0.3.0 verfügbar. Ab der Neptune-Engine-Version 1.0.5.0 ist sie standardmäßig aktiviert, jedoch nur für die Verwendung mit Abfragehinweisen und zur Unterstützung von openCypher.

Ab der Neptune-Engine-Version 1.1.1.0 ist die DFE-Engine nicht mehr im Labor-Modus und wird jetzt über den Instance-Parameter neptune_dfe_query_engine in der DB-Parametergruppe einer Instance gesteuert.

Die DFE-Engine verwendet Informationen zu den Daten in Ihrem Neptune-Diagramm, um bei der Planung der Abfrageausführung effektive Kompromisse einzugehen. Bei diesen Informationen handelt es sich um Statistiken, die sogenannte Merkmalssätze und Prädikatstatistiken umfassen, die als Anleitung für die Abfrageplanung dienen können.

Ab Engine-Version 1.2.1.0 können Sie mithilfe der GetGraphSummaryAPI oder des Endpunkts zusammenfassende Informationen zu Ihrem Diagramm aus diesen Statistiken abrufen. summary

Diese DFE-Statistiken werden derzeit neu generiert, wenn entweder mehr als 10 % der Daten in Ihrem Diagramm geändert wurden oder wenn die neuesten Statistiken älter als 10 Tage sind. Diese Auslöser können sich in der Zukunft jedoch ändern.

Anmerkung

Die Statistikgenerierung ist für T3- und T4g-Instances deaktiviert, da sie die Arbeitsspeicherkapazität dieser Instance-Typen überschreiten kann.

Sie können die Generierung von DFE-Statistiken über einen der folgenden Endpunkte verwalten:

• https://your-neptune-host:port/rdf/statistics     (für SPARQL).

• https://your-neptune-host:port/propertygraph/statistics    (für Gremlin und openCypher) und die alternative Version: https://your-neptune-host:port/pg/statistics.

Anmerkung

Ab Engine-Version 1.1.1.0 wird der Gremlin-Statistik-Endpunkt (https://your-neptune-host:port/gremlin/statistics) zugunsten des propertygraph- oder pg-Endpunkts außer Betrieb genommen. Aus Gründen der Abwärtskompatibilität wird er weiter unterstützt, wird jedoch in zukünftigen Versionen möglicherweise entfernt.

Ab Engine-Version 1.2.1.0 wird der SPARQL-Statistik-Endpunkt (https://your-neptune-host:port/sparql/statistics) zugunsten des rdf-Endpunkts außer Betrieb genommen. Aus Gründen der Abwärtskompatibilität wird er weiter unterstützt, wird jedoch in zukünftigen Versionen möglicherweise entfernt.

In den folgenden Beispielen steht $STATISTICS_ENDPOINT für beliebige dieser Endpunkt-URLs.

Anmerkung

Wenn sich ein DFE-Statistikendpunkt auf einer Reader-Instance befindet, kann er nur Statusanfragen verarbeiten. Andere Anfragen schlagen mit einer ReadOnlyViolationException fehl.

Größenbeschränkungen für die DFE-Statistikgenerierung

Derzeit wird die Generierung von DFE-Statistiken angehalten, wenn eine der folgenden Größenbeschränkungen erreicht wird:

• Die Anzahl der generierten Merkmalsätze darf 50 000 nicht überschreiten.

• Die Anzahl der generierten Prädikatstatistiken darf eine Million nicht überschreiten.

Diese Grenzwerte unterliegen Änderungen.

Aktueller Status der DFE-Statistiken

Sie können den aktuellen Status der DFE-Statistiken mithilfe der folgenden curl-Anforderung überprüfen:

curl -G "$STATISTICS_ENDPOINT"

Die Antwort auf eine Statusanforderung enthält die folgenden Felder:

• status  –   HTTP-Rückgabecode der Anforderung. Wenn die Anforderung erfolgreich ist, lautet der Code 200. Eine Liste mit häufigen Fehlern finden Sie unter Häufige Fehler.

• payload:

  • autoCompute  –   (Boolean) Gibt an, ob die automatische Generierung von Statistiken aktiviert ist oder nicht.

  • active  –   (Boolean) Gibt an, ob die automatische Generierung von DFE-Statistiken aktiviert ist oder nicht.

  • statisticsId   –   Meldet die ID der aktuellen Statistikgenerierungsausführung. Der Wert -1 gibt an, dass keine Statistiken generiert wurden.

  • date  –   Die UTC-Zeit, zu der die DFE-Statistiken zuletzt generiert wurden (im Format ISO 8601).

    Anmerkung

    Vor Engine-Version 1.2.1.0 wurde dies mit Minutengenauigkeit dargestellt. Ab Engine-Version 1.2.1.0 wird dies mit Millisekundengenauigkeit dargestellt (zum Beispiel 2023-01-24T00:47:43.319Z).

  • note  –   Ein Hinweis zu Problemen in dem Fall, dass Statistiken ungültig sind.

  • signatureInfo  –   Enthält Informationen zu den in der Statistik generierten Merkmalsätzen (vor Engine-Version 1.2.1.0 hatte dieses Feld den Namen summary). Dies ist im Allgemeinen nicht direkt umsetzbar:

    • signatureCount  –   Gesamtzahl der Signaturen für alle Merkmalsätze.

    • instanceCount  –   Gesamtzahl der Merkmalsatz-Instances.

    • predicateCount  –   Gesamtzahl der eindeutigen Prädikate.

Die Antwort auf eine Statusanforderung, wenn keine Statistiken generiert wurden, sieht wie folgt aus:

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

Wenn DFE-Statistiken verfügbar sind, sieht die Antwort wie folgt aus:

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

Wenn die Generierung von DFE-Statistiken fehlgeschlagen ist, weil beispielsweise die Größenbeschränkung für Statistiken überschritten wurde, sieht die Antwort wie folgt aus:

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

Deaktivieren der automatischen Generierung von DFE-Statistiken

Standardmäßig ist die automatische Generierung von DFE-Statistiken aktiviert, wenn Sie DFE aktivieren.

Sie können die automatische Generierung wie folgt deaktivieren:

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

Wenn die Anforderung erfolgreich ist, lautet der HTTP-Antwortcode 200 und die Antwort ist:

{
  "status" : "200 OK"
}

Sie können überprüfen, ob die automatische Generierung deaktiviert ist, indem Sie eine Statusanforderung ausgeben und überprüfen, ob das Feld autoCompute in der Antwort auf false festgelegt ist.

Durch das Deaktivieren der automatischen Generierung von Statistiken wird eine laufende Statistikberechnung nicht beendet.

Wenn Sie eine Anforderung zur Deaktivierung der automatischen Generierung an eine Reader-Instance Ihres DB-Clusters statt an die Writer-Instance senden, schlägt die Anforderung mit dem HTTP-Rückgabecode 400 und einer Ausgabe wie der folgenden fehl:

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

Eine Liste mit weiteren häufigen Fehlern finden Sie unter Häufige Fehler.

Erneutes Aktivieren der automatischen Generierung von DFE-Statistiken

Standardmäßig ist die automatische Generierung von DFE-Statistiken bereits aktiviert, wenn Sie DFE aktivieren. Wenn Sie die automatische Generierung deaktivieren, können Sie diese später wie folgt erneut aktivieren:

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

Wenn die Anforderung erfolgreich ist, lautet der HTTP-Antwortcode 200 und die Antwort ist:

{
  "status" : "200 OK"
}

Sie können überprüfen, ob die automatische Generierung aktiviert ist, indem Sie eine Statusanforderung ausgeben und prüfen, ob das Feld autoCompute in der Antwort auf true festgelegt ist.

Manuelles Auslösen der Generierung von DFE-Statistiken

Sie können die Generierung von DFE-Statistiken wie folgt manuell starten:

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

Wenn die Anforderung erfolgreich ist, sieht die Ausgabe wie folgt aus und der HTTP-Rückgabecode ist 200:

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

Die statisticsId in der Ausgabe ist die ID der Statistikgenerierung, die zurzeit ausgeführt wird. Wenn zum Zeitpunkt der Anforderung bereits eine Ausführung bearbeitet wird, gibt die Anforderung die ID dieser Ausführung zurück, statt eine neue zu initiieren. Sie können jeweils nur eine Statistikgenerierung gleichzeitig ausführen.

Wenn während der Generierung der DFE-Statistiken ein Failover auftritt, nimmt der neue Writer-Knoten den zuletzt verarbeiteten Prüfpunkt auf und setzt die Statistikausführung ab dort fort.

Verwendung der StatsNumStatementsScanned CloudWatch Metrik zur Überwachung der Statistikberechnung

Die StatsNumStatementsScanned CloudWatch Metrik gibt die Gesamtzahl der Anweisungen zurück, die seit dem Start des Servers für statistische Berechnungen gescannt wurden. Sie wird bei jedem Slice der Statistikberechnung aktualisiert.

Bei jeder Auslösung einer Statistikberechnung nimmt diese Zahl zu. Wenn keine Berechnung stattfindet, bleibt sie konstant. Wenn Sie ein Diagramm mit StatsNumStatementsScanned-Werten über die Zeit betrachten, erhalten Sie daher ein ziemlich klares Bild davon, wann und wie schnell Statistikberechnungen ausgeführt wurden:

Während der Berechnung zeigt Ihnen die Steigung im Diagramm, wie schnell diese ausgeführt wird. (Je steiler die Steigung, desto schneller werden Statistiken berechnet.)

Wenn das Diagramm einfach eine flache Linie bei 0 ist, wurde das Statistik-Feature aktiviert, es wurden jedoch keine Statistiken berechnet. Wenn das Statistik-Feature deaktiviert wurde oder wenn Sie eine Engine-Version verwenden, die keine Statistikberechnung unterstützt, ist StatsNumStatementsScanned nicht vorhanden.

Wie bereits erwähnt, können Sie die Statistikberechnung über die Statistik-API deaktivieren. Wenn Sie diese jedoch deaktiviert lassen, sind Statistiken möglicherweise nicht aktuell, was zu einer mangelhaften Abfrageplangenerierung für die DFE-Engine führen kann.

Informationen Überwachung von Neptune mit Amazon CloudWatch zur Verwendung finden Sie unter CloudWatch.

Verwenden der AWS Identity and Access Management (IAM-) Authentifizierung mit DFE-Statistikendpunkten

Sie können mit einer IAM-Authentifizierung sicher auf DFE-Statistikendpunkte zugreifen, indem Sie awscurl oder ein anderes Tool verwenden, das mit HTTPS und IAM funktioniert. Weitere Informationen dazu, wie Sie korrekte Anmeldeinformationen einrichten, finden Sie unter Verwenden von awscurl mit temporären Anmeldeinformationen für sichere Verbindungen zu DB-Clustern mit aktivierter IAM-Authentifizierung. Anschließend können Sie eine Statusanforderung wie folgt senden:

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

Alternativ können Sie beispielsweise eine JSON-Datei mit dem Namen request.json erstellen, die Folgendes enthält:

{ "mode" : "refresh" }

Sie können die Generierung von DFE-Statistiken dann wie folgt manuell initiieren:

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

Löschen von DFE-Statistiken

Sie können alle Statistiken in der Datenbank löschen, indem Sie eine HTTP-DELETE-Anforderung an den Statistikendpunkt senden:

curl -X "DELETE" "$STATISTICS_ENDPOINT"

Gültige HTTP-Rückgabecodes sind:

• 200   –   Die Statistiken wurden erfolgreich gelöscht.

  In diesem Fall würde eine typische Antwort wie folgt aussehen:

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

• 204   –   Es gab keine Statistiken, die gelöscht werden konnten.

  In diesem Fall ist die Antwort leer (keine Antwort).

Wenn Sie eine Löschanforderung an einen Statistikendpunkt auf einem Reader-Knoten senden, wird eine ReadOnlyViolationException ausgelöst.

Häufige Fehlercodes für DFE-Statistikanforderungen

Im Folgenden finden Sie eine Liste häufiger Fehler, die auftreten können, wenn Sie eine Anforderung an einen Statistikendpunkt senden:

• AccessDeniedException   –   Rückgabecode: 400. Meldung: Missing Authentication Token.

• BadRequestException (für Gremlin und openCypher)   –   Rückgabecode: 400. Meldung: Bad route: /pg/statistics.

• BadRequestException (für RDF-Daten)   –   Rückgabecode: 400. Meldung: Bad route: /rdf/statistics.

• InvalidParameterException   –   Rückgabecode: 400. Meldung: Statistics command parameter 'mode' has unsupported value 'the invalid value'.

• MissingParameterException   –   Rückgabecode: 400. Meldung: Content-type header not specified..

• ReadOnlyViolationException   –   Rückgabecode: 400. Meldung: Writes are not permitted on a read replica instance.

Wenn Sie beispielsweise eine Anforderung senden, wenn DFE und Statistiken nicht aktiviert sind, erhalten Sie eine Antwort wie die folgende:

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