Pular para o conteúdo principal
Mostra o plano de execução de uma instrução.
Sintaxe:
Exemplo:

​
Tipos de EXPLAIN

  • AST — Árvore de sintaxe abstrata.
  • SYNTAX — Texto da consulta após otimizações no nível da AST.
  • QUERY TREE — Árvore de consulta após otimizações no nível da Query Tree.
  • PLAN — Plano de execução da consulta.
  • PIPELINE — Pipeline de execução da consulta.

​
EXPLAIN AST

Exibe a AST da consulta. Compatível com todos os tipos de consulta, não apenas SELECT. Configurações:
  • graph – Exibe a AST como um grafo descrito na linguagem de descrição de grafos DOT. Padrão: 0.
Exemplos:

​
EXPLAIN SYNTAX

Mostra a Árvore de Sintaxe Abstrata (AST) de uma consulta após a análise de sintaxe. Isso é feito fazendo o parsing da consulta, construindo a AST e a árvore de consulta da consulta, opcionalmente executando o analisador de consultas e os passes de otimização, e então convertendo a árvore de consulta de volta para a AST da consulta. Configurações:
  • oneline – Imprime a consulta em uma única linha. Padrão: 0.
  • run_query_tree_passes – Executa os passes da árvore de consulta antes de exibi-la. Padrão: 0.
  • query_tree_passes – Se run_query_tree_passes estiver definido, especifica quantos passes executar. Sem especificar query_tree_passes, ele executa todos os passes.
Exemplos:
Query
Response
Usando run_query_tree_passes:
Query
Response

​
EXPLAIN QUERY TREE

Configurações:
  • run_passes — Executa todos os passes da árvore de consulta antes de exibir a árvore de consulta. Padrão: 1.
  • dump_passes — Exibe informações sobre os passes usados antes de exibir a árvore de consulta. Padrão: 0.
  • passes — Especifica quantos passes devem ser executados. Se definido como -1, executa todos os passes. Padrão: -1.
  • dump_tree — Exibe a árvore de consulta. Padrão: 1.
  • dump_ast — Exibe a AST da consulta gerada a partir da árvore de consulta. Padrão: 0.
Exemplo:

​
EXPLAIN PLAN

Exibe os passos do plano de consulta. Configurações:
  • optimize — Controla se as otimizações do plano de consulta são aplicadas antes da exibição do plano. Padrão: 1.
  • header — Exibe o cabeçalho de saída do passo. Padrão: 0.
  • description — Exibe a descrição do passo. Padrão: 1.
  • indexes — Mostra os índices usados, o número de partes filtradas e o número de grânulos filtrados para cada índice aplicado. Padrão: 0. Compatível com tabelas MergeTree. A partir do ClickHouse >= v25.9, esta instrução só exibe uma saída adequada quando usada com SETTINGS use_query_condition_cache = 0, use_skip_indexes_on_data_read = 0.
  • projections — Mostra todas as projeções analisadas e seu efeito na filtragem no nível de partes com base nas condições da chave primária da projeção. Para cada projeção, esta seção inclui estatísticas como o número de partes, linhas, marcas e intervalos avaliados usando a chave primária da projeção. Também mostra quantas partes de dados foram ignoradas devido a essa filtragem, sem ler a própria projeção. Se uma projeção foi realmente usada para leitura ou apenas analisada para filtragem pode ser determinado pelo campo description. Padrão: 0. Compatível com tabelas MergeTree.
  • actions — Exibe informações detalhadas sobre as ações do passo. Padrão: 0.
  • sorting — Exibe a descrição da ordenação para cada passo do plano que produz saída ordenada. Padrão: 0.
  • keep_logical_steps — Mantém os passos lógicos do plano para junções em vez de convertê-los em implementações físicas de junção. Padrão: 0.
  • json — Exibe os passos do plano de consulta como uma linha no formato JSON. Padrão: 0. Recomenda-se usar o formato TabSeparatedRaw (TSVRaw) para evitar escapes desnecessários.
  • input_headers — Exibe os cabeçalhos de entrada do passo. Padrão: 0. Em geral, isso só é útil para desenvolvedores depurarem problemas relacionados à incompatibilidade entre cabeçalhos de entrada e saída.
  • column_structure — Exibe também a estrutura das colunas nos cabeçalhos, além do nome e do tipo. Padrão: 0. Em geral, isso só é útil para desenvolvedores depurarem problemas relacionados à incompatibilidade entre cabeçalhos de entrada e saída.
  • distributed — Mostra os planos de consulta executados em nós remotos para tabelas distribuídas ou réplicas paralelas. Padrão: 0.
  • compact — Quando ativado, oculta do plano os passos de expressão e as informações detalhadas das ações (entradas, funções, aliases e posições de saída). Só tem efeito quando actions = 1. Padrão: 0.
  • pretty — Exibe a árvore do plano usando caracteres de desenho de linha (├──, └──, │) em vez de indentação para visualizar a hierarquia. Também formata as propriedades do passo de junção em linha. Padrão: 0.
Quando json=1, os nomes dos passos contêm um sufixo adicional com um identificador único do passo. Exemplo:
Não há suporte à estimativa de custo do passo e da consulta.
Quando json = 1, o plano da consulta é representado em formato JSON. Cada nó é um dicionário que sempre contém as chaves Node Type e Plans. Node Type é uma string com o nome de um passo. Plans é um array com descrições dos passos filhos. Outras chaves opcionais podem ser adicionadas dependendo do tipo de nó e das configurações. Exemplo:
Com description = 1, a chave Description é adicionada ao passo:
Com header = 1, a chave Header é adicionada ao passo na forma de um array de colunas. Exemplo:
Com indexes = 1, a chave Indexes é adicionada. Ela contém um array dos índices usados. Cada índice é descrito como JSON com a chave Type (uma string Partition Min-Max, Partition, Statistics, PrimaryKey ou Skip) e chaves opcionais:
  • Name — O nome do índice (atualmente usado apenas para índices Skip).
  • Keys — O array de colunas usado pelo índice.
  • Condition — A condição usada.
  • Description — A descrição do índice (atualmente usada apenas para índices Skip).
  • Parts — O número de partes após/antes da aplicação do índice.
  • Granules — O número de grânulos após/antes da aplicação do índice.
  • Ranges — O número de intervalos de grânulos após a aplicação do índice.
Exemplo:
Com projections = 1, a chave Projections é adicionada. Ela contém um array de projeções analisadas. Cada projeção é descrita em JSON com as seguintes chaves:
  • Name — O nome da projeção.
  • Condition — A condição usada na chave primária da projeção.
  • Description — A descrição de como a projeção é usada (por exemplo, filtragem em nível de parte).
  • Selected Parts — Número de partes selecionadas pela projeção.
  • Selected Marks — Número de marcas selecionadas.
  • Selected Ranges — Número de intervalos selecionados.
  • Selected Rows — Número de linhas selecionadas.
  • Filtered Parts — Número de partes ignoradas devido à filtragem em nível de parte.
Exemplo:
Com actions = 1, as chaves adicionadas dependem do tipo de passo. Exemplo:
Com compact = 1, cada passo de Expression é removido. Além disso, se actions = 1 estiver definido, as linhas Actions e Positions ficam ocultas, deixando apenas as descrições dos passos:
Com distributed = 1, a saída inclui não apenas o plano de consulta local, mas também os planos de consulta que serão executados nos nós remotos. Isso é útil para analisar e depurar consultas distribuídas. Exemplo com tabela distribuída:
Exemplo com réplicas paralelas:
Em ambos os exemplos, o plano de consulta exibe o fluxo de execução completo, incluindo etapas locais e remotas. Com pretty = 1, a árvore do plano é exibida usando caracteres de desenho de linhas em vez de recuo, e informações adicionais são mostradas para os passos principais:
  • As colunas de saída da consulta são exibidas no topo do plano.
  • As expressões em filtros, chaves de agregação, descrições de ordenação e funções de janela são exibidas em uma notação semelhante a SQL e legível por humanos (por exemplo, a + 1 > 5 em vez de greater(plus(a, 1), 5)). Os prefixos internos de identificadores de coluna (como __table1.) são removidos para maior clareza.
  • Os passos de source (como ReadFromMergeTree) exibem suas colunas de saída.
  • Os passos de filtro exibem a condição de filtro em notação SQL. Quando há filtros de join em runtime, eles são mostrados separadamente.
  • Os passos de agregação exibem chaves e funções de agregação com seus argumentos (por exemplo, sum(c), count()).
  • Os conjuntos IN de literais Tuple mostram seus valores (truncados para conjuntos grandes), os conjuntos baseados em subquery são rotulados como subquery1, subquery2 etc., e os conjuntos de tabelas com engine Set mostram o nome da tabela.
  • Os passos de join exibem a relação de join usando notação matemática, a contagem estimada de linhas do resultado e quais colunas de saída vêm do lado esquerdo e quais vêm do lado direito. Os símbolos a seguir são usados para representar diferentes tipos de join:
Por exemplo, t1 ⟕ t2 significa um left join entre as tabelas t1 e t2. O número entre colchetes após o nome da tabela (por exemplo, t1[100]) indica a contagem estimada de linhas quando há estatísticas da tabela disponíveis. A opção pretty funciona bem em conjunto com compact = 1, que oculta os passos Expression e as informações detalhadas de ações, tornando o plano mais fácil de ler.
Um exemplo mais detalhado com junções:

​
EXPLAIN PIPELINE

Configurações:
  • header — Imprime o cabeçalho de cada porta de saída. Padrão: 0.
  • graph — Imprime um grafo descrito na linguagem de descrição de grafos DOT. Padrão: 0.
  • compact — Imprime o grafo no modo compacto se a configuração graph estiver habilitada. Padrão: 1.
Quando compact=0 e graph=1, os nomes dos processadores conterão um sufixo adicional com um identificador exclusivo do processador. Exemplo:

​
EXPLAIN ESTIMATE

Mostra o número estimado de linhas, marcas e partes que serão lidas das tabelas durante o processamento da consulta. Funciona com tabelas da família MergeTree. Exemplo Criando uma tabela:
Query
Query
Response

​
EXPLAIN TABLE OVERRIDE

Mostra o resultado de um override de tabela em um esquema acessado por meio de uma função de tabela. Também faz algumas validações, gerando uma exceção se o override causar algum tipo de falha. Exemplo Suponha que você tenha uma tabela MySQL remota como esta:
Query
Query
Response
A validação não está completa, portanto uma consulta bem-sucedida não garante que o override não cause problemas.
Última modificação em 19 de junho de 2026