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.

adaptive_aggregator_freeze_threshold

O número de chaves a partir do qual o agregador adaptativo congela a tabela hash local de uma thread (consulte enable_adaptive_aggregator). Valores menores mantêm as tabelas congeladas na cache, enquanto valores maiores permitem que absorvam mais chaves frequentes. O valor 0 congela as tabelas na primeira oportunidade, fazendo com que o algoritmo se comporte como sharding puro pelo hash da chave: cada chave é roteada pelo seu hash e agregada por um único proprietário, mas apenas na fase de merge, em vez de ser trocada entre threads durante a varredura.

adaptive_aggregator_freeze_threshold_bytes

O tamanho de memória em que o agregador adaptativo congela a tabela hash local de uma thread (consulte enable_adaptive_aggregator). Uma tabela é congelada quando este valor ou adaptive_aggregator_freeze_threshold é atingido primeiro. O tamanho corresponde aos bytes efetivamente alocados pela própria tabela local (seu buffer de tabela hash mais suas arenas) e é verificado entre blocos. O limite em bytes é importante quando as chaves ou os estados de agregação são largos: apenas o limite de contagem de chaves permitiria que essas tabelas ultrapassassem os caches da CPU. Com o valor padrão, tabelas com chaves e estados de largura comum continuam sendo congeladas pela contagem de chaves. O valor 0 desativa o limite em bytes, de modo que apenas o limite de contagem de chaves determina isso.

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. Atualmente, a análise em 2D ignora curvas com argumentos UInt64 porque as implementações das curvas usam apenas 32 bits por argumento.

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.

cascades_aggregation_pushdown

Considera o pushdown da agregação parcial para baixo de um join (agregação imediata) como alternativa baseada em custo no otimizador Cascades. Só tem efeito em conjunto com enable_cascades_optimizer = 1 e make_distributed_plan = 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.

compressão

Aplica compressão genérica ao corpo da resposta, por exemplo, compression=gz. Observe que ela é independente de Content-Encoding (compressão HTTP) e do parâmetro legado compress (compressão nativa do ClickHouse). Especificar no caminho da URL uma extensão de arquivo compactado é equivalente. Esta é uma configuração da interface HTTP que define o formato da resposta: ela é processada antes da execução da consulta (os buffers de resposta são configurados previamente). Portanto, deve ser fornecida pelo parâmetro de URL HTTP, pela extensão de arquivo no caminho da URL ou por um perfil de usuário, e não por uma cláusula SETTINGS na consulta (na qual não tem efeito e é rejeitada).

connection_pool_max_wait_ms

O tempo de espera, em milissegundos, por uma conexão quando o pool de conexões está cheio. A espera é aplicada por réplica, pois há um pool de conexões para cada réplica. Quando expira, a tentativa falha com NO_FREE_CONNECTION. No caminho de failover usado por SELECTs distribuídos, isso é tratado como qualquer outra réplica indisponível: a consulta tenta as réplicas restantes e só falha com ALL_CONNECTION_TRIES_FAILED depois que todas tiverem sido tentadas. Portanto, essa configuração não limita a consulta como um todo; com N réplicas e T tentativas para cada uma, o tempo total de espera pode chegar a connection_pool_max_wait_ms vezes N vezes T, em que T é connections_with_failover_max_tries, mas nunca inferior a um, pois uma réplica é sempre tentada uma vez antes de ser descartada. Use max_execution_time para limitar a própria consulta. skip_unavailable_shards não elimina isso: uma réplica para a qual o initiator não tinha um slot de conexão livre nunca foi contatada, portanto o shard não é tratado como indisponível. Valores possíveis:

Inteiro positivo.
0 — Timeout infinito. A espera ainda é interrompida por KILL QUERY e por max_execution_time com o timeout_overflow_mode padrão throw. Em break, o limite de tempo não cancela a consulta; portanto, a espera continua até que uma conexão seja liberada. KILL QUERY ainda a interrompe.

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

Define qual dialeto será usado para analisar a consulta. Valores compatíveis:

clickhouse (padrão) — SQL padrão do ClickHouse.
kusto — Kusto Query Language. Requer a configuração experimental allow_experimental_kusto_dialect.
prql — PRQL. Requer a configuração experimental allow_experimental_prql_dialect.
polyglot — transpila SQL de outros dialetos (MySQL, PostgreSQL etc.) para ClickHouse SQL. Requer a configuração experimental allow_experimental_polyglot_dialect.
promql — PromQL (Prometheus Query Language) avaliada em uma tabela TimeSeries, configurada pelas opções promql_database, promql_table e promql_evaluation_time.
clickhouse_json — em vez de texto SQL, a consulta é interpretada como um AST JSON (a saída de parseQueryToJSON). A consulta SET continua sendo reconhecida em formato simples para permitir a reversão para outro dialeto. Requer a configuração experimental enable_json_ast_dialect.
trino — Trino SQL: traduz a sintaxe do Trino (ARRAY[...], TRY_CAST, UNNEST, …) e mapeia os nomes das funções do Trino para seus equivalentes no ClickHouse. Requer a configuração experimental enable_trino_dialect.

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 mesclagens 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.

explain_syntax_single_record

Retorna a saída de EXPLAIN SYNTAX como um único registro (com quebras de linha embutidas), em vez de um registro por linha, de modo que o resultado seja uma única linha recuperável (por exemplo, SELECT count() FROM (EXPLAIN SYNTAX ...) retorna 1). Especificar explicitamente a opção single_record na instrução EXPLAIN SYNTAX (por exemplo, EXPLAIN SYNTAX single_record = 0 SELECT ...) sempre substitui esta configuração. Defina como false para restaurar a saída anterior à versão 26.8, com um registro por linha, ou defina compatibility como qualquer versão anterior à 26.8.

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. Aplicada apenas a consultas CREATE com um caminho que não contenha glob nem o placeholder {_partition_id}. Um caminho com {_partition_id} sempre usa wildcard. Um caminho com outro glob não usa estratégia de partição e ignora PARTITION BY. Se essa configuração for wildcard, mas o caminho não tiver {_partition_id}, nenhuma estratégia de partição será usada; motores de tabela que não conseguem persistir essa decisão nos argumentos do motor (por exemplo, HDFS) rejeitam esse CREATE.

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

filter

Adiciona uma cláusula WHERE à consulta, encapsulando-a em uma subconsulta. Vários filtros são combinados com AND. A interface HTTP permite vários parâmetros de URL filter, que são combinados com AND, na ordem em que aparecem, e com o valor dessa configuração. Essa é uma configuração de construção de consultas aplicada pelo engine à consulta convertida em uma tabela derivada. Portanto, ela é composta com a consulta existente e funciona em todos os protocolos: pode ser fornecida por meio de um parâmetro de URL HTTP, de uma cláusula SETTINGS na consulta ou de um perfil de usuário. Ela modifica consultas SELECT / UNION que produzem resultados. Em uma consulta de gravação (INSERT … SELECT, CREATE … AS SELECT), só tem efeito quando o SELECT de origem a inclui em sua própria cláusula SETTINGS; um valor herdado de um perfil ou sessão, ou definido na própria instrução INSERT / CREATE, não é propagado para o SELECT de origem — a mesma regra de não propagação aplicável a qualquer outra configuração.

filter não é um mecanismo de controle de acesso e não deve ser usado como substituto de políticas de segurança em nível de linha ou da configuração additional_table_filters. Ele apenas adiciona uma cláusula WHERE à subconsulta que encapsula a consulta; portanto, os dados subjacentes ainda são lidos e processados antes da aplicação do filtro — uma consulta pode observar as linhas excluídas pelo filtro durante o processamento (por exemplo, com throwIf para vazar informações pelo caminho de erro). Use segurança em nível de linha ou additional_table_filters quando o objetivo for restringir quais linhas um usuário pode acessar.

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 │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

format

Substitui o FORMAT da consulta, tanto na entrada quanto na saída. Tem precedência sobre o formato especificado na consulta e na extensão do arquivo. As configurações mais específicas input_format e output_format têm precedência sobre esta configuração genérica format nas respectivas direções.

framing_output_format

Permite multiplexar diferentes partes da resposta da consulta em um único fluxo: fragmentos de dados, totais e extremos, pacotes de progresso, eventos de perfil (métricas) e logs do servidor — tudo o que o protocolo nativo oferece. Os formatos de enquadramento são independentes dos formatos de saída: eles encapsulam os bytes produzidos por qualquer formato de saída, separando e, potencialmente, codificando esses fragmentos de bytes. A concatenação das cargas úteis de todos os pacotes data, totals e extremes é exatamente o que o formato de saída teria produzido sem enquadramento. Pacotes auxiliares (progresso, logs, eventos de perfil e exceções) são representados em JSON. Há uma exceção deliberada: um formato de saída que omite totais e extremos em sua saída simples por não conseguir representá-los (a família JSONCompactEachRow) os emite com enquadramento, nos pacotes totals e extremes. Para esses formatos, a concatenação somente dos pacotes data corresponde exatamente à saída sem enquadramento, e os pacotes totals e extremes contêm linhas adicionais que a saída sem enquadramento não inclui. Os logs do servidor são incluídos se a configuração send_logs_level estiver definida, e os eventos de perfil serão incluídos se a configuração send_profile_events estiver habilitada (eles são enviados no máximo uma vez a cada interactive_delay microssegundos, e os pacotes de progresso também são limitados por interactive_delay). Um fluxo bem-sucedido termina com um pacote progress final que contém os contadores finais (result_rows, result_bytes, memory_usage), gravado após os pacotes finais log e profile_events emitidos pelo logging de término da consulta, assim como o pacote de progresso final do protocolo nativo. Em caso de falha, o pacote exception é o último pacote — com uma exceção: quando a falha ocorre depois que parte do fluxo de pacotes já foi produzida na resposta e não pode mais ser descartada (a gravação de um pacote falha parcialmente, a entrega do próprio pacote exception falha ou o fluxo de resposta falha durante a liberação ou o fechamento), o enquadramento falha de forma segura — o fluxo é encerrado sem um pacote exception terminal, e o cliente recebe uma resposta truncada e uma conexão HTTP abortada, em vez de um pacote terminal analisável. Nada é acrescentado após um fluxo parcial de pacotes; portanto, um corpo de erro HTTP simples nunca é misturado a ele. Tudo o que uma consulta habilita somente por meio de sua própria cláusula SETTINGS — um formato de enquadramento, send_logs_level ou send_profile_events — só é conhecido depois que a consulta é analisada; portanto, os logs e eventos de perfil correspondentes são capturados apenas a partir da execução da consulta. Os logs e eventos de perfil das fases de análise sintática, planejamento e análise são capturados somente quando a configuração vem da sessão ou da URL. Por exemplo, uma consulta que falha durante a análise (como ao fazer referência a uma tabela desconhecida) e habilita send_logs_level apenas em sua cláusula SETTINGS entrega somente o pacote exception, e não os logs da fase de análise; defina send_logs_level na sessão ou na URL para capturá-los. A mesma ressalva quanto à descoberta tardia se aplica a send_logs_source_regexp: a fila de logs filtra as entradas por origem no momento em que cada uma é capturada; portanto, uma expressão regular definida apenas na própria cláusula SETTINGS da consulta passa a valer a partir da execução da consulta. Os pacotes log das fases de análise sintática, planejamento e análise são filtrados pelo valor da configuração na sessão ou na URL (não são filtrados quando ela não está definida nesses locais); portanto, podem incluir origens que não correspondem à expressão regular no nível da consulta. Por outro lado, entradas descartadas por uma expressão regular mais restritiva na sessão ou na URL não são recuperadas por uma expressão mais ampla no nível da consulta. Defina send_logs_source_regexp na sessão ou na URL para filtrar todo o ciclo de vida da consulta. Atualmente, a configuração se aplica ao protocolo HTTP e é ignorada por outras interfaces. Valores possíveis:

None - encaminha de forma transparente tudo o que se aplica (dados, totais, extremos, progresso) ao formato de saída e ignora o que não se aplica (métricas, logs), mantendo o comportamento padrão.
EventStream - enquadra os pacotes como eventos HTTP enviados pelo servidor (text/event-stream). Cada pacote é enviado como um evento com o nome correspondente: data, totals, extremes, progress, log, profile_events, exception. O progresso e outros pacotes auxiliares são enviados como JSON. Como eventos enviados pelo servidor usam um protocolo de texto que trata quebras de linha (incluindo retornos de carro, \r) como delimitadores, um bloco de dados formatados é codificado em Base64 em um único campo data do evento, que é decodificado para o payload totalmente formatado, com todas as quebras de linha; o Content-Type inclui o parâmetro payload=base64 para indicar isso. Qualquer formato de saída pode ser transportado dessa maneira com exatidão byte a byte, tanto texto quanto binário.
JSONEachPacketBase64 - cada pacote é um objeto JSON em uma linha separada, e os dados formatados são codificados em Base64, por exemplo, {"packet":"data","data":"eyJ4IjoxfQo="}. Adequado para formatos de saída binários.
JSONEachPacketString - cada pacote é um objeto JSON em uma linha separada, e os dados formatados são incluídos em uma string, por exemplo, {"packet":"data","data":"{\"x\":1}\n"}.

JSONEachPacketString insere os bytes do payload em uma string JSON sem validá-los nem recodificá-los. As colunas String e FixedString podem conter bytes arbitrários, portanto formatos de saída de texto (como JSONEachRow, TSV ou CSV) podem emitir UTF-8 inválido para esses valores — assim como o próprio JSONEachRow do ClickHouse faz com o padrão output_format_json_validate_utf8 = 0 —, e não há garantia de que o fluxo NDJSON resultante seja UTF-8 válido. Use JSONEachPacketBase64 para transportar bytes arbitrários com exatidão byte a byte. Exemplo:

curl "http://localhost:8123/?framing_output_format=JSONEachPacketString" -d "SELECT number FROM numbers(3) FORMAT JSONEachRow"

Resultado:

{"packet":"data","data":"{\"number\":\"0\"}\n{\"number\":\"1\"}\n{\"number\":\"2\"}\n"}
{"packet":"profile_events","profile_events":[{"host_name":"localhost","current_time":"2026-07-11 00:00:00","thread_id":"0","type":"increment","name":"SelectedRows","value":"3"}]}
{"packet":"progress","progress":{"read_rows":"3","read_bytes":"24","total_rows_to_read":"3","result_rows":"3","result_bytes":"24","elapsed_ns":"1265958"}}

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).

input_format

Substitui o formato de entrada da consulta. Tem precedência sobre o formato especificado na consulta.

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.

legacy_join_size_limits_trigger_spilling

Restaura o comportamento que max_rows_in_join e max_bytes_in_join tinham antes de o limiar de spill se tornar o gatilho, no que diz respeito à parte de um join executada em disco: atingir um deles faz o join fazer mais spill em vez de interromper a consulta. Nesse caso, join_algorithm = 'grace_hash' faz spill apenas com base nesses dois e ignora completamente max_bytes_before_external_join, inclusive quando é zero. hash / parallel_hash continuam indo para o disco ao atingir o limiar de spill e, a partir daí, fazem spill por qualquer um dos dois; sua fase em memória segue tratando os dois como limite rígido, como antes. Voltado a consultas escritas conforme o significado anterior dessas duas settings; compatibility a habilita automaticamente. Um servidor anterior a esta setting aplica o significado antigo e não há como alterar isso; por isso, com serialize_query_plan = 1, um join cujo spill depende do novo significado simplesmente não é enviado a esse servidor: a consulta falha em vez de rodar silenciosamente sob o outro contract. Ativar esta setting faz essas consultas funcionarem nas duas versões, com o significado antigo em ambos os lados.

limit

Define o número máximo de linhas a serem retornadas pelo resultado da consulta. Ajusta o valor definido pela cláusula LIMIT. O valor é encaminhado a LIMIT e aceita tudo o que LIMIT aceita, incluindo valores negativos (contados a partir do fim do resultado) e frações em (0, 1) (interpretadas como uma proporção do resultado). Valores possíveis:

0 — O número de linhas não é limitado.
Inteiro positivo — número exato de linhas.
Inteiro negativo — retorna as últimas N linhas.
Número real no intervalo aberto (0, 1) — retorna essa fração do resultado.

Essa configuração afeta consultas SELECT / UNION que produzem resultados. Em uma consulta de escrita (INSERT … SELECT, CREATE … AS SELECT), ela só tem efeito quando o SELECT de origem a inclui em sua própria cláusula SETTINGS; um valor herdado de um perfil ou sessão, ou definido na própria instrução INSERT / CREATE, não é propagado para o SELECT de origem — a mesma regra de não propagação aplicável a qualquer outra configuração.

load_marks_asynchronously

Carrega marcas do MergeTree de forma assíncrona em um pool de threads em segundo plano (consulte a configuração do servidor load_marks_threadpool_pool_size), para que as marcas de todos os fluxos sejam carregadas em paralelo. Caso contrário, as marcas são carregadas de forma síncrona, um fluxo após o outro, o que é lento em discos remotos para colunas com muitos subfluxos, como JSON.

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. Ao ativá-la, as configurações que controlam recursos ainda não compatíveis com planos de consulta distribuída são ajustadas automaticamente:

enable_parallel_replicas = 0 e automatic_parallel_replicas_mode = 0 — o plano distribuído faz sua própria distribuição de trabalho;
correlated_subqueries_use_in_memory_buffer = 0;
compile_expressions = 0;
query_plan_direct_read_from_text_index = 0.

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.

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 ignorar antes de começar a retornar linhas da consulta. Ajusta o deslocamento definido pela cláusula OFFSET. O valor é repassado para OFFSET e aceita tudo o que OFFSET aceita, incluindo valores negativos e frações em (0, 1). Valores possíveis:

0 — Nenhuma linha é ignorada.
Inteiro positivo.
Inteiro negativo.
Um número real no intervalo aberto (0, 1) — ignora essa fração do resultado.

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 │
└─────┘

Esta configuração afeta consultas SELECT / UNION que produzem resultados. Em uma consulta de gravação (INSERT … SELECT, CREATE … AS SELECT), ela só tem efeito quando o SELECT de origem a inclui em sua própria cláusula SETTINGS; um valor herdado de um perfil ou de uma sessão, ou definido na própria instrução INSERT / CREATE, não é propagado para o SELECT de origem — a mesma regra de não propagação aplicável a qualquer outra configuração.

order

Adiciona uma cláusula ORDER BY à consulta, encapsulando-a em uma subconsulta. Aceita uma lista arbitrária de expressões. Esta é uma configuração de construção de consultas aplicada pelo mecanismo à consulta analisada sintaticamente (encapsulando-a como uma tabela derivada). Portanto, ela se combina com a consulta existente e funciona em todos os protocolos: pode ser fornecida por meio de um parâmetro de URL HTTP, de uma cláusula SETTINGS na consulta ou de um perfil de usuário. Ela define a ordenação de consultas SELECT / UNION que produzem resultados. Para uma consulta de gravação (INSERT … SELECT, CREATE … AS SELECT), só tem efeito quando o SELECT de origem a inclui em sua própria cláusula SETTINGS; um valor herdado de um perfil ou de uma sessão, ou definido na própria instrução INSERT / CREATE, não é propagado para o SELECT de origem — a mesma regra de não propagação aplicável a qualquer outra configuração.

output_format

Substitui o formato de saída da consulta. Tem precedência sobre o formato especificado na consulta, na extensão do arquivo ou por meio de default_format.

página

Define o número da página dos resultados paginados. Equivale a offset = limit * (page - 1). Só pode ser especificado quando limit está definido e offset não está. As páginas são indexadas a partir de 1. Oferece o mesmo suporte a valores negativos ou fracionários que limit e offset. Esta é uma configuração de construção de consultas aplicada pelo mecanismo à consulta analisada sintaticamente (encapsulando-a como uma tabela derivada). Portanto, ela se combina à consulta existente e funciona em todos os protocolos: pode ser fornecida pelo parâmetro de URL HTTP, por uma cláusula SETTINGS na consulta ou por um perfil de usuário. Ela molda consultas SELECT / UNION que produzem resultados. Em uma consulta de gravação (INSERT … SELECT, CREATE … AS SELECT), ela só tem efeito quando o SELECT de origem a inclui em sua própria cláusula SETTINGS; um valor herdado de um perfil ou sessão, ou definido na própria instrução INSERT / CREATE, não é propagado para o SELECT de origem — a mesma regra de não propagação aplicável a qualquer outra configuração.

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. A renomeação grava na fonte; portanto, uma consulta que lê os arquivos com essa opção definida requer o privilégio WRITE ON FILE, além de READ ON FILE. DESCRIBE não compila o pipeline de leitura de dados que realiza a renomeação e, portanto, requer apenas READ ON FILE.

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. ...

resumable_backup_from_snapshot

Habilita a retomada de BACKUP FROM SNAPSHOT: uma tentativa que falhou pode ser executada novamente sem copiar outra vez as entradas dos lotes já concluídos. Disponível apenas no ClickHouse Cloud, para destinos S3 e AzureBlobStorage no formato de diretório. Habilitá-la em compilações de código aberto do ClickHouse, nas quais o próprio BACKUP FROM SNAPSHOT não está disponível, faz com que BACKUP falhe com WRONG_BACKUP_SETTINGS.

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ção

run_query_in_background

Se habilitada, o servidor agenda a consulta em segundo plano, retorna imediatamente um resultado vazio e bem-sucedido e executa a consulta até a conclusão, independentemente do que aconteça com a conexão. Uma consulta em segundo plano não sobrevive à reinicialização do servidor. Durante o encerramento, ela segue as mesmas configurações do servidor que uma consulta em primeiro plano: shutdown_wait_unfinished_queries define se ela será cancelada ou se o servidor aguardará sua conclusão (as entradas enfileiradas são descartadas em ambos os casos, sem uma entrada em system.query_log), e shutdown_wait_unfinished limita por quanto tempo o servidor espera. Acompanhe a consulta pelo query_id: em system.processes enquanto estiver em execução e em system.query_log depois que for concluída e a entrada no log de consultas for gravada. Aplica-se a consultas recebidas pelos protocolos TCP nativo e HTTP. Em HTTP, passe a configuração como parâmetro de URL. Ela não pode ser alterada com SET; habilite-a por consulta ou no nível de usuário ou perfil. O principal caso de uso é um INSERT ... SELECT demorado que não pode ser perdido caso a conexão do cliente seja interrompida.

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

Encapsula a consulta como uma subconsulta com uma lista explícita de expressões SELECT. Quando não está vazia, a consulta que produz resultados é encapsulada como SELECT <expr_list> FROM (<query>). Esta é uma configuração de construção de consultas aplicada pelo mecanismo à consulta convertida em sua representação interna (encapsulando-a como uma tabela derivada). Portanto, ela se combina à consulta existente e funciona em todos os protocolos: pode ser fornecida pelo parâmetro de URL HTTP, por uma cláusula SETTINGS na consulta ou por um perfil de usuário. Ela define a estrutura de consultas SELECT / UNION que produzem resultados. Em uma consulta de gravação (INSERT … SELECT, CREATE … AS SELECT), ela só tem efeito quando o SELECT de origem a inclui em sua própria cláusula SETTINGS; um valor herdado de um perfil ou sessão, ou definido na própria instrução INSERT / CREATE, não é propagado para o SELECT de origem — a mesma regra de não propagação aplicável a qualquer outra configuração.

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_query_ids_history_size

O número máximo de IDs de consulta mantidos no histórico local da sessão, exposto pela tabela de sistema system.session_query_ids. O ID de consulta de cada consulta não interna executada na sessão é registrado nessa tabela no início da consulta; quando o histórico ultrapassa esse tamanho, as entradas mais antigas são removidas primeiro. O valor é lido no início da consulta, antes que ela seja convertida. Portanto, uma cláusula SETTINGS na própria consulta não afeta se ela será registrada; use SET, um parâmetro de URL HTTP ou um perfil de configurações. Valores possíveis:

Inteiro positivo.
0 — O registro é desabilitado; as entradas registradas anteriormente permanecem na tabela.

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

Adiciona uma cláusula ORDER BY simples à consulta, encapsulando-a em uma subconsulta. Aceita uma lista separada por vírgulas de identificadores ou referências posicionais a colunas (inteiros positivos), com o prefixo opcional + (ASC) ou - (DESC). Exemplo: sort=a,-b ordena por a em ordem crescente e por b em ordem decrescente; sort=1,-2 ordena pela primeira coluna em ordem crescente e pela segunda em ordem decrescente. Não pode ser combinado com order. Essa é uma configuração de construção de consultas aplicada pelo mecanismo à consulta convertida (encapsulando-a como uma tabela derivada). Portanto, ela é combinada com a consulta existente e funciona em todos os protocolos: pode ser fornecida pelo parâmetro de URL HTTP, por uma cláusula SETTINGS na consulta ou por um perfil de usuário. Ela se aplica a consultas SELECT / UNION que produzem resultados. Em uma consulta de gravação (INSERT … SELECT, CREATE … AS SELECT), só tem efeito quando o SELECT de origem a inclui em sua própria cláusula SETTINGS; um valor herdado de um perfil ou sessão, ou definido na própria instrução INSERT / CREATE, não é propagado para o SELECT de origem — a mesma regra de não propagação aplicável a qualquer outra configuraçã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.

statistics_max_set_size_for_exact_selectivity_estimation

O tamanho máximo do conjunto no lado direito do operador IN para o qual o estimador de seletividade determina os intervalos exatos abrangidos pelo conjunto. Essa determinação requer um Field por elemento, uma ordenação e uma sondagem de estatísticas por elemento, o que, em conjuntos grandes, domina o planejamento da consulta. Acima desse limite, o estimador determina a seletividade a partir do tamanho do conjunto e de seu intervalo delimitador, em uma única passagem linear pelo conjunto, sem ordenação nem sondagens de estatísticas por elemento. Zero significa sem limite.

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.

time_series_prefer_recent_samples_table

Leia da tabela de amostras recentes de uma tabela TimeSeries, em vez da tabela principal de amostras, quando todo o intervalo de tempo solicitado estiver dentro da janela de TTL da tabela de amostras recentes (consulte a configuração recent_samples_ttl_seconds do motor de tabela TimeSeries).

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.

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

workload_admission_timeout_ms

O tempo máximo que uma consulta aguarda para ser admitida pelo agendamento de workload antes de falhar sem iniciar. Ele limita a espera combinada por um query slot (de um recurso CREATE RESOURCE ... (QUERY), limitado pelo max_concurrent_queries do workload) e por uma reserva de memória (de um recurso CREATE RESOURCE ... (MEMORY RESERVATION) em conjunto com a configuração reserve_memory). Ambos são adquiridos antes de a consulta começar a ser executada, portanto esta é a única forma de limitar essa espera prévia à execução: max_execution_time ainda não se aplica, pois a consulta não foi iniciada. Quando o timeout expira, a consulta falha com um de dois erros distintos, conforme o recurso pelo qual ela estava aguardando: QUERY_SLOT_ACQUISITION_TIMEOUT para um query slot ou MEMORY_RESERVATION_ACQUISITION_TIMEOUT para uma reserva de memória. Valores possíveis:

Inteiro positivo — timeout em milissegundos.
0 — Timeout infinito: a consulta aguarda indefinidamente pela admissão (padrão). Ainda assim, ela pode ser rejeitada imediatamente quando o limite max_waiting_queries do workload é atingido.

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

​adaptive_aggregator_freeze_threshold

​adaptive_aggregator_freeze_threshold_bytes

​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

​cascades_aggregation_pushdown

​checksum_on_read

​compressão

​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

​explain_syntax_single_record

​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

​filter

​final

​finalize_projection_parts_synchronously

​flatten_nested

​format

​framing_output_format

​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

​input_format

​interactive_delay

​intersect_default_mode

​least_greatest_legacy_null_behavior

​legacy_column_name_of_tuple_literal

​legacy_join_size_limits_trigger_spilling

​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

​order

​output_format

adaptive_aggregator_freeze_threshold

adaptive_aggregator_freeze_threshold_bytes

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

cascades_aggregation_pushdown

checksum_on_read

compressão

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

explain_syntax_single_record

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

filter

final

finalize_projection_parts_synchronously

flatten_nested

format

framing_output_format

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

input_format

interactive_delay

intersect_default_mode

least_greatest_legacy_null_behavior

legacy_column_name_of_tuple_literal

legacy_join_size_limits_trigger_spilling

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

order

output_format