Skip to main content
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 árvore de consulta.
  • PLAN — Plano de execução da consulta.
  • PIPELINE — Pipeline de execução da consulta.
  • ANALYZE — Executa a consulta e anota o plano de execução com métricas de runtime medidas.
  • ESTIMATE — Número estimado de linhas, marcas e partes a serem lidas das tabelas durante o processamento da consulta.
  • TABLE OVERRIDE — Resultado validado de um override de tabela em um esquema de função de tabela.

​
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.
  • single_record – Retorna a consulta reformatada como um único registro multilinha em vez de um registro por linha. Padrão: 1 (controlado pela configuração explain_syntax_single_record). Defina como 0 para restaurar a saída histórica de um registro por linha, ou defina explain_syntax_single_record = 0 (globalmente ou em SETTINGS por consulta), ou defina compatibility como qualquer versão anterior à 26.8.
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: 1.
  • 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. Não é compatível com json. 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: 1.
  • 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: 1.
Por padrão, explain_query_plan_default = 'pretty', portanto actions, compact e pretty são inicializados com 1, e o plano é renderizado na forma compacta, com formatação pretty e com anotações de ações. Especificar explicitamente qualquer uma dessas opções na instrução EXPLAIN (por exemplo, EXPLAIN actions = 0, compact = 0, pretty = 0 SELECT ...) sempre substitui o padrão.Antes do ClickHouse 26.7, os valores padrão de actions, compact e pretty eram 0. Você ainda pode obter essa saída definindo explain_query_plan_default = 'legacy' (globalmente ou em SETTINGS por consulta) ou definindo compatibility para qualquer versão anterior à 26.7.As opções json e distributed não habilitam os padrões de pretty (actions, compact e pretty), mesmo quando explain_query_plan_default = 'pretty'. Para incluir detalhes das ações na saída delas, defina actions = 1 manualmente.
Exemplo:
Não há suporte à estimativa de custo do passo e da consulta.
Quando json = 1, o plano de consulta é representado em formato JSON. Cada nó é um dicionário que sempre tem as chaves Node Type, Node Id e Plans. Node Type é uma string com o nome do passo, e Node Id é um identificador exclusivo do passo (o nome do passo com um sufixo numérico, por exemplo, Union_10). 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: O índice Statistics usa estatísticas de coluna por parte (valores mínimo/máximo e o número de valores NULL para colunas Nullable) para pular partes que não podem corresponder ao filtro da consulta.
  • 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 como JSON com as seguintes chaves:
  • Name — O nome da projeção.
  • Condition — A condição da chave primária usada pela projeção.
  • Description — A descrição de como a projeção é usada (por exemplo, filtragem em nível de partes).
  • 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 partes.
Exemplo:
Com actions = 1, as chaves adicionadas dependem do tipo de passo. Exemplo:
Com compact = 0 e actions = 1, os passos de Expression podem ser vistos juntamente com informações detalhadas sobre as expressões:
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.
distributed é exibido apenas na forma legacy (sem pretty), porque a saída pretty não integra os planos de shard remotos à árvore do plano. Por esse motivo, habilitar distributed desabilita automaticamente os padrões de pretty (actions, compact e pretty), independentemente de explain_query_plan_default. Você ainda pode definir actions=1 manualmente. A opção distributed também não é compatível com json.
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.
  • 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 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.
  • Passos de origem (como ReadFromMergeTree) exibem suas colunas de saída.
  • Passos de filtro exibem a condição de filtro em notação SQL. Quando há filtros de join em tempo de execução, eles são mostrados separadamente.
  • Passos de agregação exibem chaves e funções de agregação com seus argumentos (por exemplo, sum(c), count()).
  • Conjuntos de IN de literais Tuple mostram seus valores (truncados para conjuntos grandes), conjuntos baseados em subconsulta são rotulados como subquery1, subquery2 etc., e conjuntos de tabelas com o motor Set mostram o nome da tabela.
  • Passos de join exibem a relação de join usando notação matemática, as estimativas que o otimizador de ordem de junções produziu para o passo (custo, seletividade, linhas de saída e linhas por lado), e as colunas de entrada de cada lado. 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 estatísticas de tabela estão disponíveis. Abaixo da relação de join, cada passo de join exibe as estimativas que o otimizador de ordem de junções produziu para ele:
  • Cost — o custo de toda a subárvore de join abaixo desta etapa, que é o valor que o otimizador minimiza ao comparar ordens de join candidatas. O custo de um join é o número estimado de pares de linhas correspondentes, <selectivity> * <left_rows> * <right_rows>, mais o custo de suas entradas.
  • Selectivity — a fração estimada do produto cartesiano dos dois lados que permanece após a condição de join. Ela é derivada do número de valores distintos (NDV) das chaves de junção: uma igualdade de chave mantém cerca de 1 / max(NDV_left, NDV_right) dos pares, e é usada a menor fração entre as condições de join.
  • Output rows — o número estimado de linhas que o join produz: <selectivity> * <left_rows> * <right_rows> para um join interno, limitado inferiormente a <left_rows> para LEFT, a <right_rows> para RIGHT e a <left_rows> + <right_rows> para FULL, porque um join externo mantém todas as linhas do seu lado preservado. Quando um join SEMI ou ANTI participa da reordenação, ele é estimado como uma fração de seu lado preservado, <preserved_rows> * min(1, <selectivity> * <other_rows>) para SEMI e as linhas restantes para ANTI; caso contrário, usa a fórmula de seu tipo de join.
  • Left / Right — o número estimado de linhas que entram no join por cada lado.
Um valor que o otimizador não conseguiu estimar é exibido como no stats. Isso acontece quando a otimização da ordem de join não foi executada — por exemplo, quando query_plan_optimize_join_order_limit é 0 — ou quando não há base para a estimativa. As linhas Input (left): e Input (right): listam as colunas que cada lado fornece ao join. A opção pretty funciona bem em conjunto com compact = 1, que oculta os passos Expression e informações detalhadas das ações, tornando o plano mais fácil de ler. Um exemplo detalhado com junções. A configuração join_runtime_filter_min_probe_rows é reduzida apenas para que uma tabela tão pequena ainda crie um filtro de join em tempo de execução:

​
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.
  • compact_repeated_processor_chains — Compacta cadeias repetidas adjacentes de processadores na saída de texto, mostrando uma cópia da cadeia com uma contagem de repetições. Isso pode facilitar a leitura de pipelines paralelos quando a mesma cadeia aparece muitas vezes, por exemplo, em junções. Isso não afeta a saída do grafo. Padrão: 0.
Quando compact=0 e graph=1, os nomes dos processadores conterão um sufixo adicional com um identificador exclusivo do processador. Exemplo:

​
EXPLAIN ANALYZE

EXPLAIN ANALYZE de fato executa a consulta, descarta as linhas de resultado e imprime a mesma árvore de plano que EXPLAIN PLAN, com cada passo anotado com o que realmente aconteceu em tempo de execução. Configurações: EXPLAIN ANALYZE aceita as mesmas opções de exibição que EXPLAIN PLAN (documentadas na seção EXPLAIN PLAN).
  • header — consulte a seção EXPLAIN PLAN.
  • description — consulte a seção EXPLAIN PLAN.
  • projections — consulte a seção EXPLAIN PLAN.
  • sorting — consulte a seção EXPLAIN PLAN.
  • input_headers — consulte a seção EXPLAIN PLAN.
  • column_structure — consulte a seção EXPLAIN PLAN.
  • actions — consulte a seção EXPLAIN PLAN. Padrão: 1.
  • indexes — consulte a seção EXPLAIN PLAN. Padrão: 1.
  • compact — consulte a seção EXPLAIN PLAN. Padrão: 1.
  • pretty — consulte a seção EXPLAIN PLAN. Padrão: 1.
  • processors — Para EXPLAIN ANALYZE, imprime uma linha adicional por estágio com a distribuição do tempo decorrido por processador: min, median, max e sum. Útil para identificar desequilíbrio de carga entre processadores paralelos. Padrão: 0.
  • matches — Para EXPLAIN ANALYZE, faz com que as etapas de junção realizem o processamento adicional necessário para as métricas matched, match rate e fanout nos casos em que esses números não podem ser derivados do que a junção produz de qualquer forma. Quando podem, são relatados sem essa opção. Consulte Etapas de junção. Padrão: 0.
Como EXPLAIN ANALYZE realmente executa a consulta encapsulada, ele se comporta como essa consulta — e, diferentemente das formas EXPLAIN que não executam — de várias maneiras:
  • Cotas e limites. Ele é contabilizado nas mesmas quotas e está sujeito aos mesmos limits (por exemplo, query_selects, read_rows) que a execução direta da consulta. Fontes isentas de cotas durante o planejamento (como system.one) não são contabilizadas.
  • Transações com falha. Dentro de uma transação que já falhou (ROLLED_BACK), ele é rejeitado com INVALID_TRANSACTION, assim como uma instrução SELECT simples — emita ROLLBACK primeiro.
  • Leituras de streaming. Em uma leitura de streaming (FROM ... STREAM), ele é rejeitado com NOT_IMPLEMENTED, porque esse tipo de leitura nunca termina.
  • Consultas distribuídas. Não há suporte para ele em consultas executadas em modo Distributed.
Exemplo:
Vamos examinar a saída. Primeiro, vamos ver o cabeçalho.
  • Time — tempo total dividido entre as fases de planejamento (isto é, criação do plano + otimização do plano + construção do pipeline) e execução (execução do pipeline).
  • Read — linhas e bytes não comprimidos lidos das tabelas, com a taxa de transferência — os mesmos números que o rodapé padrão da consulta informa como “Processed”.
  • Peak memory — pico de memória usado pela consulta.
Agora vamos examinar as novas linhas que aparecem no plano da consulta.
Linhas e bytes são informados uma vez para todo o passo (a linha I/O). O tempo e o paralelismo são informados por estágio do passo nas linhas indentadas abaixo.
  • rows <in> → <out> — linhas que entraram e saíram do passo; (<selectivity>%) mostra o quanto o passo filtrou (out/in) ou expandiu os dados; fica oculto quando as linhas de entrada são iguais às linhas de saída e quando as linhas de entrada são iguais a 0.
  • <bytes_in> → <bytes_out> — bytes não comprimidos em memória que passam pelo passo (omitido quando ambos são zero).
  • time <t> (<share>%) — tempo de relógio em que o estágio esteve ativo e sua participação no tempo de execução da consulta (isto é, sem o tempo de compilação). Observe que as participações podem somar mais de 100%, porque estágios e passos são executados de forma concorrente.
  • parallelism <avg>/<max> — número médio de threads de CPU trabalhando ao mesmo tempo neste estágio, do máximo que ele poderia usar. Um valor próximo do máximo significa que o estágio foi bem paralelizado; próximo de 1 significa que ele foi executado principalmente de forma serial.
  • Stage (<stage>) — o nome do estágio. Um passo com um único estágio imprime a linha de tempo diretamente, sem um rótulo Stage (...). Passos com vários estágios imprimem uma linha identificada para cada estágio; por exemplo, Aggregating mostra Stage (partial aggregation) e Stage (final aggregation), e um hash join mostra Stage (build) e Stage (probe).
O ClickHouse paraleliza não apenas a execução de tarefas dentro de um passo do plano, mas também a execução dos próprios passos do plano. A métrica parallelism reflete apenas o trabalho deste passo. Outros passos podem ser executados de forma concorrente, portanto esse número não mostra como o paralelismo do passo se compara ao da consulta como um todo.
O número máximo em parallelism é calculado como o valor mínimo entre:
  1. o número total de tarefas dentro do passo do plano;
  2. o número máximo de threads de processamento de consultas definido em max_threads.

​
Etapas de junção

Em uma etapa de junção, EXPLAIN ANALYZE exibe linhas que comparam as estimativas do otimizador de ordem de junção com o que realmente ocorreu (consulte Métricas de junção estimadas versus reais) e linhas de participação para cada lado — Left e Right — seguidas de linhas específicas da implementação da junção. Todos os valores de join_algorithm são contemplados (hash, parallel_hash, grace_hash, partial_merge, full_sorting_merge, parallel_full_sorting_merge, direct), assim como as duas implementações que essa configuração não pode selecionar: uma junção CROSS ou COMMA, qualquer seção ON sem igualdade de chave e o motor de tabela Join. A maioria deles informa ambos os lados; alguns informam apenas o lado que materializam (por exemplo, direct exibe apenas Left:). As linhas de cada lado seguem o mesmo formato:
Para cada lado, EXPLAIN ANALYZE informa:
  • rows estimated <estimated_rows> — a estimativa do otimizador de ordem de junção para as linhas desse lado, exibida para comparação com as rows reais ao lado; no stats quando o otimizador não produz uma estimativa (consulte Métricas de junção estimadas versus reais).
  • rows <rows> — o número total de linhas desse lado que passaram pela junção.
  • matched <matched_rows> — o número de linhas desse lado que encontraram pelo menos uma linha correspondente no outro lado. Isso conta linhas, não chaves: se uma chave ocorrer três vezes no lado direito e houver correspondência, as três linhas da direita serão contadas como correspondentes.
  • match rate <match_rate>% — a porcentagem de linhas desse lado que tiveram correspondência, calculada como 100 * <matched_rows> / <rows>.
  • fanout <fanout> — quantas linhas de saída, em média, cada linha correspondente desse lado produziu.
Um número que não pode ser calculado com exatidão é informado como not collected, em vez de 0. match rate e fanout são derivados de matched; portanto, um lado sem esse valor informa os três como not collected.

​
Métricas de join estimadas vs. reais

Uma etapa de junção traz as estimativas do otimizador de ordem de junção — as mesmas exibidas pelo EXPLAIN PLAN (consulte a seção EXPLAIN PLAN) — e o EXPLAIN ANALYZE imprime cada uma delas ao lado do valor medido:
  • Cost — ambos os valores contabilizam as linhas de saída correspondentes. A estimativa é o custo, para o otimizador, da subárvore da junção: <selectivity> * <left_rows> * <right_rows> mais o custo de suas entradas. O valor real é medido da mesma maneira — as linhas de saída correspondentes desta junção mais o custo real de cada junção abaixo dela que pertença ao mesmo cluster de reordenação.
  • Selectivity — a estimativa é derivada do número de valores distintos das chaves de junção; o valor real é a fração medida do produto cartesiano que chegou à saída: <matched output rows> / (<left rows> * <right rows>), pois é isso que o otimizador tenta estimar.
  • Output rows — o número estimado e real de linhas produzidas pela junção. Quando ambos são diferentes de zero, q-error informa max(estimated / actual, actual / estimated), a medida padrão da qualidade da estimativa de cardinalidade: 1.00 significa uma estimativa perfeita, e um valor alto significa que o otimizador escolheu a ordem das junções com base em uma cardinalidade muito imprecisa.
Uma estimativa que nunca foi feita é informada como no stats — por exemplo, quando a otimização da ordem das junções não foi executada porque query_plan_optimize_join_order_limit é 0. Isso é diferente de not collected, que indica um valor real que a execução não conseguiu medir. Junções com o lado direito pré-preenchido (o motor de tabela Join, junções direct) não passam pelo otimizador de ordem das junções e exibem apenas as linhas de participação. A etapa de junção também exibe as linhas Input (left): e Input (right): com as colunas que cada lado fornece à junção. Para as tabelas do exemplo de junção EXPLAIN PLAN, a etapa de junção de EXPLAIN ANALYZE SELECT * FROM t1 INNER JOIN t2 ON t1.id = t2.id é assim:

​
Fanout

fanout mede a multiplicação de linhas:
Uma junção externa gera uma linha de saída preenchida com NULL para cada linha de um lado preservado que não encontrou correspondência. Essas linhas são subtraídas para não diluírem a razão. Apenas um lado preservado as tem — o lado direito em RIGHT e FULL, e o esquerdo em LEFT e FULL:
  • fanout = 0 — as linhas correspondentes não produziram nenhuma linha de saída, como ocorre em uma junção ANTI: ela gera apenas as linhas que não encontraram correspondência.
  • fanout = 1 — uma junção 1:1 sem duplicações; cada linha correspondente produziu exatamente uma linha de saída.
  • fanout > 1 — uma junção 1:N; chaves duplicadas do outro lado multiplicaram as linhas. Um valor alto nos dois lados ao mesmo tempo é sinal de uma explosão cartesiana não intencional.

​
Quando os números exigem matches = 1

A maioria desses números decorre dos dados que a junção já gera e é informada por um simples EXPLAIN ANALYZE. Os demais exigem uma contabilização que a junção não faria de outra forma e, por isso, só são informados com EXPLAIN ANALYZE matches = 1. Quais são eles depende do algoritmo; na família hash, há dois casos:
  • o lado direito de ALL INNER e ALL LEFT, que exige marcar todas as linhas correspondentes do lado direito;
  • o lado esquerdo de ALL LEFT e ALL FULL, mas somente quando a consulta não seleciona nada da tabela à direita e a seção ON é uma simples igualdade de chave. Caso contrário, a sondagem já registra quais linhas do lado esquerdo tiveram correspondência — seja para materializar as colunas do lado direito ou para avaliar a condição residual — e a contagem é exata sem a opção.
partial_merge precisa disso para o lado direito dos quatro tipos ALL, pelo mesmo motivo. full_sorting_merge e parallel_full_sorting_merge precisam disso para ambos os lados dos tipos ANY. Os tipos ALL não precisam de nada.
A opção fica desativada por padrão porque a contabilização adicional tem custo, e não usá-la reduz a fidelidade da medição. O trabalho é realizado dentro do loop de sondagem e aumenta com o número de linhas de saída. Use matches = 1 quando precisar saber as correspondências exatas encontradas pelas linhas dos lados esquerdo e direito.
matches = 1 não torna todas as combinações passíveis de coleta. Os lados que uma junção pode informar decorrem do que ela já precisa fazer de qualquer forma; portanto, isso depende tanto do algoritmo quanto do tipo e da strictness. Família hash. hash, parallel_hash e grace_hash sempre se comportam da mesma forma: O lado direito não está disponível sempre que a junção mantém apenas uma linha por chave em sua tabela hash, como fazem as junções ANY, SEMI e ANTI: as linhas duplicadas do lado direito nunca são armazenadas e, portanto, não podem ser contadas. O lado esquerdo não está disponível quando a junção suprime a saída de uma linha do lado esquerdo cuja correspondente já foi reivindicada por outra linha desse lado, fazendo com que as linhas emitidas sejam uma subcontagem das linhas com correspondência. Ativar any_join_distinct_right_table_keys muda ANY para a semântica mais antiga RightAny, que emite uma linha por linha do lado esquerdo e, portanto, mantém ambas as contagens. ANY RIGHT e ANY FULL passam a informar ambos os lados, e ANY INNER é reescrito como SEMI LEFT. O motor de tabela Join segue a mesma tabela, usando o tipo e a strictness declarados no mecanismo: Join(ALL, INNER, …) informa ambos os lados, enquanto Join(ANY, LEFT, …) não informa nenhum deles. Algoritmos de merge. full_sorting_merge e parallel_full_sorting_merge aceitam os quatro tipos ALL, ANY INNER, ANY LEFT, ANY RIGHT, ASOF e ASOF LEFT. Eles informam ambos os lados para todos os tipos, exceto ASOF e ASOF LEFT, nos quais o lado direito é not collected, mesmo sem matches = 1 — eles percorrem as duas entradas ordenadas e veem todas as linhas de uma faixa de valores iguais à medida que as consomem, portanto nada precisa ser reconstruído posteriormente. partial_merge aceita ALL INNER, ALL LEFT, ALL RIGHT, ALL FULL, ANY INNER, ANY LEFT e SEMI LEFT. Ele informa ambos os lados para os quatro tipos ALL, sendo o direito com matches = 1; para ANY INNER, ANY LEFT e SEMI LEFT, o lado direito é not collected. direct. Somente o lado esquerdo. O lado direito é um armazenamento de chave-valor que nunca é materializado em linhas e, portanto, não possui nenhuma linha Right:. CROSS, COMMA e um ON constante. Nenhum dos lados, conforme descrito acima. Quando ambos os algoritmos informam um número, os resultados coincidem. Os algoritmos de mesclagem simplesmente têm mais informações; eles não divergem quanto ao que constitui uma correspondência.

​
Linhas específicas do algoritmo

Vejamos as linhas adicionais incluídas por cada implementação de junção. Para as junções hash e parallel_hash e para o motor de tabela Join, uma linha Hash table: descreve a tabela hash criada a partir da tabela à direita:
  • unique keys <unique_keys> — o número de chaves únicas armazenadas na tabela hash durante a fase de compilação.
  • memory <peak_memory> — o pico de memória usado pela tabela hash durante a fase de compilação.
Para a junção grace_hash, a linha Hash table: também informa como a junção se adaptou ao limite de memória, e uma linha Spill: informa se os dados foram gravados em disco:
  • buckets <buckets> — o número de buckets que a junção grace hash teve ao final da execução. Esse número é sempre uma potência de 2.
  • rehashes <rehashes> — quantas vezes o número de buckets precisou ser dobrado para se ajustar ao limite de memória.
  • Spill: — uma flag yes/no que indica se houve spill para disco. Quando houve, left spilled <left_spilled_bytes> e right spilled <right_spilled_bytes> informam os bytes comprimidos gravados em disco dos lados esquerdo (probe) e direito (build); quando não houve spill, a linha é simplesmente Spill: no.
Na junção partial_merge, a linha Right: contém informações adicionais sobre como a tabela da direita foi armazenada em buffer e ordenada, e o tempo de ordenação é exibido nas linhas Stage (build) e Stage (probe):
  • size <right_size> — o tamanho em memória dos blocos da tabela à direita.
  • blocks <right_blocks> — o número de blocos nos quais a tabela à direita foi armazenada em buffer.
  • storage <in-memory|external> — indica se a tabela à direita coube na memória (in-memory) ou precisou ser descarregada em disco (external). Quando é external, um campo adicional spilled <spilled_bytes> informa os bytes comprimidos gravados em disco.
  • sort time <sort_time> — o tempo gasto na ordenação da tabela à direita (no estágio de compilação) e de cada bloco recebido da esquerda (no estágio de sondagem).
  • sort share <sort_share>% — sort time como proporção do tempo de ocupação do próprio estágio (a soma do tempo decorrido de seus processadores), diferentemente da porcentagem de time do estágio, que representa uma proporção do tempo de execução de toda a consulta.
Para a junção full_sorting_merge, são impressas apenas as linhas comuns Left: e Right:. Para a junção direct, é impressa apenas a linha Left:, pois o lado direito é um armazenamento de chave-valor consultado diretamente, em vez de ser materializado em linhas. Para uma junção CROSS ou COMMA, e para qualquer seção ON sem igualdade de chave, uma linha Buffer: descreve como a tabela à direita foi mantida na memória, e uma linha Spill: informa se ela foi descarregada em disco:
  • memory <peak_memory> — o pico de memória ocupado pela tabela da direita armazenada em buffer.
  • compressed <yes|no> — indica se pelo menos um bloco armazenado em buffer foi comprimido; nesse caso, os leitores descompactam todos os blocos armazenados.
  • Spill: — a mesma flag yes/no de grace_hash, com right spilled <right_spilled_bytes> informando os bytes comprimidos gravados em disco.
Ambos os lados informam matched not collected aqui: um predicado constante associa todas as linhas da esquerda a todas as linhas da direita ou a nenhuma delas; portanto, não é possível determinar quais linhas individuais corresponderam. Para uma junção com o motor de tabela Join, ambos os lados são informados, juntamente com a linha Hash table:, que descreve a tabela pré-criada. O lado direito contabiliza as linhas armazenadas no mecanismo, não as linhas de uma compilação específica da consulta.

​
Tempos por processador

Com processors = 1, uma linha extra é impressa abaixo de cada estágio, mostrando a distribuição do tempo decorrido entre os processadores do estágio:
<n> é o número de processadores no estágio. Uma grande diferença entre median e max indica um desequilíbrio de carga entre processadores paralelos.

​
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 WHATIF

Estima o benefício que um skip index hipotético teria em uma consulta SELECT, sem materializar o índice em disco. Defina um ou mais candidatos com CREATE HYPOTHETICAL INDEX e, em seguida, execute EXPLAIN WHATIF SELECT ... para ver, para cada candidato: aplicabilidade, marcas lidas estimadas, bytes estimados e taxa de descarte. Projeções hipotéticas definidas com CREATE HYPOTHETICAL PROJECTION também são listadas como candidatas, mas seu benefício ainda não é estimado: cada uma é informada com status: not_applicable. Uma projeção cuja definição não se aplica mais à tabela — uma coluna removida ou uma mudança de configuração que desabilita os recursos de que ela precisa — é informada com esse motivo. Sintaxe
Configurações
  • empirical — 1 (padrão) executa o índice em memória sobre os grânulos filtrados pela referência para medir a taxa de descarte (um limite superior). 0 ignora esse caminho. De qualquer forma, se empirical não produzir um resultado (por estar desabilitado ou porque o índice não pode ser avaliado em memória), o estimador recorre às estatísticas da coluna e, por fim, a um resumo apenas de aplicabilidade se nenhuma das duas opções estiver disponível.
Saída
  • source — como a estimativa foi gerada.
    • empirical: construiu o índice em memória sobre os grânulos remanescentes após o pruning de referência e contou os grânulos que o índice pularia. Este é um limite superior — veja as limitações em CREATE HYPOTHETICAL INDEX.
    • statistical: derivado de estatísticas de coluna. Usado quando a estimativa empírica está desabilitada (empirical = 0) ou não conseguiu produzir um resultado, e há estatísticas de coluna definidas nas colunas relevantes.
    • applicability_only: o índice é aplicável ao predicado, mas nem a estimativa empírica nem a estatística produziram um resultado (por exemplo, empirical = 0 e nenhuma estatística de coluna definida). Informa skip_ratio: 0.0% como um limite conservador.
  • empirical_reason — por que a estimativa empírica não pôde ser executada. Exibido apenas com empirical_status: unsupported. Por exemplo, um valor diferente de zero para merge_tree_min_rows_for_seek ou merge_tree_min_bytes_for_seek faz com que uma leitura real agrupe intervalos de marcas, algo que a contagem por grânulo não modela; portanto, a estimativa recorre a statistical ou applicability_only.
  • sampled_parts / sampled_marks — <baseline-pruned> / <total in the table>. Mostra que fração da tabela restou após o pruning por PK, partição e índices existentes, ou seja, a entrada para o índice hipotético.
  • est_bytes — uma estimativa dos bytes lidos, derivada do tamanho médio de linha da tabela; por isso, é aproximada e varia conforme o armazenamento e a compressão. A linha de referência aparece apenas quando a consulta lê linhas; a linha de cada candidato, apenas quando a estimativa de bytes da linha de referência é conhecida.
A configuração é escrita inline entre WHATIF e SELECT — não há palavra-chave SETTINGS (isso corresponde à forma como outras variantes de EXPLAIN aceitam suas opções). Se nem índices hipotéticos nem projeções hipotéticas estiverem definidos para a tabela, EXPLAIN WHATIF informa status: not_applicable com uma dica para criar um. Linha combinada (múltiplos candidatos) Quando dois ou mais candidatos são avaliados empiricamente, o EXPLAIN WHATIF acrescenta um bloco extra chamado (combined: idx_a, idx_b, ...) após as linhas por candidato. Ele informa o benefício conjunto de ter todos esses índices ao mesmo tempo: uma leitura real mantém um grânulo apenas se ele sobreviver a cada skip index, portanto a estimativa combinada é a interseção dos grânulos sobreviventes dos candidatos. Seu skip_ratio é, assim, pelo menos tão alto quanto o do melhor candidato individual — índices complementares eliminam mais dados em conjunto, enquanto os redundantes o deixam inalterado. Só contribuem os candidatos com source: empirical, porque a linha combinada é formada pela interseção dos conjuntos de sobrevivência por grânulo de cada um. Os candidatos estimados como statistical ou applicability_only não têm dados por grânulo e são excluídos; consequentemente, o bloco combinado aparece somente quando pelo menos dois candidatos produziram uma estimativa empírica, e é omitido caso contrário (por exemplo, com empirical = 0). Seus campos de estimativa são os mesmos de um bloco empírico por candidato, exceto que elapsed_us é 0 — a estimativa combinada é derivada das varreduras por candidato, não de uma nova varredura. O nome sintético (combined: ...) é apenas um rótulo do relatório e não pode ser usado com force_data_skipping_indices. Exemplo empírico
O minmax hipotético reduziria de 100 marcas para 1 — skip_ratio: 99.0%. (est_bytes é uma estimativa com base no tamanho médio da linha, portanto o valor exato varia.) Exemplo estatístico As estatísticas de coluna vêm desativadas por padrão. Para usar o caminho statistical, primeiro defina-as nas colunas relevantes e aguarde a conclusão da mutação de materialização:
Em seguida, desative o caminho empírico para que o estimador passe a usar as estatísticas de coluna:
O número vem da seletividade das estatísticas da coluna de b < 10 (cerca de 10 linhas em 10000) e é informado como um limite superior de skip_ratio. Não há sampled_parts / sampled_marks — nenhum dado foi lido. Se nenhum dos dois caminhos estiver disponível (por exemplo, empirical = 0 e nenhuma estatística de coluna definida), o estimador informa source: applicability_only e um skip_ratio: 0.0% conservador.

​
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 26 de setembro de 2026