View a markdown version of this page

Cache do plano de consulta no Amazon Neptune - Amazon Neptune
Como habilitar ou desabilitar à força o cache do plano de consultasComo determinar se um plano está armazenado em cache ou nãoRemoçãoCondições que fazem com que o plano não seja armazenado em cache

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Cache do plano de consulta no Amazon Neptune

Quando uma consulta é enviada ao Neptune, a string de consulta é analisada, otimizada e transformada em um plano de consulta, executado pelo mecanismo. As aplicações muitas vezes são apoiadas por padrões de consulta comuns que são instanciados com diferentes valores. O cache do plano de consultas pode reduzir a latência geral ao armazenar em cache os planos de consulta e, assim, evitar a análise e a otimização desses padrões repetidos.

O Cache do Plano de Consulta pode ser usado para OpenCypherconsultas — consultas não parametrizadas ou parametrizadas. Ele está habilitado para READ e para HTTP e Bolt. Não é compatível com consultas de mutação do OC. Não é compatível com consultas Gremlin ou SPARQL.

Como habilitar ou desabilitar à força o cache do plano de consultas

O cache do plano de consulta é habilitado por padrão para consultas parametrizadas de baixa latência. Um plano para uma consulta parametrizada é armazenado em cache somente quando a latência é inferior ao limite de 100 ms. Esse comportamento pode ser alterado para cada consulta (parametrizada ou não) por meio da dica de consulta em nível de consulta QUERY:PLANCACHE. Ele precisa ser usado com a cláusula USING. A dica de consulta aceita enabled ou disabled como valor.

AWS CLI

Forçando o plano a ser armazenado em cache ou reutilizado:

aws neptunedata execute-open-cypher-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "Using QUERY:PLANCACHE \"enabled\" MATCH(n) RETURN n LIMIT 1"

Com parâmetros:

aws neptunedata execute-open-cypher-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "Using QUERY:PLANCACHE \"enabled\" RETURN \$arg" \
  --parameters '{"arg": 123}'

Forçando o plano a não ser armazenado em cache nem reutilizado:

aws neptunedata execute-open-cypher-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "Using QUERY:PLANCACHE \"disabled\" MATCH(n) RETURN n LIMIT 1"

Para obter mais informações, consulte execute-open-cypher-queryna Referência de AWS CLI Comandos.

SDK
import boto3
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

# Forcing plan to be cached or reused
response = client.execute_open_cypher_query(
    openCypherQuery='Using QUERY:PLANCACHE "enabled" MATCH(n) RETURN n LIMIT 1'
)

print(response['results'])

Para exemplos de AWS SDK em outras linguagens, consulteAWS SDK.

awscurl

Forçando o plano a ser armazenado em cache ou reutilizado:

awscurl https://your-neptune-endpoint:port/openCypher \
  --region us-east-1 \
  --service neptune-db \
  -X POST \
  -d "query=Using QUERY:PLANCACHE \"enabled\" MATCH(n) RETURN n LIMIT 1"
nota

Este exemplo pressupõe que suas AWS credenciais estejam configuradas em seu ambiente. us-east-1Substitua pela região do seu cluster Neptune.

curl

Forçando o plano a ser armazenado em cache ou reutilizado:

curl https://your-neptune-endpoint:port/openCypher \
  -d "query=Using QUERY:PLANCACHE \"enabled\" MATCH(n) RETURN n LIMIT 1"

Com parâmetros:

curl https://your-neptune-endpoint:port/openCypher \
  -d "query=Using QUERY:PLANCACHE \"enabled\" RETURN \$arg" \
  -d "parameters={\"arg\": 123}"

Forçando o plano a não ser armazenado em cache nem reutilizado:

curl https://your-neptune-endpoint:port/openCypher \
  -d "query=Using QUERY:PLANCACHE \"disabled\" MATCH(n) RETURN n LIMIT 1"

Como determinar se um plano está armazenado em cache ou não

Para HTTP READ, se a consulta foi enviada e o plano está armazenado em cache, explain mostra detalhes relevantes ao cache do plano de consultas.

AWS CLI
aws neptunedata execute-open-cypher-explain-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "Using QUERY:PLANCACHE \"enabled\" MATCH(n) RETURN n LIMIT 1" \
  --explain-mode details

Para obter mais informações, consulte execute-open-cypher-explain-query na Referência de AWS CLI Comandos.

SDK
import boto3
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

response = client.execute_open_cypher_explain_query(
    openCypherQuery='Using QUERY:PLANCACHE "enabled" MATCH(n) RETURN n LIMIT 1',
    explainMode='details'
)

print(response['results'].read().decode('utf-8'))

Para exemplos de AWS SDK em outras linguagens, consulteAWS SDK.

awscurl
awscurl https://your-neptune-endpoint:port/openCypher \
  --region us-east-1 \
  --service neptune-db \
  -X POST \
  -d "query=Using QUERY:PLANCACHE \"enabled\" MATCH(n) RETURN n LIMIT 1" \
  -d "explain=details"
nota

Este exemplo pressupõe que suas AWS credenciais estejam configuradas em seu ambiente. us-east-1Substitua pela região do seu cluster Neptune.

curl
curl https://your-neptune-endpoint:port/openCypher \
  -d "query=Using QUERY:PLANCACHE \"enabled\" MATCH(n) RETURN n LIMIT 1" \
  -d "explain=details"

Se o plano foi armazenado em cache, a explain saída mostra:

Query: <QUERY STRING>
Plan cached by request: <REQUEST ID OF FIRST TIME EXECUTION>
Plan cached at: <TIMESTAMP OF FIRST TIME EXECUTION>
Parameters: <PARAMETERS, IF QUERY IS PARAMETERIZED QUERY>
Plan cache hits: <NUMBER OF CACHE HITS FOR CACHED PLAN>
First query evaluation time: <LATENCY OF FIRST TIME EXECUTION>

The query has been executed based on a cached query plan. Detailed explain with operator runtime statistics can be obtained by running the query with plan cache disabled (using HTTP parameter planCache=disabled).

Ao usar o Bolt, o recurso de explicação não é compatível.

Remoção

Um plano de consulta é removido pelo tempo de vida útil (TTL) do cache ou quando um número máximo de planos de consulta armazenados em cache é atingido. Quando o plano de consultas é atingido, o TTL é atualizado. Os padrões são:

  • 1000: o número máximo de planos que podem ser armazenados em cache por instância.

  • TTL: 300 mil milissegundos ou 5 minutos. O acerto de cache reinicia o TTL e o redefine para 5 min.

Condições que fazem com que o plano não seja armazenado em cache

O cache do plano de consultas não é usado nas seguintes condições:

  1. Quando uma consulta é enviada usando a dica de consulta QUERY:PLANCACHE "disabled". Você pode executar novamente a consulta e remover QUERY:PLANCACHE "disabled" para habilitar o cache do plano de consulta.

  2. Se a consulta enviada não for uma consulta parametrizada e não contiver a dica QUERY:PLANCACHE "enabled".

  3. Se o tempo de avaliação da consulta for maior que o limite de latência, a consulta não será armazenada em cache e será considerada uma consulta de longa duração que não se beneficiaria do cache do plano de consulta.

  4. Se a consulta contiver um padrão que não retorne nenhum resultado.

    • Ou seja, MATCH (n:nonexistentLabel) return n quando há zero nós com o rótulo especificado.

    • Ou seja, MATCH (n {name: $param}) return n com parameters={"param": "abcde"} quando não há nenhum nó contendo name=abcde.

  5. Se o parâmetro de consulta for um tipo composto, como list ou map. 

    curl https://your-neptune-endpoint:port/openCypher \
  -d "query=Using QUERY:PLANCACHE \"enabled\" RETURN \$arg" \
  -d "parameters={\"arg\": [1, 2, 3]}"

curl https://your-neptune-endpoint:port/openCypher \
  -d "query=Using QUERY:PLANCACHE \"enabled\" RETURN \$arg" \
  -d "parameters={\"arg\": {\"a\": 1}}"

  6. Se o parâmetro de consulta for uma string que não fez parte de uma operação de carregamento ou inserção de dados. Por exemplo, se CREATE (n {name: "X"}) for executado para inserir "X", então RETURN "X" será armazenado em cache, mas RETURN "Y" não será armazenado em cache, pois "Y" não foi inserido e não existe no banco de dados.