Outras configurações de tabela MergeTree

Estas configurações estão disponíveis em system.merge_tree_settings e são geradas automaticamente a partir do código-fonte do ClickHouse.

adaptive_write_buffer_initial_size

Tamanho inicial de um buffer de escrita adaptativo

add_implicit_sign_column_constraint_for_collapsing_engine

Se true, adiciona uma restrição implícita à coluna sign de uma tabela CollapsingMergeTree ou VersionedCollapsingMergeTree para permitir somente valores válidos (1 e -1).

alter_column_secondary_index_mode

Configura se comandos ALTER que modificam colunas cobertas por índices secundários devem ser permitidos e qual ação deve ser tomada caso sejam permitidos. Por padrão, esses comandos ALTER são permitidos e os índices são reconstruídos. Valores possíveis:

rebuild (padrão): Reconstrói todos os índices secundários afetados pela coluna no comando ALTER.
throw: Impede qualquer ALTER de colunas cobertas por índices secundários explícitos, lançando uma exceção. Índices implícitos não estão sujeitos a essa restrição e serão reconstruídos.
drop: Remove os índices secundários dependentes. As novas partes não terão esses índices, sendo necessário usar MATERIALIZE INDEX para recriá-los.
compatibility: Corresponde ao comportamento original: throw em ALTER ... MODIFY COLUMN e rebuild em ALTER ... UPDATE/DELETE.
ignore: Destinado a uso especializado. Deixa os índices em um estado inconsistente, o que pode permitir resultados de consulta incorretos.

apply_patches_on_merge

Se true, as partes de patch são aplicadas durante as mesclagens

assign_part_uuids

Quando ativado, um identificador único de parte será atribuído a cada nova parte. Antes de ativar, verifique se todas as réplicas são compatíveis com a versão 4 de UUID.

auto_statistics_types

Lista separada por vírgulas dos tipos de estatística a serem calculados automaticamente em todas as colunas adequadas. Tipos de estatística compatíveis: basic, tdigest, countmin, uniq, uniq_v2. O tipo de estatística minmax está obsoleto: ele é um subconjunto de basic, que deve ser usado em seu lugar.

background_task_preferred_step_execution_time_ms

Tempo alvo para a execução de um passo de mesclagem ou mutation. Pode ser excedido se um passo demorar mais

clean_deleted_rows

Configuração obsoleta, sem efeito.

clone_replica_zookeeper_create_get_part_batch_size

Tamanho do lote para solicitações get-part multi-create do ZooKeeper ao clonar uma réplica.

compatibility_allow_sampling_expression_not_in_primary_key

Permite criar uma tabela com uma expressão de amostragem que não esteja na chave primária. Isso é necessário apenas para permitir temporariamente a execução do servidor com tabelas incorretas, por compatibilidade retroativa.

compute_exact_num_defaults_for_sparse_columns

Calcula a contagem exata de valores padrão por coluna durante inserções e mesclagens, em vez da estimativa mais barata por amostragem usada para decidir sobre a serialização esparsa. Necessário para optimize_trivial_count_with_sparsity_filter, que consome o contador num_defaults persistido (colunas Nullable também precisam de nullable_serialization_version = 'allow_sparse'). Deixá-la desabilitada mantém inserções/mesclagens tão rápidas quanto antes; habilitá-la adiciona uma passagem O(rows) por coluna apta à serialização esparsa.

deduplicate_merge_projection_mode

Se é permitido criar projeções para a tabela com MergeTree não clássico, ou seja, que não seja (Replicated, Shared) MergeTree. A opção ignore existe apenas por compatibilidade e pode resultar em respostas incorretas. Caso contrário, se permitido, define qual é a ação ao fazer mesclagem de projeções: drop ou rebuild. Assim, o MergeTree clássico ignora esta configuração. Ela também controla OPTIMIZE DEDUPLICATE, mas tem efeito sobre todos os membros da família MergeTree. Semelhante à opção lightweight_mutation_projection_mode, ela também é em nível de parte. Possíveis valores:

ignore
throw
drop
rebuild

deduplication_hashes_cache_update_wait_ms

Por quanto tempo cada iteração de insert aguarda a atualização do cache em memória deduplication_hashes para uma versão mais recente antes de verificá-lo novamente em busca de blocos já inseridos. O cache espelha o diretório deduplication_hashes no ClickHouse Keeper para que os inserts possam detectar duplicatas sem precisar de uma ida e volta ao Keeper.

default_compression_codec

Especifica o codec de compressão padrão a ser usado caso nenhum tenha sido definido para uma coluna específica na declaração da tabela. Ordem de seleção do codec de compressão para uma coluna:

Codec de compressão definido para a coluna na declaração da tabela
Codec de compressão definido em default_compression_codec (esta configuração)
Codec de compressão padrão definido nas configurações de compression Valor padrão: uma string vazia (não definido).

disco

Nome do disco de armazenamento. Pode ser especificado no lugar da política de armazenamento.

dynamic_serialization_version

Versão de serialização para o tipo de dados Dynamic. Necessária para compatibilidade. Possíveis valores:

v1
v2
v3

enforce_index_structure_match_on_partition_manipulation

Se essa configuração estiver habilitada na tabela de destino de uma consulta de manipulação de partição (ATTACH/MOVE/REPLACE PARTITION), os índices e as projeções deverão ser idênticos entre as tabelas de origem e de destino. Caso contrário, a tabela de destino poderá ter um superconjunto dos índices e das projeções da tabela de origem.

execute_merges_on_single_replica_time_threshold

Quando esta configuração tem um valor maior que zero, apenas uma única réplica inicia a mesclagem imediatamente, e as outras réplicas aguardam por esse período para baixar o resultado em vez de fazer mesclagens localmente. Se a réplica escolhida não concluir a mesclagem nesse período, ocorre o retorno ao comportamento padrão. Valores possíveis:

Qualquer número inteiro positivo.

finished_mutations_to_keep

Quantos registros sobre mutações concluídas devem ser mantidos. Se for zero, mantenha todos eles.

force_read_through_cache_for_merges

Forçar a leitura por meio do cache do sistema de arquivos para mesclagens

initialization_retry_period

Período entre tentativas de inicialização da tabela, em segundos.

kill_threads

Configuração obsoleta, sem efeito.

lightweight_mutation_projection_mode

Por padrão, a exclusão leve DELETE não funciona para tabelas com projeções. Isso ocorre porque linhas em uma projeção podem ser afetadas por uma operação DELETE. Por isso, o valor padrão é throw. No entanto, esta opção pode alterar esse comportamento. Com o valor drop ou rebuild, as exclusões funcionarão com projeções. drop excluirá a projeção, então isso pode ser rápido na consulta atual, já que a projeção é excluída, mas lento em consultas futuras, pois não haverá projeção anexada. rebuild reconstruirá a projeção, o que pode afetar o desempenho da consulta atual, mas pode acelerar consultas futuras. O ponto positivo é que essas opções funcionarão apenas no nível da parte, o que significa que projeções na parte que não forem afetadas permanecerão intactas, em vez de acionar qualquer ação como drop ou rebuild. Valores possíveis:

throw
drop
rebuild

load_existing_rows_count_for_old_parts

Se estiver habilitada junto com exclude_deleted_rows_for_part_size_in_merge, a contagem de linhas excluídas das partes de dados existentes será calculada durante a inicialização da tabela. Observe que isso pode tornar mais lento o carregamento da tabela na inicialização. Valores possíveis:

true
false

Veja também

configuração exclude_deleted_rows_for_part_size_in_merge

lock_acquire_timeout_for_background_operations

Para operações em segundo plano, como mesclagens, mutações etc. Define quantos segundos esperar antes de falhar ao adquirir bloqueios de tabela.

mutation_workload

Usado para controlar como os recursos são utilizados e compartilhados entre mutações e outros workloads. O valor especificado é usado como valor da configuração workload para as mutações em segundo plano desta tabela. Se não for especificado (string vazia), a configuração do servidor mutation_workload será usada. Veja também

Workload Scheduling

non_replicated_deduplication_window

O número dos blocos inseridos mais recentemente na tabela MergeTree não replicada cujas somas de hash são armazenadas para verificar duplicatas. Valores possíveis:

Qualquer inteiro positivo.
0 (desabilita a desduplicação).

É usado um mecanismo de desduplicação semelhante ao das tabelas replicadas (consulte a configuração replicated_deduplication_window): a soma de hash de desduplicação abrange todo o bloco inserido. As somas de hash são gravadas em um arquivo local em disco, em vez de no ClickHouse Keeper.

notify_newest_block_number

Notifica o número do bloco mais recente ao SharedJoin ou ao SharedSet. Somente no ClickHouse Cloud.

nullable_serialization_version

Controla o método de serialização usado para colunas Nullable(T). Valores possíveis:

basic — Usa a serialização padrão para Nullable(T).
allow_sparse — Permite que Nullable(T) use codificação esparsa.

object_serialization_version

Versão de serialização para o tipo de dados JSON. Necessária para compatibilidade. Valores possíveis:

v1
v2
v3

Somente a versão v3 oferece suporte à alteração da versão de serialização dos dados compartilhados.

old_parts_lifetime

O tempo (em segundos) de armazenamento de partes inativas para proteger contra perda de dados durante reinicializações inesperadas do servidor. Valores possíveis:

Qualquer inteiro positivo.

Após mesclar várias partes em uma nova parte, o ClickHouse marca as partes originais como inativas e só as exclui após old_parts_lifetime segundos. As partes inativas são removidas se não estiverem sendo usadas por queries em execução, ou seja, se o refcount da parte for 1. fsync não é chamado para novas partes, portanto, por algum tempo, elas existem apenas na RAM do servidor (cache do SO). Se o servidor reiniciar inesperadamente, essas novas partes podem ser perdidas ou corrompidas. Para proteger os dados, as partes inativas não são excluídas imediatamente. Durante a inicialização, o ClickHouse verifica a integridade das partes. Se a parte mesclada estiver corrompida, o ClickHouse devolve as partes inativas à lista de partes ativas e depois as mescla novamente. Em seguida, a parte corrompida é renomeada (o prefixo broken_ é adicionado) e movida para a pasta detached. Se a parte mesclada não estiver corrompida, então as partes inativas originais são renomeadas (o prefixo ignored_ é adicionado) e movidas para a pasta detached. O valor padrão de dirty_expire_centisecs (uma configuração do kernel Linux) é de 30 segundos (o tempo máximo em que os dados gravados ficam armazenados apenas na RAM), mas, sob carga intensa no sistema de disco, os dados podem ser gravados bem mais tarde. Experimentalmente, foi escolhido um valor de 480 segundos para old_parts_lifetime, período durante o qual se garante que uma nova parte seja gravada em disco.

optimize_row_order

Controla se a ordem das linhas deve ser otimizada durante inserções para melhorar a compressibilidade da parte da tabela recém-inserida. Só tem efeito em tabelas comuns com o motor MergeTree. Não tem efeito em tabelas especializadas do motor MergeTree (por exemplo, CollapsingMergeTree). As tabelas MergeTree são comprimidas (opcionalmente) usando codecs de compressão. Codecs de compressão genéricos, como LZ4 e ZSTD, atingem taxas máximas de compressão quando os dados apresentam padrões. Sequências longas de um mesmo valor normalmente são muito bem comprimidas. Se esta configuração estiver habilitada, o ClickHouse tenta armazenar os dados nas partes recém-inseridas em uma ordem de linhas que minimize o número de sequências de valores iguais nas colunas da nova parte da tabela. Em outras palavras, um número pequeno de sequências de valores iguais significa que as sequências individuais são longas e comprimem bem. Encontrar a ordem ideal das linhas é computacionalmente inviável (NP-hard). Por isso, o ClickHouse usa uma heurística para encontrar rapidamente uma ordem de linhas que ainda assim melhora as taxas de compressão em relação à ordem original das linhas. Se estiver habilitada, as operações de insert incorrem em custos adicionais de CPU para analisar e otimizar a ordem das linhas dos novos dados. Espera-se que INSERTs levem de 30% a 50% mais tempo, dependendo das características dos dados. As taxas de compressão de LZ4 ou ZSTD melhoram, em média, de 20% a 40%. Essa configuração funciona melhor para tabelas sem chave primária ou com chave primária de baixa cardinalidade, isto é, uma tabela com poucos valores distintos de chave primária. Não se espera que chaves primárias de alta cardinalidade, por exemplo, envolvendo colunas de timestamp do tipo DateTime64, se beneficiem dessa configuração.

packed_skip_index_max_bytes

Limite (em bytes serializados em disco, ou seja, após a compressão e o encadeamento de hash do subfluxo) abaixo do qual um subfluxo de índice de salto é empacotado em um único arquivo skp_idx.packed por parte, em vez de ser gravado como um arquivo separado skp_idx_<name>.idx2 / .mrk2. Subfluxos maiores que isso permanecem no layout legado por arquivo. A decisão é tomada independentemente para cada subfluxo no momento da gravação, portanto uma única parte pode ter índices pequenos (por exemplo, minmax) empacotados e grandes (por exemplo, um bloom_filter pesado) em arquivos separados. Defina 0 para desabilitar totalmente o empacotamento (padrão). Cada subfluxo de índice de salto consiste, na prática, em um arquivo de dados e um arquivo de marcas; ambos ficam em buffer na memória até o limite antes que a decisão de spill seja tomada. Portanto, o pico de memória durante a gravação escala com 2 * packed_skip_index_max_bytes * (number of substreams that stay below the threshold). Índices de texto completo não são compatíveis com esta configuração e nunca são empacotados. O empacotamento reduz a pressão sobre os inodes quando muitos índices de salto são definidos em uma tabela (por exemplo, com add_minmax_index_for_numeric_columns). O formato em disco é autodescritivo: os leitores detectam skp_idx.packed e atendem os subfluxos empacotados dentro dele de forma transparente. Alterar esta configuração afeta apenas as partes gravadas a partir daí; as partes existentes mantêm o layout que tinham no momento da gravação.

part_minmax_index_columns

Seleciona quais colunas o índice min-max de cada parte abrange. Cada valor habilita um grupo adicional de colunas em relação ao anterior. Valores possíveis:

partition_key_only — somente as colunas da chave de partição são rastreadas.
with_block_number_offset — colunas da chave de partição, além das colunas virtuais persistidas _block_number e _block_offset. Permite a poda em nível de parte com base nessas colunas.

propagate_types_serialization_versions_to_nested_types

Se true, versões de serialização como string_serialization_version serão propagadas para dentro de tipos aninhados como Array/Map/Nullable/JSON/etc. Se desabilitado, a versão de serialização terá efeito apenas nas colunas de nível superior desse tipo e Tuple el

ratio_of_defaults_for_sparse_serialization

Razão mínima entre o número de valores default e o número total de valores em uma coluna. Definir esse valor faz com que a coluna seja armazenada usando serializações esparsas. Se uma coluna for esparsa (contiver principalmente zeros), o ClickHouse pode codificá-la em um formato esparso e otimizar automaticamente os cálculos — os dados não precisam de descompressão completa durante as queries. Para habilitar essa serialização esparsa, defina a configuração ratio_of_defaults_for_sparse_serialization com um valor menor que 1.0. Se o valor for maior ou igual a 1.0, as colunas sempre serão gravadas usando a serialização Full normal. Valores possíveis:

Float entre 0 e 1 para habilitar a serialização esparsa
1.0 (ou maior) se você não quiser usar serialização esparsa

Exemplo Observe que a coluna s na tabela a seguir é uma string vazia em 95% das linhas. Em my_regular_table, não usamos serialização esparsa, e em my_sparse_table, definimos ratio_of_defaults_for_sparse_serialization como 0.95:

CREATE TABLE my_regular_table
(
`id` UInt64,
`s` String
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO my_regular_table
SELECT
number AS id,
number % 20 = 0 ? toString(number): '' AS s
FROM
numbers(10000000);

CREATE TABLE my_sparse_table
(
`id` UInt64,
`s` String
)
ENGINE = MergeTree
ORDER BY id
SETTINGS ratio_of_defaults_for_sparse_serialization = 0.95;

INSERT INTO my_sparse_table
SELECT
number,
number % 20 = 0 ? toString(number): ''
FROM
numbers(10000000);

Observe que a coluna s em my_sparse_table ocupa menos espaço em disco:

SELECT table, name, data_compressed_bytes, data_uncompressed_bytes FROM system.columns
WHERE table LIKE 'my_%_table';

┌─table────────────┬─name─┬─data_compressed_bytes─┬─data_uncompressed_bytes─┐
│ my_regular_table │ id   │              37790741 │                75488328 │
│ my_regular_table │ s    │               2451377 │                12683106 │
│ my_sparse_table  │ id   │              37790741 │                75488328 │
│ my_sparse_table  │ s    │               2283454 │                 9855751 │
└──────────────────┴──────┴───────────────────────┴─────────────────────────┘

Você pode verificar se uma coluna está usando a codificação esparsa consultando a coluna serialization_kind da tabela system.parts_columns:

SELECT column, serialization_kind FROM system.parts_columns
WHERE table LIKE 'my_sparse_table';

Você pode ver quais partes de s foram armazenadas com a serialização esparsa:

┌─column─┬─serialization_kind─┐
│ id     │ Default            │
│ s      │ Default            │
│ id     │ Default            │
│ s      │ Default            │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
└────────┴────────────────────┘

reduce_blocking_parts_sleep_ms

Disponível apenas no ClickHouse Cloud. Tempo mínimo de espera antes de tentar reduzir novamente as partes que causam bloqueio após nenhum intervalo ter sido removido/substituído. Uma configuração menor acionará tarefas em background_schedule_pool com frequência, o que resultará em um grande volume de solicitações ao ZooKeeper em clusters de grande escala

replace_long_file_name_to_hash

Se o nome do arquivo da coluna for muito longo (mais de ‘max_file_name_length’ bytes), substitua-o por SipHash128

replicated_can_become_leader

Se true, as réplicas de tabelas replicadas neste nó tentarão assumir a liderança. Valores possíveis:

true
false

search_orphaned_parts_disks

O ClickHouse varre todos os disks em busca de partes órfãs após qualquer ATTACH ou CREATE de tabela, para evitar que partes de dados em disks indefinidos (não incluídos na política) passem despercebidas. As partes órfãs se originam de uma reconfiguração de armazenamento potencialmente insegura, por exemplo, quando um disk é excluído da política de armazenamento. Essa configuração limita o escopo dos disks a serem pesquisados com base nas características deles. Valores possíveis:

any - o escopo não é limitado.
local - o escopo é limitado aos disks locais.
none - escopo vazio, não pesquisar

serialization_info_version

Versão das informações de serialização usada ao gravar serialization.json. Essa configuração é necessária para garantir compatibilidade durante upgrades do cluster. Valores possíveis:

basic - Formato básico.
with_types - Formato com o campo adicional types_serialization_versions, permitindo versões de serialização por tipo. Isso faz com que configurações como string_serialization_version passem a ter efeito.

Durante atualizações graduais, defina esta opção como basic para que os novos servidores produzam partes de dados compatíveis com os servidores antigos. Após a conclusão do upgrade, mude para WITH_TYPES para habilitar versões de serialização por tipo.

share_nested_offsets

Quando habilitada (padrão), colunas Array com nomes pontilhados que compartilham um prefixo em comum (por exemplo, n.a e n.b) são tratadas como parte de uma estrutura Nested: compartilham um único arquivo de offsets em disco (por exemplo, n.size0), e é verificado durante o INSERT se seus tamanhos de array são iguais. Quando desabilitada, cada coluna Array recebe seu próprio arquivo de offset independente, nomes pontilhados não têm semântica especial, e uma coluna escalar pode coexistir com colunas Array pontilhadas que compartilham o mesmo prefixo (por exemplo, n UInt32 ao lado de n.a Array(String)). Essa configuração é imutável após a criação da tabela.

simultaneous_parts_removal_limit

Se houver muitas partes desatualizadas, a thread de limpeza tentará excluir até simultaneous_parts_removal_limit partes em uma única iteração. simultaneous_parts_removal_limit definido como 0 significa sem limite.

storage_policy

Nome da política de armazenamento em disco

string_serialization_version

Controla o formato de serialização de colunas String de nível superior. Esta configuração só tem efeito quando serialization_info_version está definido como “with_types”. Quando definido como with_size_stream, as colunas String de nível superior são serializadas com uma subcoluna .size separada para armazenar os comprimentos das strings, em vez de embuti-los inline. Isso permite subcolunas .size reais e pode melhorar a eficiência da compressão. Tipos String aninhados (por exemplo, dentro de Nullable, LowCardinality, Array ou Map) não são afetados, exceto quando aparecem em uma Tuple. Possíveis valores:

single_stream — Use o formato de serialização padrão com tamanhos inline.
with_size_stream — Use um fluxo separado de tamanhos para colunas String de nível superior.

temporary_directories_lifetime

Por quantos segundos os diretórios tmp_ devem ser mantidos. Você não deve reduzir esse valor, pois mesclagens e mutações podem não conseguir funcionar com um valor baixo dessa configuração.

try_fetch_recompressed_part_timeout

Tempo limite (em segundos) antes de iniciar a mesclagem com recompressão. Durante esse período, o ClickHouse tenta obter a parte recomprimida da réplica à qual foi atribuída essa mesclagem com recompressão. Na maioria dos casos, a recompressão é lenta, por isso a mesclagem com recompressão não é iniciada antes desse tempo limite, e o sistema tenta obter a parte recomprimida da réplica à qual foi atribuída essa mesclagem com recompressão. Valores possíveis:

Qualquer inteiro positivo.

ttl_only_drop_parts

Controla se as partes de dados são removidas por completo em tabelas MergeTree quando todas as linhas dessa parte expiraram de acordo com suas configurações de TTL. Quando ttl_only_drop_parts está desabilitado (por padrão), somente as linhas que expiraram com base em suas configurações de TTL são removidas. Quando ttl_only_drop_parts está habilitado, a parte inteira é removida se todas as linhas dessa parte tiverem expirado de acordo com suas configurações de TTL.

wait_for_unique_parts_send_before_shutdown_ms

Antes do desligamento, a tabela aguardará o tempo necessário para que partes únicas (que existem apenas na réplica atual) sejam obtidas por outras réplicas (0 significa desabilitado).

zookeeper_session_expiration_check_period

Período de verificação da expiração da sessão do ZooKeeper, em segundos. Valores possíveis:

Qualquer número inteiro positivo.

Última modificação em 24 de julho de 2026

Configurações de formatoConfigurações que controlam os formatos de entrada e saída.

​adaptive_write_buffer_initial_size

​add_implicit_sign_column_constraint_for_collapsing_engine

​alter_column_secondary_index_mode

​apply_patches_on_merge

​assign_part_uuids

​auto_statistics_types

​background_task_preferred_step_execution_time_ms

​clean_deleted_rows

​clone_replica_zookeeper_create_get_part_batch_size

​compatibility_allow_sampling_expression_not_in_primary_key

​compute_exact_num_defaults_for_sparse_columns

​deduplicate_merge_projection_mode

​deduplication_hashes_cache_update_wait_ms

​default_compression_codec

​disco

​dynamic_serialization_version

​enforce_index_structure_match_on_partition_manipulation

​execute_merges_on_single_replica_time_threshold

​finished_mutations_to_keep

​force_read_through_cache_for_merges

​initialization_retry_period

​kill_threads

​lightweight_mutation_projection_mode

​load_existing_rows_count_for_old_parts

​lock_acquire_timeout_for_background_operations

​mutation_workload

​non_replicated_deduplication_window

​notify_newest_block_number

​nullable_serialization_version

​object_serialization_version

​old_parts_lifetime

​optimize_row_order

​packed_skip_index_max_bytes

​part_minmax_index_columns

​propagate_types_serialization_versions_to_nested_types

​ratio_of_defaults_for_sparse_serialization

​reduce_blocking_parts_sleep_ms

​replace_long_file_name_to_hash

​replicated_can_become_leader

​search_orphaned_parts_disks

​serialization_info_version

​share_nested_offsets

​simultaneous_parts_removal_limit

​storage_policy

​string_serialization_version

​temporary_directories_lifetime

​try_fetch_recompressed_part_timeout

​ttl_only_drop_parts

​wait_for_unique_parts_send_before_shutdown_ms

​zookeeper_session_expiration_check_period