Skip to main content
Essas configurações estão disponíveis em system.settings e são geradas automaticamente com base no código-fonte.

​
join_algorithm

Especifica qual algoritmo de JOIN é usado. Vários algoritmos podem ser especificados, e um deles será escolhido para uma consulta específica com base em kind/strictness e no motor de tabela. A maioria dos algoritmos afeta uma consulta apenas quando é selecionada para ela. Alguns, no entanto, alteram o planejamento apenas por estarem listados — mesmo como uma alternativa de menor prioridade que não é selecionada ao final — porque a decisão é tomada antes da escolha do algoritmo. Há dois efeitos desse tipo:
  • A inferência de tipo da chave de junção se torna mais restritiva (uma junção merge não pode unir chaves de tipos diferentes, por exemplo, String e Nullable(String)). Isso pode alterar os tipos de resultado das colunas USING e pode fazer com que uma junção com uma tabela do mecanismo Join falhe com TYPE_MISMATCH. Acionado por full_sorting_merge e parallel_full_sorting_merge.
  • ORDER BY ... LIMIT no lado preservado de uma junção recebe uma ordenação explícita em vez de uma leitura na ordem da chave primária, pois presume-se que a junção interrompa a leitura ordenada (uma junção merge insere sua própria ordenação antes da junção; uma partial merge join reordena os blocos da esquerda; uma junção que pode produzir blocos atrasados também não propaga a leitura ordenada). O resultado é o mesmo, mas o plano é menos eficiente. Acionado por full_sorting_merge, parallel_full_sorting_merge, partial_merge, prefer_partial_merge, grace_hash e auto, e também por um valor diferente de zero em max_bytes_before_external_join / max_bytes_ratio_before_external_join.
Ambos se aplicam mesmo quando a consulta acaba sendo executada com hash ou outro algoritmo. Se isso for indesejável, não liste os algoritmos acima em join_algorithm para as consultas afetadas. Valores possíveis:
  • grace_hash
Grace hash join é usado. O Grace hash oferece uma opção de algoritmo que permite executar junções complexas com bom desempenho, limitando o uso de memória. A primeira fase de uma grace join lê a tabela da direita e a divide em N buckets, dependendo do valor de hash das colunas-chave (inicialmente, N é grace_hash_join_initial_buckets). Isso é feito de forma a garantir que cada bucket possa ser processado de maneira independente. As linhas do primeiro bucket são adicionadas a uma tabela hash em memória, enquanto as demais são salvas em disco. Se a tabela hash crescer além do limite de memória (por exemplo, conforme definido por max_bytes_in_join), o número de buckets será aumentado, assim como o bucket atribuído a cada linha. Todas as linhas que não pertencem ao bucket atual são descarregadas e reatribuídas. Oferece suporte a INNER/LEFT/RIGHT/FULL ALL/ANY JOIN.
  • hash
O algoritmo hash join é usado. É a implementação mais genérica, compatível com todas as combinações de kind e strictness e com várias chaves de junção combinadas com OR na seção JOIN ON. Ao usar o algoritmo hash, a parte direita de JOIN é carregada na RAM.
  • parallel_hash
Uma variação de hash join que divide os dados em buckets e constrói simultaneamente várias tabelas hash em vez de apenas uma, para acelerar esse processo. Ao usar o algoritmo parallel_hash, a parte direita de JOIN é carregada na RAM.
  • partial_merge
Uma variação do algoritmo sort-merge, em que apenas a tabela da direita é totalmente ordenada. RIGHT JOIN e FULL JOIN têm suporte apenas com strictness ALL (SEMI, ANTI, ANY e ASOF não têm suporte). Ao usar o algoritmo partial_merge, o ClickHouse ordena os dados e os grava em disco. O algoritmo partial_merge no ClickHouse difere ligeiramente da implementação clássica. Primeiro, o ClickHouse ordena a tabela da direita pelas chaves de junção em blocos e cria um índice min-max para os blocos ordenados. Em seguida, ordena partes da tabela da esquerda pela join key e faz a junção com a tabela da direita. O índice min-max também é usado para ignorar blocos desnecessários da tabela da direita.
  • direct
O algoritmo direct (também conhecido como nested loop) realiza um lookup na tabela da direita usando as linhas da tabela da esquerda como chaves. É compatível com armazenamentos especiais, como tabelas Dicionário, EmbeddedRocksDB e MergeTree. Para tabelas MergeTree, o algoritmo envia filtros de chave de junção diretamente para a camada de armazenamento. Isso pode ser mais eficiente quando a chave pode usar o índice de chave primária da tabela para lookups; caso contrário, ele executa varreduras completas na tabela da direita para cada bloco da tabela da esquerda. Oferece suporte a junções INNER e LEFT e apenas a chaves de junção de igualdade de uma única coluna, sem outras condições.
  • auto
Quando definido como auto, hash join é tentado primeiro, e o algoritmo é alterado dinamicamente para outro algoritmo se o limite de memória for excedido.
  • full_sorting_merge
Algoritmo sort-merge com ordenação completa das tabelas unidas antes da junção.
  • ie_join
O algoritmo IEJoin baseado em ordenação para um JOIN cuja seção ON tem duas comparações de desigualdade (<, <=, >, >=) entre expressões das tabelas unidas. Oferece suporte a ALL INNER/LEFT/RIGHT/FULL JOIN e SEMI/ANTI LEFT/RIGHT JOIN. A posição na lista define a prioridade: listado após outros algoritmos, IEJoin é usado somente quando eles não se aplicam (a seção ON não tem condições de igualdade); listado primeiro, ele é usado sempre que a seção ON tiver duas condições de desigualdade. As condições restantes (incluindo igualdades) são aplicadas como filtro sobre o resultado da junção para ALL INNER JOIN e avaliadas dentro do operador como uma condição residual que afeta a correspondência para os outros tipos. Sem ie_join na lista, um INNER JOIN apenas com condições de desigualdade é executado como um CROSS JOIN com um filtro, e os outros tipos não têm suporte. Ambas as entradas são acumuladas na memória antes da junção: max_rows_in_join e max_bytes_in_join limitam juntas a entrada acumulada de ambos os lados (não apenas do lado direito), com a ação em caso de overflow definida por join_overflow_mode; os índices de ordenação que o operador cria sobre a entrada acumulada não são contabilizados no limite. O próprio operador de junção é executado em uma única thread; apenas as ordenações das entradas anteriores à junção são paralelizadas.
  • parallel_full_sorting_merge
Igual a full_sorting_merge, mas as junções de igualdade compatíveis com hash são divididas pelo hash das chaves de junção em junções merge independentes por shard que são executadas em paralelo (até max_threads), em vez de uma única junção merge. Isso mantém o baixo uso de memória por streaming de uma junção merge enquanto usa todas as threads, e o resultado não é ordenado. O particionamento por hash usando as chaves de junção é aplicado somente a junções simples de igualdade em tipos de chave cujo hash corresponde à comparação da junção merge, e somente quando nenhum dos lados já está ordenado. Ele é ignorado nestes casos:
  • Junções ASOF e tipos de chave de ponto flutuante / JSON / Object / Dynamic: seus hashes não são consistentes com a comparação da junção merge, portanto chaves iguais poderiam acabar em shards diferentes.
  • Lados que já estão ordenados (uma leitura MergeTree em ordem ou qualquer entrada pré-ordenada): uma dispersão que preserva a ordem nas junções merge por shard pode causar deadlock no pipeline. A leitura em ordem e sua otimização read_in_order_use_virtual_row são mantidas.
  • Enquanto o iniciador cria um plano distribuído (make_distributed_plan), porque a ordenação dispersa não é serializável para execução remota. O plano local de fragmento único e os fragmentos por worker são reotimizados com essa configuração desativada, portanto ainda podem ser divididos em shards.
Ignorá-lo desativa apenas essa reescrita, não o paralelismo em geral: a junção é executada como uma única full_sorting_merge, e os lados MergeTree lidos em ordem ainda podem ser divididos na origem por intervalos de chave primária (que ordenam pela mesma comparação usada pela junção, portanto chaves iguais permanecem juntas) quando query_plan_join_shard_by_pk_ranges está habilitado.
  • prefer_partial_merge
O ClickHouse sempre tenta usar partial_merge join, se possível; caso contrário, usa hash. Descontinuado; é o mesmo que partial_merge,hash.
  • default (descontinuado)
Valor legado; não use mais. O mesmo que direct,hash, ou seja, tente usar direct join e hash join (nessa ordem).

​
join_any_take_last_row

Altera o comportamento das operações JOIN com strictness ANY quando a tabela da direita tem mais de uma linha correspondente para uma chave.
Essa configuração se aplica a tabelas com o motor Join e a algoritmos de join baseados em hash.Se um join for executado em paralelo, a ordem das linhas pode ser não determinística. Isso significa que join_any_take_last_row = 1 pode retornar uma linha não determinística em consultas ANY JOIN.
Valores possíveis:
  • 0 — Se a tabela da direita tiver mais de uma linha correspondente, apenas a primeira encontrada será combinada.
  • 1 — Se a tabela da direita tiver mais de uma linha correspondente, apenas a última encontrada será combinada.
Veja também:

​
join_default_strictness

Define a strictness padrão das cláusulas JOIN. Valores possíveis:
  • ALL — Se a tabela da direita tiver várias linhas correspondentes, o ClickHouse cria um produto cartesiano com as linhas correspondentes. Esse é o comportamento normal de JOIN no SQL padrão.
  • ANY — Se a tabela da direita tiver várias linhas correspondentes, somente a primeira encontrada é combinada. Se a tabela da direita tiver apenas uma linha correspondente, os resultados de ANY e ALL serão os mesmos.
  • ASOF — Para junção de sequências com correspondência incerta.
  • Empty string — Se ALL ou ANY não for especificado na consulta, o ClickHouse lança uma exceção.

​
join_on_disk_max_files_to_merge

Limita o número de arquivos permitidos para a ordenação paralela em operações MergeJoin quando são executadas em disco. Quanto maior o valor da configuração, mais RAM é usada e menos E/S de disco é necessária. Valores possíveis:
  • Qualquer número inteiro positivo, a partir de 2.

​
join_output_by_rowlist_perkey_rows_threshold

O limite inferior da média de linhas por chave na tabela à direita para determinar se a saída deve ser feita por lista de linhas em hash join.

​
join_overflow_mode

Define qual ação o ClickHouse executa quando um JOIN atinge qualquer um dos seguintes limites: Essa configuração só é considerada para os valores hash, parallel_hash e ie_join de join_algorithm. Outros algoritmos (por exemplo, partial_merge, grace_hash, auto) lidam com esses limites de outra forma — fazendo spill para disco, reparticionando ou mudando de estratégia — veja join_algorithm. Valores possíveis:
  • THROW — o ClickHouse lança uma exceção e interrompe a consulta.
  • BREAK — o ClickHouse interrompe a consulta e não lança uma exceção.
Valor padrão: THROW. Veja também

​
join_use_nulls

Define o comportamento de JOIN. Ao combinar tabelas, células vazias podem aparecer. O ClickHouse as preenche de forma diferente com base nessa configuração. Valores possíveis:
  • 0 — As células vazias são preenchidas com o valor padrão do tipo de campo correspondente.
  • 1 — JOIN se comporta da mesma forma que no SQL padrão. O tipo do campo correspondente é convertido para Nullable, e as células vazias são preenchidas com NULL.
Última modificação em 14 de agosto de 2026