Gestione delle statistiche utilizzabili dal motore DFE Neptune

Nota

Il supporto per openCypher dipende dal motore di query DFE di Neptune.

Il motore DFE è stato disponibile per la prima volta in modalità di laboratorio nel rilascio 1.0.3.0 del motore Neptune e, a partire dal rilascio 1.0.5.0 del motore Neptune, è stato abilitato per impostazione predefinita, ma solo per l'uso con hint di query e per il supporto di openCypher.

A partire dal rilascio 1.1.1.0 del motore Neptune, il motore DFE non è più in modalità Lab e ora viene controllato con il parametro di istanza neptune_dfe_query_engine nel gruppo di parametri database di un'istanza.

Il motore DFE utilizza le informazioni sui dati del grafo Neptune per trovare compromessi efficaci al momento di pianificare l'esecuzione delle query. Queste informazioni assumono la forma di statistiche che includono i cosiddetti insiemi di caratteristiche, nonché statistiche sui predicati utili per la pianificazione delle query.

A partire dalla versione 1.2.1.0 del motore, è possibile recuperare informazioni di riepilogo sul grafico da queste statistiche utilizzando l'GetGraphSummaryAPI o l'endpoint. summary

Queste statistiche DFE vengono attualmente rigenerate ogni volta che viene modificato più del 10% dei dati nel grafo o quando le ultime statistiche risalgono a più di 10 giorni fa. Tuttavia, questi trigger potrebbero cambiare in futuro.

Nota

La generazione di statistiche è disabilitata nelle istanze T3 e T4g in quanto può superare la capacità di memoria di tali tipi di istanze.

È possibile gestire la generazione di statistiche DFE tramite uno dei seguenti endpoint:

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

• https://your-neptune-host:port/propertygraph/statistics    (per Gremlin e openCypher) e la relativa versione alternativa: https://your-neptune-host:port/pg/statistics.

Nota

A partire dal rilascio 1.1.1.0 del motore, l'endpoint delle statistiche Gremlin (https://your-neptune-host:port/gremlin/statistics) è stato deprecato a favore dell'endpoint propertygraph o pg. È ancora supportato per la compatibilità con le versioni precedenti, ma potrebbe essere rimosso nei rilasci futuri.

A partire dal rilascio 1.2.1.0 del motore, l'endpoint delle statistiche SPARQL (https://your-neptune-host:port/sparql/statistics) è stato deprecato a favore dell'endpoint rdf. È ancora supportato per la compatibilità con le versioni precedenti, ma potrebbe essere rimosso nei rilasci futuri.

Negli esempi seguenti, $STATISTICS_ENDPOINT indica uno qualsiasi di questi URL di endpoint.

Nota

Se un endpoint delle statistiche DFE si trova in un'istanza di lettura, le uniche richieste che può elaborare sono le richieste di stato. Le altre richieste avranno esito negativo con ReadOnlyViolationException.

Limiti di dimensione per la generazione di statistiche DFE

Attualmente, la generazione di statistiche DFE si interrompe se viene raggiunto uno dei seguenti limiti di dimensione:

• Il numero di set di caratteristiche generati non può superare 50.000.

• Il numero di statistiche sui predicati generate non può superare un milione.

Questi limiti possono cambiare.

Stato corrente delle statistiche DFE

È possibile controllare lo stato corrente delle statistiche DFE utilizzando la seguente richiesta curl:

curl -G "$STATISTICS_ENDPOINT"

La risposta a una richiesta di status include i seguenti campi:

• status: codice HTTP restituito della richiesta. Se la richiesta è riuscita, il codice è 200. Per visualizzare un elenco di errori comuni, consulta Errori comuni.

• payload:

  • autoCompute: (booleano) indica se la generazione automatica di statistiche è abilitata o meno.

  • active: (booleano) indica se la generazione di statistiche DFE è abilitata o meno.

  • statisticsId : riporta l'ID dell'esecuzione corrente della generazione delle statistiche. Il valore -1 indica che non sono state generate statistiche.

  • date: l'ora UTC in cui sono state generate le statistiche DFE più recentemente, nel formato ISO 8601.

    Nota

    Prima del rilascio 1.2.1.0 del motore, questo valore era rappresentato con precisione al minuto, ma dal rilascio 1.2.1.0 in poi, viene rappresentato con precisione al millisecondo (ad esempio, 2023-01-24T00:47:43.319Z).

  • note: una nota sui problemi nel caso in cui le statistiche non siano valide.

  • signatureInfo: contiene informazioni sui set di caratteristiche generati nelle statistiche (prima del rilascio 1.2.1.0 del motore, questo campo era denominato summary). In genere non sono direttamente utilizzabili:

    • signatureCount: numero totale di firme in tutti i set di caratteristiche.

    • instanceCount: numero totale di istanze di set di caratteristiche.

    • predicateCount: numero totale di predicati univoci.

La risposta a una richiesta di stato quando non sono state generate statistiche è simile alla seguente:

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

Se le statistiche DFE sono disponibili, la risposta è simile alla seguente:

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

Se la generazione delle statistiche DFE non è riuscita, ad esempio perché ha superato il limite di dimensione delle statistiche, la risposta è simile alla seguente:

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

Disabilitazione della generazione automatica di statistiche DFE

Per impostazione predefinita, la generazione automatica delle statistiche DFE viene abilitata quando si abilita DFE.

È possibile disabilitare la generazione automatica come segue:

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

Se la richiesta ha esito positivo, il codice di risposta HTTP è 200 e la risposta è:

{
  "status" : "200 OK"
}

È possibile verificare che la generazione automatica è disabilitata inviando una richiesta di stato e verificando che il campo autoCompute nella risposta sia impostato su false.

La disabilitazione della generazione automatica delle statistiche non interrompe il calcolo delle statistiche in corso.

Se si effettua una richiesta per disabilitare la generazione automatica in un'istanza di lettura anziché nell'istanza di scrittura del cluster database, la richiesta ha esito negativo con il codice HTTP restituito 400 e un output simile al seguente:

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

Per visualizzare un elenco di altri errori comuni, consulta Errori comuni.

Riabilitazione della generazione automatica di statistiche DFE

Per impostazione predefinita, la generazione automatica delle statistiche DFE è già abilitata quando si abilita DFE. Se si disabilita la generazione automatica, è possibile riabilitarla in un secondo momento come segue:

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

Se la richiesta ha esito positivo, il codice di risposta HTTP è 200 e la risposta è:

{
  "status" : "200 OK"
}

È possibile verificare che la generazione automatica è abilitata inviando una richiesta di stato e verificando che il campo autoCompute nella risposta sia impostato su true.

Attivazione manuale della generazione di statistiche DFE

È possibile avviare manualmente la generazione di statistiche DFE nel modo seguente:

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

Se la richiesta ha esito positivo, l'output è il seguente, con il codice HTTP restituito 200:

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

Il valore statisticsId nell'output è l'ID dell'esecuzione della generazione di statistiche attualmente in corso. Se un'esecuzione era già in corso al momento della richiesta, la richiesta restituisce l'ID di tale esecuzione anziché avviarne una nuova. È possibile eseguire una sola generazione di statistiche alla volta.

Se si verifica un failover durante la generazione delle statistiche DFE, il nuovo nodo di scrittura rileverà l'ultimo checkpoint elaborato e riprenderà l'esecuzione delle statistiche da lì.

Utilizzo della StatsNumStatementsScanned CloudWatch metrica per monitorare il calcolo delle statistiche

La StatsNumStatementsScanned CloudWatch metrica restituisce il numero totale di istruzioni analizzate per il calcolo delle statistiche dall'avvio del server. Viene aggiornata ad ogni sezione di calcolo delle statistiche.

Ogni volta che viene attivato il calcolo delle statistiche, questo numero aumenta e quando non viene eseguito alcun calcolo, rimane costante. L'esame di un grafico dei valori di StatsNumStatementsScanned nel tempo offre quindi un quadro abbastanza chiaro di quando è stato effettuato il calcolo delle statistiche e con quale velocità:

Durante il calcolo, la pendenza del grafico mostra la velocità (maggiore è la pendenza, più velocemente vengono calcolate le statistiche).

Se il grafico è semplicemente una linea piatta a 0, la funzionalità delle statistiche è stata abilitata, ma non è stata calcolata alcuna statistica. Se la funzionalità delle statistiche è stata disabilitata o se si utilizza una versione del motore che non supporta il calcolo delle statistiche, StatsNumStatementsScanned non esiste.

Come accennato in precedenza, è possibile disabilitare il calcolo delle statistiche utilizzando l'API delle statistiche, ma lasciarlo disabilitato può far sì che le statistiche non vengano aggiornate, il che a sua volta può comportare una generazione del piano di query inappropriata per il motore DFE.

Monitoraggio di Neptune tramite Amazon CloudWatchPer informazioni sull'uso CloudWatch, vedere.

Utilizzo dell'autenticazione AWS Identity and Access Management (IAM) con gli endpoint statistici DFE

È possibile accedere agli endpoint delle statistiche DFE in modo sicuro con l'autenticazione IAM utilizzando awscurl o qualsiasi altro strumento che funzioni con HTTPS e IAM. Per vedere come configurare le credenziali corrette, consulta Utilizzo di awscurl con credenziali temporanee per connettersi in modo sicuro a un cluster database con autenticazione IAM abilitata. Dopo aver eseguito questa operazione, è possibile effettuare una richiesta di stato come questa:

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

Oppure, ad esempio, è possibile creare un file JSON denominato request.json che contiene:

{ "mode" : "refresh" }

È quindi possibile avviare manualmente la generazione di statistiche nel modo seguente:

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

Eliminazione delle statistiche DFE

È possibile eliminare tutte le statistiche nel database effettuando una richiesta HTTP DELETE all'endpoint delle statistiche:

curl -X "DELETE" "$STATISTICS_ENDPOINT"

I codici HTTP restituiti validi sono:

• 200: l'eliminazione è riuscita.

  In questo caso, una risposta tipica è la seguente:

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

• 204: non c'erano statistiche da eliminare.

  In questo caso, la risposta è vuota (nessuna risposta).

Se si invia una richiesta di eliminazione a un endpoint di statistiche su un nodo di lettura, viene generata un'eccezione ReadOnlyViolationException.

Codici di errore comuni per la richiesta di statistiche DFE

Di seguito è riportato un elenco di errori comuni che possono verificarsi quando si effettua una richiesta a un endpoint di statistiche:

• AccessDeniedException: codice restituito: 400. Messaggio Missing Authentication Token.

• BadRequestException (per Gremlin e openCypher): codice restituito: 400. Messaggio Bad route: /pg/statistics.

• BadRequestException (per dati RDF): codice restituito: 400. Messaggio Bad route: /rdf/statistics.

• InvalidParameterException: codice restituito: 400. Messaggio Statistics command parameter 'mode' has unsupported value 'the invalid value'.

• MissingParameterException: codice restituito: 400. Messaggio Content-type header not specified..

• ReadOnlyViolationException: codice restituito: 400. Messaggio Writes are not permitted on a read replica instance.

Ad esempio, se si effettua una richiesta quando il motore DFE e le statistiche non sono abilitati, si otterrà una risposta simile alla seguente:

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