Configurações globais
common de nível superior:
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.Compressã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
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
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
Variantsão lidos como o tipo Python correspondente. Os inserts nativos selecionam um membro com base no tipo do valor em Python. - Quando vários membros de
Variantcorrespondem ao mesmo tipo Python, envolva o valor comclickhouse_connect.datatypes.dynamic.typed_variant(value, "TypeName")para selecionar o membro explicitamente. - O formato de leitura
typeddeVariantretorna objetosTypedVariant(value, type_name)e preserva o tipo do membro de origem. Habilite-o comquery_formats={"Variant": "typed"}. - Os valores de
Dynamicsão lidos como o tipo Python correspondente. No momento, os inserts são enviados por meio da representação em string. - Os valores de
JSONpodem 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,DynamicouJSONretornam o tipo concreto da subcoluna.
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.