Integração em Python com ClickHouse Connect

Introdução

ClickHouse Connect é um driver principal de banco de dados que fornece interoperabilidade com uma ampla variedade de aplicações Python.

A interface principal é o objeto Client no pacote clickhouse_connect.driver. Esse pacote principal também inclui várias classes auxiliares e funções utilitárias usadas para se comunicar com o servidor ClickHouse, além de implementações de contexto para o gerenciamento avançado de consultas de inserção e seleção.
O pacote clickhouse_connect.datatypes fornece uma implementação base e subclasses para todos os tipos de dados não experimentais do ClickHouse. Sua funcionalidade principal é a serialização e desserialização de dados do ClickHouse no formato colunar binário “Native” do ClickHouse, usado para garantir o transporte mais eficiente entre o ClickHouse e as aplicações cliente.
As classes Cython/C no pacote clickhouse_connect.cdriver otimizam algumas das serializações e desserializações mais comuns, proporcionando um desempenho significativamente melhor em comparação com Python puro.
Há um dialeto SQLAlchemy no pacote clickhouse_connect.cc_sqlalchemy, baseado nos pacotes datatypes e dbi. Essa implementação oferece suporte à funcionalidade Core do SQLAlchemy, incluindo consultas SELECT com JOINs (INNER, LEFT OUTER, FULL OUTER, CROSS), cláusulas WHERE, ORDER BY, LIMIT/OFFSET, operações DISTINCT, instruções lightweight DELETE com condições WHERE, introspecção de tabelas e operações DDL básicas (CREATE TABLE, CREATE/DROP DATABASE). Embora não ofereça suporte a recursos avançados de ORM nem a recursos avançados de DDL, ela fornece recursos robustos de consulta adequados para a maioria das cargas de trabalho analíticas no banco de dados ClickHouse voltado para OLAP.
O driver principal e a implementação ClickHouse Connect SQLAlchemy são o método preferido para conectar o ClickHouse ao Apache Superset. Use a conexão de banco de dados ClickHouse Connect ou a string de conexão do dialeto SQLAlchemy clickhousedb.

Esta documentação está atualizada até o lançamento 0.9.2 do clickhouse-connect.

O driver Python oficial ClickHouse Connect usa o protocolo HTTP para se comunicar com o servidor ClickHouse. Isso permite suporte a balanceadores de carga HTTP e funciona bem em ambientes corporativos com firewalls e proxies, mas oferece compressão e desempenho ligeiramente inferiores em comparação com o protocolo nativo baseado em TCP, além de não oferecer suporte a alguns recursos avançados, como cancelamento de consultas. Para alguns casos de uso, você pode considerar usar um dos drivers Python da comunidade que usam o protocolo nativo baseado em TCP.

Requisitos e compatibilidade

Python		Plataforma¹		ClickHouse		SQLAlchemy²		Apache Superset		Pandas		Polars
2.x, <3.9	❌	Linux (x86)	✅	<25.x³	🟡	<1.4.40	❌	<1.4	❌	≥1.5	✅	1.x	✅
3.9.x	✅	Linux (Aarch64)	✅	25.x³	🟡	≥1.4.40	✅	1.4.x	✅	2.x	✅
3.10.x	✅	macOS (x86)	✅	25.3.x (LTS)	✅	≥2.x	✅	1.5.x	✅
3.11.x	✅	macOS (ARM)	✅	25.6.x (Estável)	✅			2.0.x	✅
3.12.x	✅	Windows	✅	25.7.x (Estável)	✅			2.1.x	✅
3.13.x	✅			25.8.x (LTS)	✅			3.0.x	✅
				25.9.x (Estável)	✅

¹O ClickHouse Connect foi testado explicitamente nas plataformas listadas. Além disso, wheels binários não testados (com otimização em C) são gerados para todas as arquiteturas compatíveis com o excelente projeto cibuildwheel. Por fim, como o ClickHouse Connect também pode ser executado como Python puro, a instalação a partir do código-fonte deve funcionar em qualquer instalação recente do Python. ²O suporte ao SQLAlchemy é limitado às funcionalidades do Core (consultas, DDL básico). Recursos de ORM não são compatíveis. Consulte a documentação de SQLAlchemy Integration Support para mais detalhes. ³O ClickHouse Connect geralmente funciona bem com versões fora do intervalo oficialmente suportado.

Instalação

Instale o ClickHouse Connect a partir do PyPI via pip: pip install clickhouse-connect O ClickHouse Connect também pode ser instalado a partir do código-fonte:

faça git clone do repositório no GitHub.
(Opcional) execute pip install cython para compilar e habilitar as otimizações em C/Cython
vá para o diretório raiz do projeto com cd e execute pip install .

Política de suporte

Atualize para a versão mais recente do ClickHouse Connect antes de relatar qualquer problema. Os problemas devem ser registrados no projeto no GitHub. Os lançamentos futuros do ClickHouse Connect devem ser compatíveis com as versões do ClickHouse com suporte ativo no momento do lançamento. As versões do servidor ClickHouse com suporte ativo podem ser encontradas aqui. Se você não souber qual versão do servidor ClickHouse usar, leia esta discussão aqui. Nossa matriz de testes de CI testa as duas versões LTS mais recentes e as três versões estáveis mais recentes. No entanto, devido ao protocolo HTTP e ao número mínimo de mudanças incompatíveis entre os lançamentos do ClickHouse, o ClickHouse Connect geralmente funciona bem com versões de servidor fora da faixa oficialmente suportada, embora a compatibilidade com determinados tipos de dados avançados possa variar.

Uso básico

Obtenha os detalhes da conexão

Para se conectar ao ClickHouse via HTTP(S), você precisa das seguintes informações:

Parâmetro(s)	Descrição
`HOST` and `PORT`	Normalmente, a porta é 8443 ao usar TLS ou 8123 quando não se usa TLS.
`DATABASE NAME`	Por padrão, há um banco de dados chamado `default`; use o nome do banco de dados ao qual você deseja se conectar.
`USERNAME` and `PASSWORD`	Por padrão, o nome de usuário é `default`. Use o nome de usuário apropriado para o seu caso de uso.

Os detalhes do seu serviço do ClickHouse Cloud estão disponíveis no console do ClickHouse Cloud. Selecione um serviço e clique em Connect: Escolha HTTPS. Os detalhes de conexão são exibidos em um comando curl de exemplo. Se você estiver usando ClickHouse autogerenciado, os detalhes de conexão são definidos pelo administrador do seu ClickHouse.

Estabeleça uma conexão

Há dois exemplos de como se conectar ao ClickHouse:

Conectar-se a um servidor ClickHouse em localhost.
Conectar-se a um serviço do ClickHouse Cloud.

Use uma instância do cliente ClickHouse Connect para se conectar a um servidor ClickHouse no localhost:

import clickhouse_connect

client = clickhouse_connect.get_client(host='localhost', username='default', password='password')

Use uma instância do cliente ClickHouse Connect para se conectar a um serviço do ClickHouse Cloud:

Use os detalhes da conexão obtidos anteriormente. Os serviços do ClickHouse Cloud exigem TLS, então use a porta 8443.

import clickhouse_connect

client = clickhouse_connect.get_client(host='HOSTNAME.clickhouse.cloud', port=8443, username='default', password='your password')

Interaja com seu banco de dados

Para executar um comando em ClickHouse SQL, use o método command do cliente:

client.command('CREATE TABLE new_table (key UInt32, value String, metric Float64) ENGINE MergeTree ORDER BY key')

Para inserir dados em lote, use o método insert do cliente com um array bidimensional de linhas e valores:

row1 = [1000, 'String Value 1000', 5.233]
row2 = [2000, 'String Value 2000', -107.04]
data = [row1, row2]
client.insert('new_table', data, column_names=['key', 'value', 'metric'])

Para obter dados usando ClickHouse SQL, use o método query do cliente:

result = client.query('SELECT max(key), avg(metric) FROM new_table')
print(result.result_rows)
# Saída: [(2000, -50.9035)]

​Introdução

​Requisitos e compatibilidade

​Instalação

​Política de suporte

​Uso básico

​Obtenha os detalhes da conexão

​Estabeleça uma conexão

​Use uma instância do cliente ClickHouse Connect para se conectar a um servidor ClickHouse no localhost:

​Use uma instância do cliente ClickHouse Connect para se conectar a um serviço do ClickHouse Cloud:

​Interaja com seu banco de dados

Introdução

Requisitos e compatibilidade

Instalação

Política de suporte

Uso básico

Obtenha os detalhes da conexão

Estabeleça uma conexão

Use uma instância do cliente ClickHouse Connect para se conectar a um servidor ClickHouse no localhost:

Use uma instância do cliente ClickHouse Connect para se conectar a um serviço do ClickHouse Cloud:

Interaja com seu banco de dados