Analisar a execução de consultas com o Query Explain

Esta página descreve como recuperar informações de execução de consultas ao executar uma consulta.

Usar o Query Explain

Use o Query Explain para entender como suas consultas estão sendo executadas. Isso fornece detalhes que podem ser usados para otimizar suas consultas.

É possível usar o Query Explain no Google Cloud console ou usando as bibliotecas de cliente do servidor do Firestore.

Console

Execute uma consulta no Editor de consultas e abra a guia Explicação:

  1. No Google Cloud console, acesse a página Bancos de dados.

    Acessar "Bancos de dados"

  2. Na lista de bancos de dados, selecione um banco de dados do Firestore. O Google Cloud console abre o Firestore Explorer para esse banco de dados.
  3. Insira uma consulta no editor de consultas e clique em Executar.

  4. Clique na guia Explicação para conferir a saída da análise de consulta.

Node.js (Admin)
const q = db.pipeline()
        .collection('/users')
        .sort(field('status').ascending())
        .limit(100);
let results;
try {
    results = await q.execute({
        explainOptions: { mode: 'analyze', outputFormat: 'text' }
    });
} catch (error) {
    console.log(error);
}
const metrics = results?.explainStats?.text;

console.log(metrics);
Java (Admin)
Pipeline q = db.pipeline()
        .collection("/users")
        .sort(field("status").ascending())
        .limit(100);

PipelineExecuteOptions pipelineOpts = new PipelineExecuteOptions().withExplainOptions(
        new ExplainOptions().withExecutionMode(ExplainOptions.ExecutionMode.ANALYZE)
);
Pipeline.Snapshot result = q.execute(pipelineOpts).get();

String metrics = null;
if (result.getExplainStats() != null) {
    metrics = result.getExplainStats().getText();
    System.out.println(metrics);
}

Modos de explicação

Dependendo do que você quer depurar, é possível executar uma consulta com o Query Explain em diferentes modos:

  • analyze: planeja e executa a consulta. Retorna informações do planejador, estatísticas e métricas de execução de tempo de execução, além dos resultados normais produzidos pela consulta.

  • explain: planeja a consulta, mas não a executa. Retorna as informações do planejador, mas não estatísticas, métricas ou resultados de tempo de execução. Isso é útil para depurar o comportamento de uma consulta sem executar operações caras.

Análise

A saída do Query Explain contém dois componentes principais: as estatísticas de resumo e a árvore de execução. Considere esta consulta como exemplo:

db.pipeline().collection('/users').sort(field("status").ascending()).limit(100)

Estatísticas de resumo

A parte de cima da saída explicada contém um resumo das estatísticas de execução. Use essas estatísticas para determinar se uma consulta tem alta latência ou custo. Além disso, contém estatísticas de memória que informam se a consulta está próxima dos limites de memória.

Execution:
 results returned: 2
 request peak memory usage: 20.25 KiB (20,736 B)
 data bytes read: 148 B
 entity row scanned: 2

Billing:
 read units: 1

Árvore de execução

A árvore de execução descreve a execução da consulta como uma série de nós. Os nós inferiores (nós folha) recuperam dados da camada de armazenamento, que percorre a árvore para gerar uma resposta de consulta.

Para detalhes sobre cada nó de execução, consulte a Referência de execução.

Para saber como usar essas informações para otimizar suas consultas, consulte Otimizar a execução de consultas.

Confira um exemplo de árvore de execução:

Tree:
• Compute
|  $out_1: map_set($record_1, "__name__", $__name___1, "__key__", unset)
|  is query result: true
|
|  Execution:
|   records returned: 2
|   latency: 5.96 ms (local <1 ms)
|
└── • Compute
    |  $__name___1: map_get($record_1, "__key__")
    |
    |  Execution:
    |   records returned: 2
    |   latency: 5.88 ms (local <1 ms)
    |
    └── • MajorSort
        |  fields: [$v_1 ASC]
        |  output: [$record_1]
        |  limit: 100
        |
        |  Execution:
        |   records returned: 2
        |   latency: 5.86 ms (local <1 ms)
        |   peak memory usage: 20.25 KiB (20,736 B)
        |
        └── • Compute
            |  $v_1: map_get($record_1, "status")
            |
            |  Execution:
            |   records returned: 2
            |   latency: 5.23 ms (local <1 ms)
            |
            └── • TableScan
                   source: /users
                   order: UNDEFINED
                   properties: *
                   row range: (-∞..+∞)
                   output record: $record_1
                   variables: [$record_1]

                   Execution:
                    records returned: 2
                    latency: 4.68 ms
                    records scanned: 2
                    data bytes read: 148 B

A seguir