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