Outras configurações de sessão - ClickHouse Documentation

Essas configurações estão disponíveis em system.settings e são autogeradas a partir do código-fonte.

add_http_cors_header

Grava o cabeçalho HTTP CORS.

analyze_index_with_space_filling_curves

Se uma tabela tiver uma curva de preenchimento espacial em seu índice, por exemplo, ORDER BY mortonEncode(x, y) ou ORDER BY hilbertEncode(x, y), e a consulta tiver condições sobre seus argumentos, por exemplo, x >= 10 AND x <= 20 AND y >= 20 AND y <= 30, use a curva de preenchimento espacial para análise de índice.

analyzer_inline_views

Quando habilitado, o analisador substitui visões comuns (não materializadas e não parametrizadas) por suas subconsultas de definição, permitindo otimizações que atravessam essas fronteiras, como pushdown de predicados e poda de colunas.

any_join_distinct_right_table_keys

Habilita o comportamento legado do servidor ClickHouse em operações ANY INNER|LEFT JOIN.

Use esta configuração apenas para compatibilidade retroativa se seus casos de uso dependerem do comportamento legado de JOIN.

Quando o comportamento legado está habilitado:

Os resultados das operações t1 ANY LEFT JOIN t2 e t2 ANY RIGHT JOIN t1 não são iguais porque o ClickHouse usa uma lógica de mapeamento de chaves entre as tabelas, da esquerda para a direita, de muitos para um.
Os resultados das operações ANY INNER JOIN contêm todas as linhas da tabela à esquerda, assim como as operações SEMI LEFT JOIN.

Quando o comportamento legado está desabilitado:

Os resultados das operações t1 ANY LEFT JOIN t2 e t2 ANY RIGHT JOIN t1 são iguais porque o ClickHouse usa uma lógica que fornece mapeamento de chaves de um para muitos em operações ANY RIGHT JOIN.
Os resultados das operações ANY INNER JOIN contêm uma linha por chave de ambas as tabelas, à esquerda e à direita.

Valores possíveis:

0 — O comportamento legado está desabilitado.
1 — O comportamento legado está habilitado.

Veja também:

JOIN strictness

archive_adaptive_buffer_max_size_bytes

Limita o tamanho máximo do buffer adaptativo usado ao gravar em arquivos de arquivamento (por exemplo, arquivos tar

arrow_flight_request_descriptor_type

Tipo de descritor a ser usado nas requisições do Arrow Flight. ‘path’ envia o nome do conjunto de dados como um descritor de caminho. ‘command’ envia uma consulta SQL como um descritor de comando (necessário para o Dremio). Valores possíveis:

‘path’ — Usa FlightDescriptor::Path (padrão, funciona com a maioria dos servidores Arrow Flight)
‘command’ — Usa FlightDescriptor::Command com uma consulta SELECT (necessário para o Dremio)

backup_slow_all_threads_after_retryable_s3_error

Quando definido como true, todas as threads que executam solicitações ao S3 para o mesmo endpoint de backup ficam mais lentas depois que uma única solicitação ao S3 encontra um erro S3 passível de nova tentativa, como ‘Slow Down’. Quando definido como false, cada thread lida com o backoff das solicitações ao S3 independentemente das demais.

cache_warmer_threads

Só tem efeito no ClickHouse Cloud. Número de threads de segundo plano para baixar especulativamente novas partes de dados para o cache do sistema de arquivos quando cache_populated_by_fetch está habilitado. Zero para desabilitar.

calculate_text_stack_trace

Calcula o stack trace em texto em caso de exceções durante a execução da consulta. Esse é o padrão. Requer buscas de símbolos que podem deixar os testes de fuzzing mais lentos quando uma grande quantidade de consultas incorretas é executada. Em condições normais, você não deve desabilitar esta opção.

cancel_http_readonly_queries_on_client_close

Cancela queries HTTP em modo somente leitura (por exemplo, SELECT) quando o cliente fecha a conexão sem aguardar a resposta. Valor padrão no Cloud: 1.

checksum_on_read

Valida checksums durante a leitura. Ela vem habilitada por padrão e deve estar sempre habilitada em produção. Não se espera nenhum benefício ao desabilitar essa configuração. Ela só deve ser usada para experimentos e benchmarks. A configuração se aplica apenas a tabelas da família MergeTree. Checksums são sempre validados para outros motores de tabela e ao receber dados pela rede.

connection_pool_max_wait_ms

O tempo de espera, em milissegundos, por uma conexão quando o pool de conexões está cheio. Valores possíveis:

Inteiro positivo.
0 — Tempo limite infinito.

connections_with_failover_max_tries

O número máximo de tentativas de conexão com cada réplica para o engine de tabela Distributed.

convert_query_to_cnf

Quando definido como true, uma consulta SELECT será convertida para a forma normal conjuntiva (CNF). Há cenários em que reescrever uma consulta em CNF pode fazer com que ela seja executada mais rapidamente (veja esta issue no Github para uma explicação). Por exemplo, observe como a consulta SELECT a seguir não é modificada (comportamento padrão):

EXPLAIN SYNTAX
SELECT *
FROM
(
    SELECT number AS x
    FROM numbers(20)
) AS a
WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))
SETTINGS convert_query_to_cnf = false;

O resultado é:

┌─explain────────────────────────────────────────────────────────┐
│ SELECT x                                                       │
│ FROM                                                           │
│ (                                                              │
│     SELECT number AS x                                         │
│     FROM numbers(20)                                           │
│     WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15)) │
│ ) AS a                                                         │
│ WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))     │
│ SETTINGS convert_query_to_cnf = 0                              │
└────────────────────────────────────────────────────────────────┘

Vamos definir convert_query_to_cnf como true e ver o que muda:

EXPLAIN SYNTAX
SELECT *
FROM
(
    SELECT number AS x
    FROM numbers(20)
) AS a
WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))
SETTINGS convert_query_to_cnf = true;

Observe que a cláusula WHERE é reescrita em CNF, mas o conjunto de resultados é o mesmo - a lógica booleana permanece inalterada:

┌─explain───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ SELECT x                                                                                                              │
│ FROM                                                                                                                  │
│ (                                                                                                                     │
│     SELECT number AS x                                                                                                │
│     FROM numbers(20)                                                                                                  │
│     WHERE ((x <= 15) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x >= 10) OR (x >= 1)) │
│ ) AS a                                                                                                                │
│ WHERE ((x >= 10) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x <= 15) OR (x <= 5))     │
│ SETTINGS convert_query_to_cnf = 1                                                                                     │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Valores possíveis: true, false

count_matches_stop_at_empty_match

Interrompe a contagem assim que um padrão corresponder a zero caracteres na função countMatches.

cross_to_inner_join_rewrite

Use INNER JOIN em vez de junção por vírgula/CROSS JOIN se houver expressões de junção na cláusula WHERE. Valores: 0 - sem reescrita, 1 - aplicar se possível a junções por vírgula/CROSS JOIN, 2 - forçar a reescrita de todas as junções por vírgula, CROSS JOIN - se possível

data_type_default_nullable

Permite que tipos de dados sem modificadores explícitos NULL ou NOT NULL na definição de coluna sejam do tipo Nullable. Valores possíveis:

1 — Os tipos de dados nas definições de coluna são definidos como Nullable por padrão.
0 — Os tipos de dados nas definições de coluna são definidos como não Nullable por padrão.

decimal_check_overflow

Verifica overflow em operações aritméticas e de comparação com Decimal

deduplicate_blocks_in_dependent_materialized_views

Habilita ou desabilita a verificação de desduplicação para visões materializadas que recebem dados de tabelas Replicated*. Possíveis valores:

0 — Desabilitado.
1 — Habilitado.

Quando habilitada, o ClickHouse realiza a desduplicação de blocos em visões materializadas que dependem de tabelas Replicated*. Essa configuração é útil para garantir que as visões materializadas não contenham dados duplicados quando a operação de inserção estiver sendo tentada novamente devido a uma falha. Veja também

Processamento de NULL em operadores IN

defer_partition_pruning_after_final

Quando habilitada (padrão), a poda de partições é ignorada em consultas FINAL em tabelas cujas colunas da chave de partição não fazem parte da chave de ordenação. Esse é o comportamento seguro do ponto de vista da correção introduzido na 26.3: FINAL pode precisar desduplicar linhas que compartilham a mesma chave primária, mas estão em partições diferentes, e a poda de partições excluiria silenciosamente essas linhas da entrada usada na desduplicação. Quando desabilitada, a poda de partições é aplicada mesmo com FINAL, restaurando o comportamento anterior à 26.3. Isso pode ser substancialmente mais rápido para consultas com predicados WHERE na coluna de partição, mas só é correto quando linhas com a mesma chave primária não podem existir em partições diferentes — por exemplo, tabelas de log de eventos cuja coluna de partição é definida no momento do insert e nunca muda. Essa configuração afeta apenas tabelas particionadas cujas colunas da chave de partição não estão incluídas na chave de ordenação; para as demais tabelas, a poda de partições é sempre aplicada. Valores possíveis:

0 — Aplicar a poda de partições antes de FINAL (comportamento anterior à 26.3, mais rápido, mas inseguro no caso geral).
1 — Adiar a poda de partições para depois de FINAL (padrão, seguro do ponto de vista da correção).

describe_compact_output

Se true, inclui apenas os nomes e tipos das colunas no resultado da consulta DESCRIBE

dialeto

Qual dialeto será usado para interpretar a consulta

discard_query_data

Se estiver habilitada, o servidor deixa de enviar ao cliente as linhas de resultado da consulta. A consulta ainda é executada e registrada integralmente no servidor, e o cliente ainda recebe os pacotes restantes. Usado para tráfego espelhado, benchmarks e fuzzing. Não tem efeito em consultas secundárias. Afeta apenas o protocolo TCP nativo.

distinct_overflow_mode

Define o que acontece quando a quantidade de dados excede um dos limites. Valores possíveis:

throw: gera uma exceção (padrão).
break: interrompe a execução da consulta e retorna o resultado parcial, como se os dados de origem tivessem se esgotado.

do_not_merge_across_partitions_select_final

Melhora consultas FINAL ao evitar mesclagens entre partições diferentes. Quando ativado, em consultas SELECT FINAL, partes de partições diferentes não serão mescladas entre si. Em vez disso, a mesclagem ocorrerá separadamente apenas dentro de cada partição. Isso pode melhorar significativamente o desempenho das consultas ao trabalhar com tabelas particionadas.

dynamic_throw_on_type_mismatch

Ao aplicar uma função a uma coluna Dynamic usando a implementação padrão, determina o que acontece com as linhas cujo tipo real é incompatível com a função:

true (padrão) — gera uma exceção.
false — retorna NULL para essas linhas.

enforce_strict_identifier_format

Se ativado, permite apenas identificadores com caracteres alfanuméricos e sublinhados.

engine_url_skip_empty_files

Ativa ou desativa a opção de ignorar arquivos vazios em tabelas com o motor URL. Valores possíveis:

0 — SELECT lança uma exceção se o arquivo vazio não for compatível com o formato solicitado.
1 — SELECT retorna um resultado vazio para arquivo vazio.

exact_rows_before_limit

Quando ativada, o ClickHouse fornecerá o valor exato da estatística rows_before_limit_at_least, mas isso exige que os dados antes do limite sejam lidos por completo

except_default_mode

Define o modo padrão da consulta EXCEPT. Valores possíveis: string vazia, ‘ALL’, ‘DISTINCT’. Se estiver vazio, a consulta sem modo gerará uma exceção.

exclude_materialize_skip_indexes_on_insert

Exclui os skip indexes especificados da criação e do armazenamento durante INSERTs. Os skip indexes excluídos ainda serão criados e armazenados durante merges ou por uma consulta explícita MATERIALIZE INDEX. Não tem efeito se materialize_skip_indexes_on_insert estiver definido como false. Exemplo:

CREATE TABLE tab
(
    a UInt64,
    b UInt64,
    INDEX idx_a a TYPE minmax,
    INDEX idx_b b TYPE set(3)
)
ENGINE = MergeTree ORDER BY tuple();

SET exclude_materialize_skip_indexes_on_insert='idx_a'; -- idx_a will be not be updated upon insert
--SET exclude_materialize_skip_indexes_on_insert='idx_a, idx_b'; -- neither index would be updated on insert

INSERT INTO tab SELECT number, number / 50 FROM numbers(100); -- only idx_b is updated

-- since it is a session setting it can be set on a per-query level
INSERT INTO tab SELECT number, number / 50 FROM numbers(100, 100) SETTINGS exclude_materialize_skip_indexes_on_insert='idx_b';

ALTER TABLE tab MATERIALIZE INDEX idx_a; -- this query can be used to explicitly materialize the index

SET exclude_materialize_skip_indexes_on_insert = DEFAULT; -- reset setting to default

execute_exists_as_scalar_subquery

Executa subconsultas EXISTS não correlacionadas como subconsultas escalares. Assim como ocorre com subconsultas escalares, o cache é usado, e o constant folding é aplicado ao resultado. Valor padrão no Cloud: 0.

explain_query_plan_default

Formato padrão usado pelo EXPLAIN PLAN. Valores possíveis:

pretty (padrão desde a 26.7) — actions, compact e pretty são true por padrão, produzindo um plano compacto, Pretty e anotado com ações.
legacy — saída anterior à 26.7.

Especificar explicitamente as opções actions, compact ou pretty na instrução EXPLAIN (por exemplo, EXPLAIN actions = 0, compact = 0, pretty = 0 SELECT ...) sempre substitui essa configuração. EXPLAIN PLAN com json = 1 ou distributed = 1 mantém os padrões legados (anteriores à 26.7) independentemente dessa configuração, a menos que actions, compact ou pretty sejam definidos explicitamente. A saída Pretty não consegue representar resultados JSON nem planos distribuídos por shard, portanto esses modos só são renderizados corretamente no formato legado.

extract_key_value_pairs_max_pairs_per_row

Aliases: extract_kvp_max_pairs_per_row Número máximo de pares que podem ser produzidos pela função extractKeyValuePairs. Usado como proteção contra o consumo excessivo de memória.

extremes

Define se os valores extremos devem ser contabilizados (os valores mínimos e máximos nas colunas do resultado de uma consulta). Aceita 0 ou 1. O padrão é 0 (desabilitado). Para mais informações, consulte a seção “Valores extremos”.

fallback_to_stale_replicas_for_distributed_queries

Força uma consulta a usar uma réplica desatualizada se os dados atualizados não estiverem disponíveis. Veja Replicação. O ClickHouse seleciona a réplica mais adequada entre as réplicas desatualizadas da tabela. Usado ao executar SELECT em uma tabela distribuída que aponta para tabelas replicadas. Por padrão, 1 (habilitado).

file_like_engine_default_partition_strategy

Estratégia de partição padrão para motores semelhantes a arquivos.

filesystem_prefetches_limit

Número máximo de prefetches. Zero significa sem limite. A configuração filesystem_prefetches_max_memory_usage é mais recomendada se você quiser limitar o número de prefetches

final

Aplica automaticamente o modificador FINAL a todas as tabelas de uma consulta para as quais FINAL é aplicável, incluindo tabelas em joins, tabelas em subconsultas e tabelas distribuídas. Valores possíveis:

0 - desabilitado
1 - habilitado

Exemplo:

CREATE TABLE test
(
    key Int64,
    some String
)
ENGINE = ReplacingMergeTree
ORDER BY key;

INSERT INTO test FORMAT Values (1, 'first');
INSERT INTO test FORMAT Values (1, 'second');

SELECT * FROM test;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘
┌─key─┬─some──┐
│   1 │ first │
└─────┴───────┘

SELECT * FROM test SETTINGS final = 1;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘

SET final = 1;
SELECT * FROM test;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘

finalize_projection_parts_synchronously

Quando ativada, as partes de projeção são finalizadas de forma síncrona durante o INSERT, reduzindo o pico de uso de memória à custa de menor paralelismo no upload para o S3. Por padrão, o fluxo de saída de cada projeção é mantido ativo até que toda a parte (incluindo todas as projeções) seja finalizada, o que permite sobrepor uploads para o S3, mas aumenta o pico de uso de memória proporcionalmente ao número de projeções. Essa configuração afeta apenas o caminho de INSERT; merge e mutation já finalizam projeções de forma síncrona.

flatten_nested

Define o formato de dados das colunas Nested. Valores possíveis:

1 — A coluna Nested é expandida em arrays separados.
0 — A coluna Nested permanece como um único array de tuplas.

Uso Se a configuração estiver definida como 0, é possível usar qualquer nível de aninhamento. Exemplos Consulta:

SET flatten_nested = 1;
CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();

SHOW CREATE TABLE t_nest;

Resultado:

┌─statement───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_nest
(
    `n.a` Array(UInt32),
    `n.b` Array(UInt32)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 8192 │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Consulta:

SET flatten_nested = 0;

CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();

SHOW CREATE TABLE t_nest;

Resultado:

┌─statement──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_nest
(
    `n` Nested(a UInt32, b UInt32)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 8192 │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

fsync_metadata

Ativa ou desativa o fsync ao gravar arquivos .sql. Ativado por padrão. Faz sentido desativá-lo se o servidor tiver milhões de tabelas pequenas sendo constantemente criadas e removidas.

functions_h3_default_if_invalid

Se false, as funções h3, por exemplo h3CellAreaM2, lançam uma exceção se a entrada for inválida. Se true, retornam 0 ou o valor padrão.

geo_distance_returns_float64_on_float64_arguments

Se os quatro argumentos das funções geoDistance, greatCircleDistance e greatCircleAngle forem Float64, retorne Float64 e use precisão dupla nos cálculos internos. Em versões anteriores do ClickHouse, as funções sempre retornavam Float32.

geotoh3_argument_order

A função ‘geoToH3’ aceita (lon, lat) quando definida como ‘lon_lat’ e (lat, lon) quando definida como ‘lat_lon’.

glob_expansion_max_elements

Número máximo de endereços permitidos (para armazenamento externo, funções de tabela etc.).

h3togeo_lon_lat_result_order

A função ‘h3ToGeo’ retorna (lon, lat) se true; caso contrário, (lat, lon).

handshake_timeout_ms

Tempo limite, em milissegundos, para receber o pacote Hello das réplicas durante o handshake.

hedged_connection_timeout_ms

Timeout de conexão para estabelecer uma conexão com a réplica em hedged requests

highlight_max_matches_per_row

Define o número máximo de correspondências de destaque por linha na função highlight. Use essa configuração para se proteger contra uso excessivo de memória ao destacar padrões altamente repetitivos em textos longos. Valores possíveis:

Inteiro positivo.

hnsw_candidate_list_size_for_search

O tamanho da lista dinâmica de candidatos durante a busca no índice de similaridade vetorial, também conhecido como ‘ef_search’.

hsts_max_age

Tempo de expiração do HSTS. 0 significa desativar o HSTS.

idle_connection_timeout

Tempo limite para encerrar conexões TCP ociosas após o número especificado de segundos. Valores possíveis:

Inteiro positivo (0 - encerra imediatamente, após 0 segundos).

inject_random_order_for_select_without_order_by

Se habilitado, injeta ‘ORDER BY rand()’ em consultas SELECT sem cláusula ORDER BY. Aplica-se apenas à profundidade de subconsulta = 0. Subconsultas e INSERT INTO … SELECT não são afetados. Se a construção no nível superior for UNION, ‘ORDER BY rand()’ é injetado em todos os filhos de forma independente. Útil apenas para testes e desenvolvimento (a ausência de ORDER BY é uma fonte de resultados de consulta não determinísticos).

interactive_delay

O intervalo, em microssegundos, para verificar se a execução da requisição foi cancelada e enviar informações de progresso.

intersect_default_mode

Define o modo padrão da consulta INTERSECT. Valores possíveis: string vazia, ‘ALL’, ‘DISTINCT’. Se estiver vazio, a consulta sem modo gerará uma exceção.

least_greatest_legacy_null_behavior

Quando ativada, as funções ‘least’ e ‘greatest’ retornam NULL se um de seus argumentos for NULL.

legacy_column_name_of_tuple_literal

Liste todos os nomes dos elementos de literais Tuple grandes em seus nomes de colunas em vez de hash. Esta configuração existe apenas por motivos de compatibilidade. Faz sentido defini-la como ‘true’ ao fazer rolling update do cluster de uma versão inferior à 21.7 para uma superior.

limit

Define o número máximo de linhas a retornar no resultado da consulta. Ele ajusta o valor definido pela cláusula LIMIT, de modo que o limite especificado na consulta não possa exceder o limite definido por esta configuração. Possíveis valores:

0 — O número de linhas não é limitado.
Inteiro positivo.

load_marks_asynchronously

Carrega as marcas do MergeTree de forma assíncrona Valor padrão no Cloud: 1.

lock_acquire_timeout

Define quantos segundos uma solicitação de bloqueio aguarda antes de falhar. O tempo limite de bloqueio é usado para evitar deadlocks durante a execução de operações de leitura/gravação em tabelas. Quando o tempo limite se esgota e a solicitação de bloqueio falha, o servidor ClickHouse lança uma exceção “Locking attempt timed out! Possible deadlock avoided. Client should retry.” com o código de erro DEADLOCK_AVOIDED. Valores possíveis:

Inteiro positivo (em segundos).
0 — Sem tempo limite de bloqueio.

low_priority_query_wait_time_ms

Quando o mecanismo de priorização de consultas é usado (consulte a configuração priority), as consultas de baixa prioridade aguardam até que as de prioridade mais alta terminem. Essa configuração especifica o tempo de espera.

make_distributed_plan

Cria o plano de consulta distribuída.

merge_table_max_tables_to_look_for_schema_inference

Ao criar uma tabela Merge sem um esquema explícito ou ao usar a função de tabela merge, infira o esquema como a união de, no máximo, o número especificado de tabelas correspondentes. Se houver mais tabelas do que isso, o esquema será inferido a partir das primeiras tabelas, até o número especificado.

mongodb_throw_on_unsupported_query

Se estiver habilitada, as tabelas do MongoDB retornarão erro quando uma consulta do MongoDB não puder ser gerada. Caso contrário, o ClickHouse lê a tabela inteira e a processa localmente. Esta opção não se aplica quando ‘allow_experimental_analyzer=0’.

multiple_joins_try_to_keep_original_names

Não adiciona aliases à lista de expressões de nível superior na reescrita de múltiplas junções

normalize_function_names

Normaliza os nomes das funções para suas formas canônicas

offset

Define o número de linhas a serem ignoradas antes de começar a retornar linhas da consulta. Ele ajusta o offset definido pela cláusula OFFSET, para que esses dois valores sejam somados. Valores possíveis:

0 — Nenhuma linha é ignorada.
Inteiro positivo.

Exemplo Tabela de entrada:

CREATE TABLE test (i UInt64) ENGINE = MergeTree() ORDER BY i;
INSERT INTO test SELECT number FROM numbers(500);

Consulta:

SET limit = 5;
SET offset = 7;
SELECT * FROM test LIMIT 10 OFFSET 100;

Resultado:

┌───i─┐
│ 107 │
│ 108 │
│ 109 │
└─────┘

paimon_target_snapshot_id

Leitura direcionada de snapshot no nível da consulta para o modo incremental do Paimon. Quando >0, o leitor buscará apenas o delta do snapshot_id especificado, sem avançar a watermark confirmada. Padrão: -1 (desabilitado)

parallelize_output_from_storages

Paraleliza a saída na etapa de leitura a partir do armazenamento. Permite paralelizar o processamento de consultas logo após a leitura do armazenamento, quando possível

partial_result_on_first_cancel

Permite que a consulta retorne um resultado parcial após o cancelamento.

per_part_index_stats

Registra estatísticas do índice para cada parte

poll_interval

Bloqueia no loop de espera da consulta no servidor pelo número de segundos especificado.

polyglot_dialect

Dialeto SQL de origem do transpilador polyglot (por exemplo, ‘sqlite’, ‘mysql’, ‘postgresql’, ‘snowflake’, ‘duckdb’).

postgresql_fault_injection_probability

Probabilidade aproximada de falha nas consultas internas do PostgreSQL (para replicação). O valor válido está no intervalo [0.0f, 1.0f]

predicate_statistics_sample_rate

Coleta estatísticas de seletividade de predicados em system.predicate_statistics_log. Quando definido como N > 0, aproximadamente 1/N das consultas são amostradas (pelo ID da consulta). 0 significa que está desabilitado.

prefetch_buffer_size

O tamanho máximo do buffer de prefetch para leitura do sistema de arquivos. Valores acima de 256 MiB são limitados a 256 MiB, pois um buffer de leitura nunca precisa ser maior.

print_pretty_type_names

Permite exibir nomes de tipos com aninhamento profundo de forma legível, com indentação, na consulta DESCRIBE e na função toTypeName(). Exemplo:

CREATE TABLE test (a Tuple(b String, c Tuple(d Nullable(UInt64), e Array(UInt32), f Array(Tuple(g String, h Map(String, Array(Tuple(i String, j UInt64))))), k Date), l Nullable(String))) ENGINE=Memory;
DESCRIBE TABLE test FORMAT TSVRaw SETTINGS print_pretty_type_names=1;

a   Tuple(
    b String,
    c Tuple(
        d Nullable(UInt64),
        e Array(UInt32),
        f Array(Tuple(
            g String,
            h Map(
                String,
                Array(Tuple(
                    i String,
                    j UInt64
                ))
            )
        )),
        k Date
    ),
    l Nullable(String)
)

priority

Priority da consulta. 1 - a mais alta; quanto maior o valor, menor a priority; 0 - não usar priorities.

push_external_roles_in_interserver_queries

Habilita o envio das roles do usuário do nó de origem para outros nós durante a execução de uma consulta.

query_metric_log_interval

O intervalo, em milissegundos, em que o query_metric_log é coletado para consultas individuais. Se for definido com qualquer valor negativo, ele assumirá o valor de collect_interval_milliseconds da configuração query_metric_log ou, se ela não estiver presente, o valor padrão de 1000. Para desativar a coleta de uma única consulta, defina query_metric_log_interval como 0. Valor padrão: -1

queue_max_wait_ms

O tempo de espera na fila de requisições, caso o número de requisições simultâneas exceda o máximo.

rabbitmq_max_wait_ms

O tempo de espera para leitura do RabbitMQ antes de tentar novamente.

readonly

0 - sem restrições de somente leitura. 1 - apenas requisições de leitura, bem como a alteração de configurações explicitamente permitidas. 2 - apenas requisições de leitura, bem como a alteração de configurações, exceto da configuração ‘readonly’.

recursive_cte_max_steps_in_type_inference

Número máximo de iterações para inferir tipos de coluna em CTEs recursivas. Os tipos de coluna são determinados pela aplicação iterativa de getLeastSupertype aos lados não recursivo e recursivo do UNION ALL até a convergência. Defina como 0 para desativar a ampliação de tipos e usar apenas os tipos da parte não recursiva.

regexp_max_matches_per_row

Define o número máximo de correspondências de uma única expressão regular por linha. Use essa configuração para evitar sobrecarga de memória ao usar uma expressão regular gulosa na função extractAllGroupsHorizontal. Valores possíveis:

Inteiro positivo.

reject_expensive_hyperscan_regexps

Rejeita padrões cuja avaliação com hyperscan provavelmente será custosa (devido à explosão de estados do NFA)

remerge_sort_lowered_memory_bytes_ratio

Se o uso de memória após o remerge não for reduzido nessa razão, o remerge será desativado.

remote_read_min_bytes_for_seek

Quantidade mínima de bytes necessária para que a leitura remota (url, s3) faça seek, em vez de ler com ignore.

rename_files_after_processing

Tipo: String
Valor padrão: String vazia

Esta configuração permite especificar o padrão de renomeação para arquivos processados pela função de tabela file. Quando essa opção é definida, todos os arquivos lidos pela função de tabela file serão renomeados de acordo com o padrão especificado com placeholders, somente se o processamento dos arquivos for bem-sucedido.

Placeholders

%a — Nome completo do arquivo original (por exemplo, “sample.csv”).
%f — Nome do arquivo original sem extensão (por exemplo, “sample”).
%e — Extensão do arquivo original com ponto (por exemplo, “.csv”).
%t — Timestamp (em microssegundos).
%% — Símbolo de porcentagem (”%”).

Exemplo

Opção: --rename_files_after_processing="processed_%f_%t%e"
Consulta: SELECT * FROM file('sample.csv')

Se a leitura de sample.csv for concluída com sucesso, o arquivo será renomeado para processed_sample_1683473210851438.csv

replication_wait_for_inactive_replica_timeout

Especifica por quanto tempo (em segundos) esperar até que réplicas inativas executem consultas ALTER, OPTIMIZE ou TRUNCATE. Valores possíveis:

0 — Não esperar.
Inteiro negativo — Espera por tempo ilimitado.
Inteiro positivo — Número de segundos de espera.

reserve_memory

Usado no agendamento de workloads. Quantidade mínima de RAM reservada para a execução de uma consulta em um único servidor. A reserva é feita por meio da hierarquia WORKLOAD usando o valor da configuração de consulta workload. Se não houver memória suficiente disponível para o workload, a consulta não será iniciada e ficará em estado pendente até que a reserva possa ser atendida. Um valor de 0 significa que não há reserva. Essa configuração só entra em vigor se o recurso MEMORY RESERVATION for criado.

restore_replicated_merge_tree_to_shared_merge_tree

Substitui o engine da tabela de ReplicatedMergeTree por SharedMergeTree durante o RESTORE. Valor padrão na Cloud: 1.

result_overflow_mode

Define o que fazer se o volume do resultado exceder um dos limites. Valores possíveis:

throw: lançar uma exceção (padrão).
break: interromper a execução da consulta e retornar o resultado parcial, como se os dados de origem tivessem se esgotado.

Usar ‘break’ é semelhante a usar LIMIT. Break interrompe a execução apenas no nível do bloco. Isso significa que a quantidade de linhas retornadas será maior que max_result_rows, será um múltiplo de max_block_size e dependerá de max_threads. Exemplo

Query

SET max_threads = 3, max_block_size = 3333;
SET max_result_rows = 3334, result_overflow_mode = 'break';

SELECT *
FROM numbers_mt(100000)
FORMAT Null;

Result

6666 rows in set. ...

rows_before_aggregation

Quando habilitada, o ClickHouse fornecerá o valor exato da estatística rows_before_aggregation, que representa o número de linhas lidas antes da agregaçã

secondary_indices_enable_bulk_filtering

Ativa o algoritmo de filtragem em lote para índices. A expectativa é que ele seja sempre superior, mas mantemos esta configuração por compatibilidade e controle.

select_sequential_consistency

Essa configuração tem comportamento diferente no SharedMergeTree e no ReplicatedMergeTree. Consulte SharedMergeTree consistency para mais informações sobre o comportamento de select_sequential_consistency no SharedMergeTree.

Habilita ou desabilita a consistência sequencial para consultas SELECT. Requer que insert_quorum_parallel esteja desabilitado (habilitado por padrão). Valores possíveis:

0 — Desabilitado.
1 — Habilitado.

Uso Quando a consistência sequencial está habilitada, o ClickHouse permite que o cliente execute a consulta SELECT apenas nas réplicas que contêm dados de todas as consultas INSERT anteriores executadas com insert_quorum. Se o cliente se conectar a uma réplica parcial, o ClickHouse gerará uma exceção. A consulta SELECT não incluirá dados que ainda não tenham sido gravados no quorum de réplicas. Quando insert_quorum_parallel está habilitado (o padrão), select_sequential_consistency não funciona. Isso acontece porque consultas INSERT paralelas podem ser gravadas em diferentes conjuntos de réplicas de quorum, portanto não há garantia de que uma única réplica terá recebido todas as gravações. Veja também:

session_timezone

Define o fuso horário implícito da sessão ou da consulta atual. O fuso horário implícito é o fuso horário aplicado a valores do tipo DateTime/DateTime64 que não têm um fuso horário explicitamente especificado. Essa configuração tem precedência sobre o fuso horário implícito configurado globalmente (no nível do servidor). Um valor de ” (string vazia) significa que o fuso horário implícito da sessão ou da consulta atual é igual ao fuso horário do servidor. Você pode usar as funções timeZone() e serverTimeZone() para obter o fuso horário da sessão e o fuso horário do servidor. Valores possíveis:

Qualquer nome de fuso horário de system.time_zones, por exemplo, Europe/Berlin, UTC ou Zulu

Exemplos:

SELECT timeZone(), serverTimeZone() FORMAT CSV

"Europe/Berlin","Europe/Berlin"

SELECT timeZone(), serverTimeZone() SETTINGS session_timezone = 'Asia/Novosibirsk' FORMAT CSV

"Asia/Novosibirsk","Europe/Berlin"

Atribua o fuso horário da sessão ‘America/Denver’ ao DateTime interno sem fuso horário explicitamente especificado:

SELECT toDateTime64(toDateTime64('1999-12-12 23:23:23.123', 3), 3, 'Europe/Zurich') SETTINGS session_timezone = 'America/Denver' FORMAT TSV

1999-12-13 07:23:23.123

Nem todas as funções que interpretam DateTime/DateTime64 respeitam session_timezone. Isso pode levar a erros sutis. Veja o exemplo e a explicação a seguir.

CREATE TABLE test_tz (`d` DateTime('UTC')) ENGINE = Memory AS SELECT toDateTime('2000-01-01 00:00:00', 'UTC');

SELECT *, timeZone() FROM test_tz WHERE d = toDateTime('2000-01-01 00:00:00') SETTINGS session_timezone = 'Asia/Novosibirsk'
0 rows in set.

SELECT *, timeZone() FROM test_tz WHERE d = '2000-01-01 00:00:00' SETTINGS session_timezone = 'Asia/Novosibirsk'
┌───────────────────d─┬─timeZone()───────┐
│ 2000-01-01 00:00:00 │ Asia/Novosibirsk │
└─────────────────────┴──────────────────┘

Isso ocorre devido a pipelines de parsing diferentes:

toDateTime() sem fuso horário explicitamente informado, usado na primeira consulta SELECT, respeita a configuração session_timezone e o fuso horário global.
Na segunda consulta, um DateTime é convertido de uma String e herda o tipo e o fuso horário da coluna existented. Assim, a configuração session_timezone e o fuso horário global não são respeitados.

Veja também

timezone

set_overflow_mode

Determina o que acontece quando a quantidade de dados excede um dos limites. Valores possíveis:

throw: lançar uma exceção (padrão).
break: interromper a execução da consulta e retornar o resultado parcial, como se os dados de origem tivessem se esgotado.

single_join_prefer_left_table

Para um único JOIN, em caso de ambiguidade de identificador, prefira a tabela à esquerda

skip_redundant_aliases_in_udf

Aliases redundantes não são usados (substituídos) em funções definidas pelo usuário, para simplificar seu uso. Valores possíveis:

1 — Os aliases são ignorados (substituídos) em UDFs.
0 — Os aliases não são ignorados (substituídos) em UDFs.

Exemplo A diferença entre ativado e desativado: Consulta:

SET skip_redundant_aliases_in_udf = 0;
CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2));

EXPLAIN SYNTAX SELECT test_03274(4 + 2);

Resultado:

SELECT ((4 + 2) + 1 AS y, y + 2)

Consulta:

SET skip_redundant_aliases_in_udf = 1;
CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2));

EXPLAIN SYNTAX SELECT test_03274(4 + 2);

Resultado:

SELECT ((4 + 2) + 1, ((4 + 2) + 1) + 2)

sleep_after_receiving_query_ms

Tempo de espera após o recebimento da consulta no TCPHandler

snappy_mode

Controla o formato wire usado pela compressão snappy em caminhos genéricos de E/S de arquivo, como file e url. Content-Encoding: snappy em HTTP sempre usa o formato de framing e ignora esta configuração. Observe que o formato bruto de bloco snappy produzido por uma única chamada a snappy::Compress (por exemplo, os payloads do protocolo remoto do Prometheus processados por SnappyBasicReadBuffer) é um formato wire separado, específico do protocolo, e não é controlado por esta configuração. Valores possíveis:

basic — Formato de bloco snappy do Hadoop. Compatível com arquivos lidos e gravados pelo Hadoop. Suporta leitura e gravação.
framed — Formato de framing do Snappy, o formato de streaming padrão definido pelo Google. Suporta leitura e gravação.

sort_overflow_mode

Define o que acontece se o número de linhas recebidas antes da ordenação exceder um dos limites. Valores possíveis:

throw: gerar uma exceção.
break: interromper a execução da consulta e retornar o resultado parcial.

splitby_max_substrings_includes_remaining_string

Controla se a função splitBy*(), com o argumento max_substrings > 0, incluirá a parte restante da string no último elemento do array de resultado. Valores possíveis:

0 - A parte restante da string não será incluída no último elemento do array de resultado.
1 - A parte restante da string será incluída no último elemento do array de resultado. Esse é o comportamento da função split() do Spark e do método ‘string.split()’ do Python.

stop_refreshable_materialized_views_on_startup

Ao iniciar o servidor, impede o agendamento de views materializadas atualizáveis, como se SYSTEM STOP VIEWS tivesse sido executado. Depois, você pode iniciá-las manualmente com SYSTEM START VIEWS ou SYSTEM START VIEW <name>. Também se aplica a views criadas posteriormente. Não tem efeito sobre views materializadas não atualizáveis.

tcp_keep_alive_timeout

O tempo, em segundos, que a conexão deve permanecer ociosa antes de o TCP começar a enviar sondas de keepalive

temporary_data_in_cache_reserve_space_wait_lock_timeout_milliseconds

Tempo de espera para bloquear o cache ao reservar espaço para dados temporários no cache do sistema de arquivos

throw_if_no_data_to_insert

Permite ou proíbe INSERTs vazios; ativado por padrão (gera um erro ao fazer um INSERT vazio). Aplica-se apenas a INSERTs usando clickhouse-client ou a interface gRPC.

timeout_before_checking_execution_speed

Verifica, após o tempo especificado em segundos ter decorrido, se a velocidade de execução não está muito baixa (não inferior a min_execution_speed).

transfer_overflow_mode

Define o que acontece quando a quantidade de dados excede um dos limites. Valores possíveis:

throw: gera uma exceção (padrão).
break: interrompe a execução da consulta e retorna o resultado parcial, como se os dados de origem tivessem se esgotado.

transform_null_in

Habilita a equivalência entre valores NULL para o operador IN. Por padrão, valores NULL não podem ser comparados, porque NULL significa um valor indefinido. Portanto, a comparação expr = NULL deve sempre retornar false. Com essa configuração, NULL = NULL retorna true para o operador IN. Valores possíveis:

0 — A comparação entre valores NULL no operador IN retorna false.
1 — A comparação entre valores NULL no operador IN retorna true.

Exemplo Considere a tabela null_in:

┌──idx─┬─────i─┐
│    1 │     1 │
│    2 │  NULL │
│    3 │     3 │
└──────┴───────┘

Consulta:

SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 0;

Resultado:

┌──idx─┬────i─┐
│    1 │    1 │
└──────┴──────┘

Consulta:

SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 1;

Resultado:

┌──idx─┬─────i─┐
│    1 │     1 │
│    2 │  NULL │
└──────┴───────┘

Veja também

Processamento de NULL em Operadores IN

traverse_shadow_remote_data_paths

Percorre os dados congelados (diretório shadow), além dos dados da própria tabela, ao consultar system.remote_data_paths

union_default_mode

Define um modo para combinar os resultados de consultas SELECT. A configuração só é usada com UNION quando UNION ALL ou UNION DISTINCT não é especificado explicitamente. Valores possíveis:

'DISTINCT' — o ClickHouse retorna linhas como resultado da combinação de consultas, removendo linhas duplicadas.
'ALL' — o ClickHouse retorna todas as linhas como resultado da combinação de consultas, incluindo linhas duplicadas.
'' — o ClickHouse gera uma exceção quando usado com UNION.

Veja exemplos em UNION.

unique_key_max_encoded_size

Tamanho máximo (em bytes) da codificação binária que preserva a ordem de uma única linha de UNIQUE KEY.

unknown_packet_in_send_data

Enviar um pacote desconhecido em vez do enésimo pacote de dados

variant_throw_on_type_mismatch

Ao aplicar uma função a uma coluna Variant usando a implementação padrão, essa configuração controla o que acontece com as linhas cujo tipo real é incompatível com a função:

true (padrão) — lança uma exceção.
false — retorna NULL para essas linhas.

wait_changes_become_visible_after_commit_mode

Aguarda que as alterações confirmadas se tornem efetivamente visíveis no snapshot mais recente

workload

Nome da workload usada para acessar recursos

write_full_path_in_iceberg_metadata

Grava caminhos completos (incluindo s3://) nos arquivos de metadados do Iceberg.

zstd_window_log_max

Permite selecionar o valor máximo do log de janela do ZSTD (não será usado para a família MergeTree)

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

Configurações das tabelas MergeTreeConfigurações do MergeTree que estão em `system.merge_tree_settings`

​add_http_cors_header

​analyze_index_with_space_filling_curves

​analyzer_inline_views

​any_join_distinct_right_table_keys

​archive_adaptive_buffer_max_size_bytes

​arrow_flight_request_descriptor_type

​backup_slow_all_threads_after_retryable_s3_error

​cache_warmer_threads

​calculate_text_stack_trace

​cancel_http_readonly_queries_on_client_close

​checksum_on_read

​connection_pool_max_wait_ms

​connections_with_failover_max_tries

​convert_query_to_cnf

​count_matches_stop_at_empty_match

​cross_to_inner_join_rewrite

​data_type_default_nullable

​decimal_check_overflow

​deduplicate_blocks_in_dependent_materialized_views

​defer_partition_pruning_after_final

​describe_compact_output

​dialeto

​discard_query_data

​distinct_overflow_mode

​do_not_merge_across_partitions_select_final

​dynamic_throw_on_type_mismatch

​enforce_strict_identifier_format

​engine_url_skip_empty_files

​exact_rows_before_limit

​except_default_mode

​exclude_materialize_skip_indexes_on_insert

​execute_exists_as_scalar_subquery

​explain_query_plan_default

​extract_key_value_pairs_max_pairs_per_row

​extremes

​fallback_to_stale_replicas_for_distributed_queries

​file_like_engine_default_partition_strategy

​filesystem_prefetches_limit

​final

​finalize_projection_parts_synchronously

​flatten_nested

​fsync_metadata

​functions_h3_default_if_invalid

​geo_distance_returns_float64_on_float64_arguments

​geotoh3_argument_order

​glob_expansion_max_elements

​h3togeo_lon_lat_result_order

​handshake_timeout_ms

​hedged_connection_timeout_ms

​highlight_max_matches_per_row

​hnsw_candidate_list_size_for_search

​hsts_max_age

​idle_connection_timeout

​inject_random_order_for_select_without_order_by

​interactive_delay

​intersect_default_mode

​least_greatest_legacy_null_behavior

​legacy_column_name_of_tuple_literal

​limit

​load_marks_asynchronously

​lock_acquire_timeout

​low_priority_query_wait_time_ms

​make_distributed_plan

​merge_table_max_tables_to_look_for_schema_inference

​mongodb_throw_on_unsupported_query

​multiple_joins_try_to_keep_original_names

​normalize_function_names

​offset

​paimon_target_snapshot_id

​parallelize_output_from_storages

​partial_result_on_first_cancel

​per_part_index_stats

​poll_interval

​polyglot_dialect

​postgresql_fault_injection_probability

​predicate_statistics_sample_rate

​prefetch_buffer_size

​print_pretty_type_names

​priority

​push_external_roles_in_interserver_queries

add_http_cors_header

analyze_index_with_space_filling_curves

analyzer_inline_views

any_join_distinct_right_table_keys

archive_adaptive_buffer_max_size_bytes

arrow_flight_request_descriptor_type

backup_slow_all_threads_after_retryable_s3_error

cache_warmer_threads

calculate_text_stack_trace

cancel_http_readonly_queries_on_client_close

checksum_on_read

connection_pool_max_wait_ms

connections_with_failover_max_tries

convert_query_to_cnf

count_matches_stop_at_empty_match

cross_to_inner_join_rewrite

data_type_default_nullable

decimal_check_overflow

deduplicate_blocks_in_dependent_materialized_views

defer_partition_pruning_after_final

describe_compact_output

dialeto

discard_query_data

distinct_overflow_mode

do_not_merge_across_partitions_select_final

dynamic_throw_on_type_mismatch

enforce_strict_identifier_format

engine_url_skip_empty_files

exact_rows_before_limit

except_default_mode

exclude_materialize_skip_indexes_on_insert

execute_exists_as_scalar_subquery

explain_query_plan_default

extract_key_value_pairs_max_pairs_per_row

extremes

fallback_to_stale_replicas_for_distributed_queries

file_like_engine_default_partition_strategy

filesystem_prefetches_limit

final

finalize_projection_parts_synchronously

flatten_nested

fsync_metadata

functions_h3_default_if_invalid

geo_distance_returns_float64_on_float64_arguments

geotoh3_argument_order

glob_expansion_max_elements

h3togeo_lon_lat_result_order

handshake_timeout_ms

hedged_connection_timeout_ms

highlight_max_matches_per_row

hnsw_candidate_list_size_for_search

hsts_max_age

idle_connection_timeout

inject_random_order_for_select_without_order_by

interactive_delay

intersect_default_mode

least_greatest_legacy_null_behavior

legacy_column_name_of_tuple_literal

limit

load_marks_asynchronously

lock_acquire_timeout

low_priority_query_wait_time_ms

make_distributed_plan

merge_table_max_tables_to_look_for_schema_inference

mongodb_throw_on_unsupported_query

multiple_joins_try_to_keep_original_names

normalize_function_names

offset

paimon_target_snapshot_id

parallelize_output_from_storages

partial_result_on_first_cancel

per_part_index_stats

poll_interval

polyglot_dialect

postgresql_fault_injection_probability

predicate_statistics_sample_rate

prefetch_buffer_size

print_pretty_type_names

priority

push_external_roles_in_interserver_queries