Opções adicionais

Opções adicionais para o ClickHouse Connect

O ClickHouse Connect oferece diversas opções adicionais para casos de uso avançados.

​

Configurações globais

Há algumas configurações que controlam o comportamento global do ClickHouse Connect. Elas podem ser acessadas no pacote common de nível superior:

from clickhouse_connect import common

common.set_setting("autogenerate_session_id", False)
print(common.get_setting("invalid_setting_action"))
# Output: error

Configure as configurações de criação do cliente antes de criar clientes. Configurações como IDs de sessão/consulta gerados e a identificação do produto são copiadas para o estado específico do cliente, portanto, alterações globais posteriores não atualizam clientes existentes. As configurações de binding e insert funcionam de modo diferente. naive_datetime_binding e dict_parameter_format são lidas quando os parâmetros são associados. naive_datetime_insert é lida quando uma coluna em um insert nativo que contém objetos datetime do Python ou strings ISO DateTime64 é serializada. Alterações nessas configurações afetam clientes existentes. Um contexto de insert reutilizável usa o valor atual de naive_datetime_insert em cada insert.

As seguintes configurações globais estão definidas atualmente:

Nome da configuração	Padrão	Opções	Descrição
autogenerate_session_id	True	True, False	Gera um ID de sessão UUID para cada cliente síncrono, a menos que um ID de sessão seja fornecido. Por padrão, a fábrica assíncrona substitui esse valor por False.
autogenerate_query_id	True	True, False	Gera um ID de consulta UUID para cada solicitação, a menos que um seja fornecido.
dict_parameter_format	"json"	"json", "map"	Formata dicionários Python usados no binding de parâmetros como JSON ou literais map do ClickHouse.
invalid_setting_action	"error"	"drop", "send", "error"	Ação para uma configuração que o servidor reporta como readonly. drop a ignora, send a encaminha e error gera ProgrammingError. Configurações ausentes de system.settings para o usuário atual, como uma configurada como CHANGEABLE_IN_READONLY em uma função, são encaminhadas para que o servidor possa aceitá-las ou rejeitá-las, a menos que a ação seja drop.
naive_datetime_binding	"wall"	"wall", "legacy"	Controla o binding de parâmetros de consulta datetime naive. wall formata datetimes naive literalmente. legacy restaura o comportamento anterior de conversão para o horário local do host. Anexe tzinfo para preservar um instante.
naive_datetime_insert	"local"	"local", "server"	Controla inserts de objetos Python com valores datetime naive em DateTime e DateTime64, e de strings ISO naive aceitas por DateTime64. local usa o fuso horário do processo para compatibilidade. server usa o fuso horário declarado da coluna e, em seguida, o fuso horário do servidor. Date e Date32 usam a própria data de calendário do valor. Colunas NumPy e Pandas com dtype datetime64 não são alteradas.
max_connection_age	600	Qualquer número de segundos	Tempo máximo de reutilização de uma conexão HTTP keep-alive. A rotação ajuda a distribuir conexões entre nós atrás de um balanceador de carga.
native_codec	"python"	"python", "rust", "rust_strict"	Codec padrão para o tráfego no formato Native gerenciado pelo cliente, substituível por cliente. A variável de ambiente CLICKHOUSE_CONNECT_NATIVE_CODEC inicializa essa configuração na importação. Veja Rust codec.
product_name	""	Qualquer string	Identificador do produto adicionado às informações do cliente. Use um valor como "my-product/1.0".
readonly	0	0, 1	No-op obsoleto mantido para compatibilidade com a versão 1.x. O cliente lê diretamente a configuração readonly do servidor.
send_os_user	True	True, False	Inclui o usuário detectado do sistema operacional nas informações do cliente.
send_integration_tags	True	True, False	Inclui as integrações usadas pelo cliente, como Pandas ou SQLAlchemy, no User-Agent HTTP.
use_protocol_version	True	True, False	Negocia a versão do protocolo do cliente usada por recursos do formato Native, como os metadados de fuso horário da coluna DateTime. Desative esta opção para proxies que rejeitam client_protocol_version.
max_error_size	1024	Qualquer inteiro não negativo	Número máximo de caracteres incluídos em um erro do cliente. Use 0 para a mensagem completa.
http_buffer_size	10485760	Bytes	Tamanho do buffer na memória para consultas HTTP de streaming; o padrão é 10 MiB.

​

Compressão

O ClickHouse Connect oferece suporte à compressão de resposta com lz4, zstd, brotli, gzip e deflate. As inserções Native oferecem suporte a lz4, zstd, brotli e gzip. A compressão reduz a transferência pela rede em troca de maior uso de CPU.

Para receber dados comprimidos, a configuração enable_http_compression do servidor ClickHouse deve estar definida como 1, ou o usuário deve ter permissão para alterar essa configuração por consulta.

A compressão é controlada pelo argumento compress de get_client e get_async_client. O valor padrão, True, anuncia todas as codificações de resposta disponíveis e comprime blocos de inserção Native com lz4. Defina compress=False para desativar a compressão ou passe "lz4", "zstd", "br" ou "gzip" para solicitar um método específico.

Os métodos raw do cliente não usam a configuração compress no nível do cliente. raw_query e raw_stream retornam dados não comprimidos, e raw_insert usa seu próprio argumento compression, que descreve a compressão já aplicada ao payload.

O suporte a lz4 e zstd é instalado com o ClickHouse Connect. No Python 3.14, o zstd usa o módulo compression.zstd da biblioteca padrão. Do Python 3.10 ao 3.13, usa-se backports.zstd. Um interpretador CPython 3.14+ personalizado, compilado sem suporte a zstd, ainda pode ser importado; nesse caso, o zstd é removido dos métodos disponíveis, e um erro só é gerado quando zstd é solicitado explicitamente. Brotli é opcional e deve ser instalado separadamente antes de usar compress="br".

Em geral, o gzip é mais lento que lz4 ou zstd para workloads do ClickHouse.

​

Suporte a proxy HTTP

O ClickHouse Connect reconhece as variáveis de ambiente padrão HTTP_PROXY e HTTPS_PROXY. Essas variáveis se aplicam a todos os clientes do processo. Para configurar um proxy por cliente, passe http_proxy ou https_proxy para get_client ou get_async_client.

O cliente síncrono usa urllib3. Para usar um proxy SOCKS, instale o PySocks e passe um urllib3.contrib.socks.SOCKSProxyManager como argumento pool_mgr para get_client. pool_mgr não é compatível com o cliente assíncrono.

​

Tipos de dados Variant, Dynamic e JSON

O ClickHouse Connect oferece suporte aos atuais tipos Variant, Dynamic e JSON do ClickHouse. O tipo legado Object('json') foi removido no clickhouse-connect 0.14 e não é compatível.

​

Notas de uso

• Os valores de Variant são lidos como o tipo Python correspondente. As inserções Native selecionam um membro com base no tipo do valor em Python.
• Quando vários membros de Variant correspondem ao mesmo tipo Python, envolva o valor com clickhouse_connect.datatypes.dynamic.typed_variant(value, "TypeName") para selecionar o membro explicitamente.
• O formato de leitura typed de Variant retorna objetos TypedVariant(value, type_name) e preserva o tipo do membro de origem. Habilite-o com query_formats={"Variant": "typed"}.
• Os valores de Dynamic são lidos como o tipo Python correspondente. No momento, os inserts são enviados por meio da representação em string.
• Os valores de JSON podem ser inseridos como dicionários Python ou strings de objeto JSON. O formato de leitura padrão retorna dicionários; use o formato de leitura "string" para retornar strings JSON.
• Consultas que selecionam uma subcoluna de Variant, Dynamic ou JSON retornam o tipo concreto da subcoluna.

Os nomes de tipo Variant, Dynamic e JSON convertidos usam a ordem canônica de argumentos do ClickHouse. Os membros de Variant são ordenados e deduplicados pelo nome de tipo canônico, inclusive quando um Variant está aninhado dentro de outro tipo. Os nomes de tipo Dynamic mantêm o argumento max_types, de modo que uma coluna Dynamic(max_types=5) é reportada como Dynamic(max_types=5) em vez de Dynamic. Os typed paths e as regras de skip de JSON são ordenados, os skip paths simples duplicados são removidos, as duplicatas de regular expression são preservadas e os limites padrão explícitos são omitidos. Um tipo JSON convertido expõe as regras decodificadas por meio de skip_paths e skip_regexps. Seu atributo skips contém as expressões canônicas correspondentes do ClickHouse.

Alguns valores armazenados na área shared-data de colunas JSON ou Dynamic usam tipos que o cliente ainda não consegue decodificar. Esses valores são retornados como bytes brutos. Esses tipos complexos também usam o caminho de conversão em pure Python, portanto podem ser mais lentos do que os tipos escalares já estabelecidos.