Usar consulta de explicação

Visualização

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

O Query Explain permite enviar consultas no modo Datastore para o back-end e receber estatísticas detalhadas de desempenho sobre a execução da consulta de back-end. Ela funciona como a operação EXPLAIN ANALYZE em muitos sistemas de banco de dados relacional.

É possível enviar solicitações do Query Explain usando as bibliotecas de cliente do modo Datastore.

Os resultados do Query Explain ajudam a entender como suas consultas são executadas, mostrando ineficiências e a localização de prováveis gargalos do lado do servidor.

Explicação da consulta:

• Fornece informações sobre a fase de planejamento para que você possa ajustar seus índices de consulta e aumentar a eficiência.
• Ajuda a entender o custo e o desempenho por consulta e permite iterar rapidamente diferentes padrões de consulta para otimizar o uso deles.

Entender as opções de Query Explain: default e analyze

É possível executar as operações do Query Explain usando a opção default ou a opção analyze.

Com a opção padrão, a Query Explain planeja a consulta, mas ignora o estágio de execução. Isso retornará informações do estágio do planejador. É possível usar isso para verificar se uma consulta tem os índices necessários e entender quais índices são usados. Isso ajudará você a verificar, por exemplo, se uma consulta específica está usando um índice composto em vez de precisar cruzar com muitos índices diferentes.

Com a opção de análise, a consulta explica os dois planos e executa a consulta. Isso retorna todas as informações do planejador mencionadas anteriormente, além de estatísticas do ambiente de execução da consulta. Isso inclui informações de faturamento e insights no nível do sistema sobre a execução da consulta. É possível usar essas ferramentas para testar várias configurações de consulta e índice para otimizar o custo e a latência.

Qual é o custo da Query Explain?

Quando uma consulta é explicada com a opção padrão, nenhuma operação de índice ou leitura é realizada. Independentemente da complexidade da consulta, uma operação de leitura é cobrada.

Quando uma consulta é explicada com a opção de análise, as operações de índice e leitura são executadas, portanto, a consulta é cobrada como de costume. Não há cobrança extra para a atividade de análise, apenas a cobrança normal para a consulta que está sendo executada.

Executar uma consulta com a opção padrão

Você pode usar uma biblioteca de cliente para enviar uma solicitação de opção padrão.

Observe que os resultados da explicação da consulta são autenticados com o Identity and Access Management, usando as mesmas permissões para operações de consulta normais.

Observação :uma execução de consulta é analisada por vez. Portanto, os resultados do tempo da explicação da consulta podem variar de solicitação para solicitação. Ela pode ajudar a detectar ineficiências estruturais significativas, mas não fornece estatísticas agregadas sobre o desempenho de consultas.

Java

Para saber como instalar e usar a biblioteca de cliente para o modo Datastore, consulte Bibliotecas de cliente do modo Datastore. Para mais informações, consulte a documentação de referência da API Java do modo Datastore.

Para autenticar no modo Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.datastore.Datastore;
import com.google.cloud.datastore.DatastoreOptions;
import com.google.cloud.datastore.Entity;
import com.google.cloud.datastore.Query;
import com.google.cloud.datastore.QueryResults;
import com.google.cloud.datastore.models.ExplainMetrics;
import com.google.cloud.datastore.models.ExplainOptions;
import com.google.cloud.datastore.models.PlanSummary;
import java.util.List;
import java.util.Map;
import java.util.Optional;

public class QueryProfileExplain {
  public static void invoke() throws Exception {
    // Instantiates a client
    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();

    // Build the query
    Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").build();

    // Set the explain options to get back *only* the plan summary
    QueryResults<Entity> results = datastore.run(query, ExplainOptions.newBuilder().build());

    // Get the explain metrics
    Optional<ExplainMetrics> explainMetrics = results.getExplainMetrics();
    if (!explainMetrics.isPresent()) {
      throw new Exception("No explain metrics returned");
    }
    PlanSummary planSummary = explainMetrics.get().getPlanSummary();
    List<Map<String, Object>> indexesUsed = planSummary.getIndexesUsed();
    System.out.println("----- Indexes Used -----");
    indexesUsed.forEach(map -> map.forEach((key, val) -> System.out.println(key + ": " + val)));
  }
}

Veja o campo indexes_used na resposta para saber mais sobre os índices usados no plano de consulta:

"indexes_used": [
        {"query_scope": "Collection Group", "properties": "(__name__ ASC)"},
]

Para mais informações, consulte a referência de relatórios.

Executar uma consulta com a opção de análise

Você pode usar uma biblioteca de cliente para enviar uma solicitação de opção padrão.

Observe que os resultados da análise da consulta são autenticados com o Identity and Access Management (IAM), usando as mesmas permissões para operações de consulta normais.

Observação :uma execução de consulta é analisada por vez. Portanto, os resultados do tempo da consulta podem variar de solicitação para solicitação. Ela pode ajudar a detectar ineficiências estruturais significativas, mas não fornece estatísticas agregadas sobre o desempenho de consultas.

Java

Para saber como instalar e usar a biblioteca de cliente para o modo Datastore, consulte Bibliotecas de cliente do modo Datastore. Para mais informações, consulte a documentação de referência da API Java do modo Datastore.

Para autenticar no modo Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.datastore.Datastore;
import com.google.cloud.datastore.DatastoreOptions;
import com.google.cloud.datastore.Entity;
import com.google.cloud.datastore.Query;
import com.google.cloud.datastore.QueryResults;
import com.google.cloud.datastore.models.ExecutionStats;
import com.google.cloud.datastore.models.ExplainMetrics;
import com.google.cloud.datastore.models.ExplainOptions;
import com.google.cloud.datastore.models.PlanSummary;
import java.util.List;
import java.util.Map;

public class QueryProfileExplainAnalyze {
  public static void invoke() throws Exception {
    // Instantiates a client
    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();

    // Build the query
    Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").build();

    // Set explain options with analzye = true to get back the query stats, plan info, and query
    // results
    QueryResults<Entity> results =
        datastore.run(query, ExplainOptions.newBuilder().setAnalyze(true).build());

    // Get the result set stats
    if (!results.getExplainMetrics().isPresent()) {
      throw new Exception("No explain metrics returned");
    }
    ExplainMetrics explainMetrics = results.getExplainMetrics().get();

    // Get the execution stats
    if (!explainMetrics.getExecutionStats().isPresent()) {
      throw new Exception("No execution stats returned");
    }

    ExecutionStats executionStats = explainMetrics.getExecutionStats().get();
    Map<String, Object> debugStats = executionStats.getDebugStats();
    System.out.println("----- Debug Stats -----");
    debugStats.forEach((key, val) -> System.out.println(key + ": " + val));
    System.out.println("----------");

    long resultsReturned = executionStats.getResultsReturned();
    System.out.println("Results returned: " + resultsReturned);

    // Get the plan summary
    PlanSummary planSummary = explainMetrics.getPlanSummary();
    List<Map<String, Object>> indexesUsed = planSummary.getIndexesUsed();
    System.out.println("----- Indexes Used -----");
    indexesUsed.forEach(map -> map.forEach((key, val) -> System.out.println(key + ": " + val)));

    if (!results.hasNext()) {
      throw new Exception("query yielded no results");
    }

    // Get the query results
    System.out.println("----- Query Results -----");
    while (results.hasNext()) {
      Entity entity = results.next();
      System.out.printf("Entity: %s%n", entity);
    }
  }
}

Consulte o objeto executionStats para encontrar informações de criação de perfil de consulta, como:

{
    "resultsReturned": "5",
    "executionDuration": "0.100718s",
    "readOperations": "5",
    "debugStats": {
               "index_entries_scanned": "95000",
               "documents_scanned": "5"
               "billing_details": {
                     "documents_billable": "5",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }
}

Para mais informações, consulte a referência de relatórios.

Interpretar resultados e fazer ajustes

No cenário de exemplo a seguir, consultamos filmes por gênero e país de produção e demonstra como otimizar os índices usados pela consulta.

Observação :o Query Explain foi criado para análises ad-hoc úteis. O formato do relatório evoluirá para maximizar a facilidade de leitura e a compreensão, e não a adequação para o processamento da máquina. Espera-se que algumas métricas retornadas mudem à medida que o modo Datastore evolui (métricas podem ser adicionadas, removidas ou atualizadas) e não são cobertas pela mesma política de descontinuação de outras APIs do modo Datastore.

Para mais informações sobre o relatório, consulte a referência do relatório do Query Explain.

Para fins de ilustração, suponha o equivalente a esta consulta SQL.

SELECT *
FROM movies
WHERE category = 'Romantic' AND country = 'USA';

Se usarmos a opção de análise, a saída do relatório a seguir vai mostrar a consulta executada nos índices de campo único (category ASC, __name__ ASC) e (country ASC, __name__ ASC). Ela verifica 16.500 entradas de índice, mas retorna apenas 1.200 documentos.

// Output query planning info
"indexes_used": [
    {"query_scope": "Collection Group", "properties": "(category ASC, __name__ ASC)"},
    {"query_scope": "Collection Group", "properties": "(country ASC, __name__ ASC)"},
]

// Output query status
{
    "resultsReturned": "1200",
    "executionDuration": "0.118882s",
    "readOperations": "1200",
    "debugStats": {
               "index_entries_scanned": "16500",
               "documents_scanned": "1200"
               "billing_details": {
                     "documents_billable": "1200",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }
}

Para otimizar o desempenho da execução da consulta, crie um índice composto totalmente coberto (categoria ASC, país ASC, __name__ ASC).

Ao executar a consulta no modo de análise novamente, podemos ver que o índice recém-criado é selecionado para essa consulta e que a consulta é executada com muito mais rapidez e eficiência.

// Output query planning info
    "indexes_used": [
        {"query_scope": "Collection Group", "properties": "(category ASC, country ASC, __name__ ASC)"}
        ]

// Output query stats
{
    "resultsReturned": "1200",
    "executionDuration": "0.026139s",
    "readOperations": "1200",
    "debugStats": {
               "index_entries_scanned": "1200",
               "documents_scanned": "1200"
               "billing_details": {
                     "documents_billable": "1200",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }
}

A seguir

• Saiba mais sobre o relatório de explicação de consulta
• Saiba mais sobre como otimizar consultas e índices