Gerenciar estatísticas a serem utilizadas pelo DFE do Neptune

nota

O suporte ao openCypher depende do mecanismo de consulta DFE no Neptune.

O mecanismo DFE foi disponibilizado pela primeira vez no modo de laboratório na versão 1.0.3.0 do mecanismo do Neptune e, a partir da versão 1.0.5.0 do mecanismo do Neptune, ele se tornou habilitado por padrão, mas somente para uso com dicas de consulta e para suporte ao openCypher.

A partir da versão 1.1.1.0 do mecanismo do Neptune, o mecanismo DFE não está mais no modo de laboratório e agora é controlado usando o parâmetro de instância neptune_dfe_query_engine no grupo de parâmetros de banco de dados de uma instância.

O mecanismo DFE usa informações sobre os dados no grafo do Neptune para fazer compensações efetivas ao planejar a execução da consulta. Essas informações assumem a forma de estatísticas que incluem os chamados conjuntos de características e estatísticas de predicados que podem orientar o planejamento de consultas.

A partir da versão 1.2.1.0 do mecanismo, você pode recuperar informações resumidas sobre seu gráfico a partir dessas estatísticas usando a API GetGraphSummary ou o endpoint. summary

No momento, essas estatísticas do DFE são geradas novamente sempre que mais de 10% dos dados no grafo são alterados ou quando as estatísticas mais recentes têm mais de dez dias. No entanto, esses gatilhos podem mudar no futuro.

nota

A geração de estatísticas está desabilitada em instâncias T3 e T4g porque pode exceder a capacidade de memória desses tipos de instância.

É possível gerenciar a geração de estatísticas do DFE por meio de um dos seguintes endpoints:

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

• https://your-neptune-host:port/propertygraph/statistics (para Gremlin e openCypher) e sua versão alternativa: https://your-neptune-host:port/pg/statistics.

nota

A partir da versão 1.1.1.0 do mecanismo, o endpoint de estatísticas do Gremlin (https://your-neptune-host:port/gremlin/statistics) está sendo descontinuado em favor do endpoint propertygraph ou pg. Ele ainda é compatível com versões anteriores, mas pode ser removido em versões futuras.

A partir da versão 1.2.1.0 do mecanismo, o endpoint de estatísticas do SPARQL (https://your-neptune-host:port/sparql/statistics) está sendo descontinuado em favor do endpoint rdf. Ele ainda é compatível com versões anteriores, mas pode ser removido em versões futuras.

Nos exemplos abaixo, $STATISTICS_ENDPOINT significa qualquer um destes URLs de endpoint.

nota

Se um endpoint de estatísticas do DFE estiver em uma instância de leitor, as únicas solicitações que ele poderá processar serão solicitações de status. Outras solicitações falharão com uma ReadOnlyViolationException.

Limites de tamanho para geração de estatísticas do DFE

No momento, a geração de estatísticas do DFE será interrompida se um dos seguintes limites de tamanho for atingido:

• O número de conjuntos de características gerados não pode exceder cinquenta mil.

• O número de estatísticas de predicados geradas não pode exceder um milhão.

Esses limites podem mudar.

Status atual das estatísticas do DFE

É possível conferir o status atual das estatísticas do DFE usando a seguinte solicitação curl:

curl -G "$STATISTICS_ENDPOINT"

A resposta a uma solicitação de status contém os seguintes campos:

• status: o código de retorno HTTP da solicitação. Se a solicitação for bem-sucedida, o código será 200. Para obter uma lista de erros comuns, consulte Erros comuns.

• payload:

  • autoCompute: (booliano) indica se a geração automática de estatísticas está habilitada ou não.

  • active: (booliano) indica se a geração automática de estatísticas do DFE está ou não habilitada.

  • statisticsId : relata o ID da execução atual da geração de estatísticas. Um valor de -1 indica que nenhuma estatística foi gerada.

  • date: a hora UTC na qual as estatísticas do DFE foram geradas mais recentemente, no formato ISO 8601.

    nota

    Antes da versão 1.2.1.0 do mecanismo, isso era representado com precisão de minutos, mas a partir da versão 1.2.1.0 do mecanismo, é representado com precisão de milissegundos (por exemplo, 2023-01-24T00:47:43.319Z).

  • note: uma observação sobre problemas no caso em que as estatísticas são inválidas.

  • signatureInfo: contém informações sobre os conjuntos de características gerados nas estatísticas (antes da versão 1.2.1.0 do mecanismo, esse campo era denominado summary). Geralmente, eles não são diretamente úteis:

    • signatureCount: o número total de assinaturas em todos os conjuntos de características.

    • instanceCount: o número total de instâncias do conjunto de características.

    • predicateCount: o número total de predicados exclusivos.

A resposta a uma solicitação de status quando nenhuma estatística foi gerada é semelhante a esta:

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

Se as estatísticas do DFE estiverem disponíveis, a resposta será semelhante a esta:

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

Se ocorrer uma falha na geração de estatísticas do DFE, por exemplo, porque excedeu o limite de tamanho das estatísticas, a resposta será semelhante a esta:

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

Desabilitar a geração automática de estatísticas do DFE

Por padrão, a geração automática de estatísticas do DFE é habilitada quando você habilita o DFE.

É possível desabilitar a geração automática da seguinte forma:

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

Se a solicitação for bem-sucedida, o código de resposta HTTP será 200 e a resposta será:

{
  "status" : "200 OK"
}

É possível confirmar se a geração automática está desabilitada permitindo uma solicitação de status e conferindo se o campo autoCompute na resposta está definido como false.

A desativação da geração automática de estatísticas não encerra um cálculo estatístico em andamento.

Se você fizer uma solicitação para desabilitar a geração automática para uma instância de leitor e não para a instância de gravador do cluster de banco de dados, ocorrerá uma falha na solicitação com um código de retorno HTTP de 400 e uma saída como a seguinte:

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

Consulte Erros comuns para obter uma lista de outros erros comuns.

Reabilitar a geração automática de estatísticas do DFE

Por padrão, a geração automática de estatísticas do DFE já é habilitada quando você habilita o DFE. Se você desabilitar a geração automática, poderá reabilitá-la posteriormente da seguinte maneira:

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

Se a solicitação for bem-sucedida, o código de resposta HTTP será 200 e a resposta será:

{
  "status" : "200 OK"
}

É possível confirmar se a geração automática está habilitada permitindo uma solicitação de status e conferindo se o campo autoCompute na resposta está definido como true.

Acionar manualmente a geração de estatísticas do DFE

É possível iniciar a geração de estatísticas do DFE manualmente da seguinte forma:

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

Se a solicitação for bem-sucedida, a saída será a seguinte, com um código de retorno HTTP de 200:

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

O statisticsId na saída é o ID da execução da geração de estatísticas que está ocorrendo atualmente. Se uma execução já estiver em andamento no momento da solicitação, a solicitação vai gerar o ID dessa execução em vez de iniciar outra. Somente uma execução de geração de estatísticas pode ocorrer por vez.

Se ocorrer um failover enquanto as estatísticas do DFE estiverem sendo geradas, o novo nó de gravador selecionará o último ponto de verificação processado e retomará a execução das estatísticas a partir daí.

Usando a StatsNumStatementsScanned CloudWatch métrica para monitorar o cálculo estatístico

A StatsNumStatementsScanned CloudWatch métrica retorna o número total de declarações escaneadas para cálculo estatístico desde a inicialização do servidor. Ela é atualizada em cada fatia de cálculo de estatísticas.

Toda vez que o cálculo de estatísticas é acionado, esse número aumenta e, quando nenhum cálculo está acontecendo, ele permanece constante. Portanto, a análise de um gráfico de valores StatsNumStatementsScanned ao longo do tempo oferece uma imagem bem clara de quando o cálculo de estatísticas estava acontecendo e com que rapidez:

Quando o cálculo está ocorrendo, a inclinação do grafo mostra a velocidade (quanto mais íngreme a inclinação, com maior rapidez as estatísticas são calculadas).

Se o grafo for simplesmente uma linha plana em 0, o atributo de estatísticas foi habilitado, mas nenhuma estatística foi calculada. Se o atributo de estatísticas tiver sido desativado ou se você estiver usando uma versão do mecanismo que não é compatível com o cálculo de estatísticas, StatsNumStatementsScanned não existe.

Conforme mencionado anteriormente, é possível desabilitar o cálculo de estatísticas usando a API de estatísticas, mas deixá-lo desabilitado pode fazer com que as estatísticas não estejam atualizadas, o que, por sua vez, pode ocasionar a geração deficiente do plano de consulta para o mecanismo do DFE.

Consulte Monitorando Neptune usando a Amazon CloudWatch para obter informações sobre como usar CloudWatch.

Usando a autenticação AWS Identity and Access Management (IAM) com endpoints de estatísticas do DFE

É possível acessar os endpoints de estatísticas do DFE de forma segura com a autenticação do IAM usando awscurl ou qualquer outra ferramenta que funcione com HTTPS e IAM. Consulte Usar awscurl com credenciais temporárias para se conectar com segurança a um cluster de banco de dados com a autenticação do IAM habilitada para saber como configurar as credenciais adequadas. Depois de fazer isso, é possível fazer uma solicitação de status como esta:

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

Ou, por exemplo, você pode criar um arquivo JSON denominado request.json que contém:

{ "mode" : "refresh" }

Depois, é possível iniciar a geração de estatísticas manualmente da seguinte forma:

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

Excluir estatísticas do DFE

É possível excluir todas as estatísticas no banco de dados fazendo uma solicitação HTTP DELETE para o endpoint de estatísticas:

curl -X "DELETE" "$STATISTICS_ENDPOINT"

Os códigos de retorno HTTP válidos são:

• 200: a exclusão foi bem-sucedida.

  Nesse caso, uma resposta típica seria:

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

• 204: não havia estatísticas para excluir.

  Nesse caso, a resposta está em branco (sem resposta).

Se você enviar uma solicitação de exclusão a um endpoint de estatísticas em um nó de leitor, uma ReadOnlyViolationException será lançada.

Códigos de erro comuns para solicitação de estatísticas do DFE

Veja a seguir uma lista de erros comuns que podem ocorrer quando você faz uma solicitação a um endpoint de estatísticas:

• AccessDeniedException: Código de retorno: 400. Mensagem: Missing Authentication Token.

• BadRequestException (para Gremlin e openCypher): Código de retorno: 400. Mensagem: Bad route: /pg/statistics.

• BadRequestException (para dados do RDF): Código de retorno: 400. Mensagem: Bad route: /rdf/statistics.

• InvalidParameterException: Código de retorno: 400. Mensagem: Statistics command parameter 'mode' has unsupported value 'the invalid value'.

• MissingParameterException: Código de retorno: 400. Mensagem: Content-type header not specified..

• ReadOnlyViolationException: Código de retorno: 400. Mensagem: Writes are not permitted on a read replica instance.

Por exemplo, se você fizer uma solicitação quando o DFE e as estatísticas não estiverem habilitados, receberá uma resposta como a seguinte:

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