Configurações globais
common de nível superior:
Essas configurações comuns
autogenerate_session_id, product_name e readonly devem sempre ser modificadas antes de criar um cliente com o método clickhouse_connect.get_client. Alterar essas configurações após a criação do cliente não afeta o comportamento dos clientes existentes.| Setting Name | Default | Options | Description |
|---|---|---|---|
| autogenerate_session_id | True | True, False | Gera automaticamente um novo ID de sessão UUID(1) (se não for fornecido) para cada sessão do cliente. Se nenhum ID de sessão for fornecido (seja no nível do cliente ou da consulta), o ClickHouse gerará um ID interno aleatório para cada consulta. |
| dict_parameter_format | ’json' | 'json’, ‘map’ | Controla se consultas parametrizadas convertem um dicionário Python em sintaxe JSON ou map do ClickHouse. json deve ser usado para inserts em colunas JSON; map, para colunas map do ClickHouse. |
| invalid_setting_action | ’error' | 'drop’, ‘send’, ‘error’ | Ação a ser tomada quando uma configuração inválida ou readonly é fornecida (seja para a sessão do cliente ou para a consulta). Se for drop, a configuração será ignorada; se for send, a configuração será enviada ao ClickHouse; se for error, um ProgrammingError será gerado no lado do cliente. |
| max_connection_age | 600 | Número máximo de segundos em que uma connection HTTP Keep alive será mantida aberta/reutilizada. Isso evita concentrar connections em um único nó do ClickHouse atrás de um load balancer/proxy. O padrão é 10 minutos. | |
| product_name | Uma String passada com a consulta ao ClickHouse para rastrear o aplicativo que usa o ClickHouse Connect. Deve estar no formato <nome do produto;&gl/<versão do produto>. | ||
| readonly | 0 | 0, 1 | Configuração implícita de ClickHouse “read_only” para versões anteriores à 19.17. Pode ser definida para corresponder ao valor “read_only” de configurações do ClickHouse, permitindo a operação com versões muito antigas do ClickHouse. |
| send_os_user | True | True, False | Inclui o usuário do sistema operacional detectado nas informações do cliente enviadas ao ClickHouse (string HTTP user-agent). |
| send_integration_tags | True | True, False | Inclui as bibliotecas/versões de integração usadas (por exemplo, Pandas/SQLAlchemy/etc.) nas informações do cliente enviadas ao ClickHouse (string HTTP user-agent). |
| use_protocol_version | True | True, False | Usa a versão do protocol do cliente. Isso é necessário para colunas DateTime com timezone, mas não funciona com a versão atual do chproxy. |
| max_error_size | 1024 | Número máximo de caracteres retornados em mensagens de error do cliente. Use 0 nessa configuração para obter a mensagem de error completa do ClickHouse. O padrão é 1024 caracteres. | |
| http_buffer_size | 10MB | Tamanho (em bytes) do buffer “em memória” usado para consultas HTTP streaming. | |
| preserve_pandas_datetime_resolution | False | True, False | Quando True e com pandas 2.x, preserva a resolution do dtype datetime64/timedelta64 (por exemplo, ‘s’, ‘ms’, ‘us’, ‘ns’). Se False (ou no pandas <2.x), faz a coerção para resolução de nanossegundos (‘ns’) por compatibilidade. |
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 parâmetro compress ao chamar o método factory clickhouse_connect.get_client. Por padrão, compress é definido como True, o que acionará as configurações padrão de compressão. Para consultas executadas com os métodos de cliente query, query_np e query_df, o ClickHouse Connect adicionará o header Accept-Encoding com
as codificações lz4, zstd, br (brotli, se a biblioteca brotli estiver instalada), gzip e deflate às consultas executadas com o método de cliente query (e, indiretamente, query_np e query_df). (Na maioria das requisições, o servidor ClickHouse
retornará um payload comprimido com zstd.) Para inserção, por padrão, o ClickHouse Connect comprimirá blocos de inserção com compressão lz4 e enviará o header HTTP Content-Encoding: lz4.
O parâmetro compress de get_client também pode ser definido como um método de compressão específico, entre lz4, zstd, br ou gzip. Esse método será então usado tanto para inserção quanto para resultados de consultas (se tiver suporte no servidor ClickHouse). As bibliotecas de compressão zstd e lz4 necessárias agora são instaladas por padrão com o ClickHouse Connect. Se br/brotli for especificado, a biblioteca brotli deverá ser instalada separadamente.
Observe que os métodos de cliente raw* não usam a compressão especificada na configuração do cliente.
Também recomendamos não usar compressão gzip, pois ela é significativamente mais lenta do que as alternativas, tanto para comprimir quanto para descomprimir dados.
Suporte a proxy HTTP
urllib3. Ele reconhece as variáveis de ambiente padrão HTTP_PROXY e HTTPS_PROXY. Observe que o uso dessas variáveis de ambiente se aplicará a qualquer cliente criado com o método clickhouse_connect.get_client. Como alternativa, para configurar cada cliente individualmente, você pode usar os argumentos http_proxy ou https_proxy no método get_client. Para mais detalhes sobre a implementação do suporte a proxy HTTP, consulte a documentação do urllib3.
Para usar um proxy SOCKS, você pode passar um urllib3 SOCKSProxyManager como argumento pool_mgr para get_client. Observe que isso exigirá a instalação da biblioteca PySocks, diretamente ou usando a opção [socks] da dependência urllib3.
tipo de dado JSON “antigo”
Object (ou Object('json')) está descontinuado e deve ser evitado em um ambiente de produção. O ClickHouse Connect continua oferecendo suporte limitado a esse tipo de dado por compatibilidade com versões anteriores. Observe que esse suporte não inclui consultas que devem retornar valores JSON de “nível superior” ou “pai” como dicionários, ou equivalente, e essas consultas resultarão em uma exceção.
Tipos de dados Variant/Dynamic/JSON “novos” (recurso experimental)
clickhouse-connect oferece suporte experimental aos novos tipos do ClickHouse — também experimentais — Variant, Dynamic e JSON.
Notas de uso
- Os dados JSON podem ser inseridos na forma de um dicionário Python ou de uma string JSON contendo um objeto JSON
{}. Outras formas de dados JSON não são aceitas. - As consultas que usam subcolunas/caminhos para esses tipos retornarão o tipo da subcoluna.
- Consulte a documentação principal do ClickHouse para ver outras notas de uso.
Limitações conhecidas
- Cada um desses tipos deve ser habilitado nas configurações do ClickHouse antes do uso.
- O “novo” tipo JSON está disponível a partir do lançamento 24.8 do ClickHouse
- Devido a alterações no formato interno,
clickhouse-connectsó é compatível com tipos Variant a partir do lançamento 24.7 do ClickHouse - Os objetos JSON retornados incluirão apenas a quantidade de elementos definida por
max_dynamic_paths(cujo valor padrão é 1024). Isso será corrigido em um lançamento futuro. - Inserções em colunas
Dynamicsempre usarão a representação em String do valor em Python. Isso será corrigido em um lançamento futuro, assim que https://github.com/ClickHouse/ClickHouse/issues/70395 for corrigido. - A implementação dos novos tipos não foi otimizada em código C, portanto o desempenho pode ser um pouco mais lento do que com tipos de dados mais simples e já consolidados.