Introdução

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

As principais interfaces são o Client síncrono e o AsyncClient, nativo e baseado em aiohttp, em clickhouse_connect.driver. O pacote do driver também fornece contextos de consulta e insert, utilitários de streaming, suporte a DB-API e métodos HTTP de nível mais baixo.
O pacote clickhouse_connect.datatypes serializa e desserializa tipos do ClickHouse usando o formato colunar binário Native do ClickHouse.
As extensões opcionais em Cython em clickhouse_connect.driverc aceleram caminhos comuns de serialização, conversão e bufferização. Uma implementação em Python puro continua disponível em plataformas nas quais as extensões não podem ser compiladas. Um codec Rust experimental e opcional pode substituir totalmente o processamento do formato Native.
O pacote inclui informações de tipos do PEP 561, para que verificadores de tipo downstream consumam anotações para as interfaces públicas do driver, da DB-API e do SQLAlchemy.
Os dialects do SQLAlchemy em clickhouse_connect.cc_sqlalchemy incluem conexões síncronas clickhousedb:// e conexões assíncronas clickhousedb+async://. Eles oferecem suporte ao SQLAlchemy Core, reflexão de esquema, cláusulas de consulta específicas do ClickHouse e motores de tabela, além de migrações do Alembic. Leituras e inserts básicos com ORM funcionam, mas o dialect foi projetado para workloads analíticas, e não para o comportamento ORM completo de unit-of-work.
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 dialect SQLAlchemy clickhousedb.

Se você estiver atualizando da versão 0.15.x ou anterior, consulte o guia de migração 1.0.

Os clientes padrão do ClickHouse Connect usam a interface HTTP. Isso oferece suporte a balanceadores de carga HTTP, proxies e controles de rede corporativos comuns. O ClickHouse Connect também tem um backend chDB experimental in-process.

Requisitos e compatibilidade

Componente	Versões compatíveis
Python	3.10 a 3.14. Compilações free-threaded, como 3.14t, têm suporte experimental.
ClickHouse	Lançamentos do ClickHouse com suporte ativo. A CI realiza testes com lançamentos recentes LTS e estáveis do servidor.
SQLAlchemy	1.4.40 ou posterior, abaixo de 3.0, para o dialect síncrono. 2.0.44 ou posterior, abaixo de 3.0, para o dialect assíncrono.
Pandas	2.x e 3.x
Polars	1.0 ou posterior
aiohttp	3.9 ou posterior
Plataformas	Linux, macOS e Windows nas arquiteturas com wheels publicadas para cada versão do Python

O pacote inclui wheels compiladas quando disponíveis e usa uma implementação em Python puro quando as extensões Cython não podem ser compiladas. PyArrow é compatível com Python 3.10 a 3.14. Python 3.14 requer PyArrow 22 ou posterior.

Instalação

Instale o ClickHouse Connect do PyPI via pip:

pip install clickhouse-connect

As integrações opcionais são instaladas via extras:

pip install "clickhouse-connect[async]"      # Native asyncio client
pip install "clickhouse-connect[pandas]"     # Pandas
pip install "clickhouse-connect[arrow]"      # PyArrow
pip install "clickhouse-connect[polars]"     # Polars
pip install "clickhouse-connect[sqlalchemy]" # SQLAlchemy dialect
pip install "clickhouse-connect[sqlalchemy-async]" # Async SQLAlchemy dialect
pip install "clickhouse-connect[alembic]"    # SQLAlchemy and Alembic
pip install "clickhouse-connect[chdb]"       # Embedded chDB backend
pip install "clickhouse-connect[rust,arrow]" # Experimental Rust codec evaluation setup
pip install "clickhouse-connect[tzdata]"     # IANA time zones on minimal systems

O ClickHouse Connect também pode ser instalado a partir do código-fonte:

Execute git clone do repositório no GitHub.
Acesse a raiz do projeto e execute pip install .. O sistema de compilação instala o Cython automaticamente para compilar as extensões C opcionais.

Modos de compilação a partir do código-fonte

As compilações a partir do código-fonte suportam três modos. Os modos padrão e obrigatório falham se o Cython não estiver disponível ou se cythonize() falhar. O modo de omissão não importa o Cython.

Modo	Comando	Comportamento
Padrão	`pip install .`	Tenta compilar as extensões C. Se o compilador ou o linker falhar, a compilação recorre a uma instalação em Python puro.
Python puro	`CLICKHOUSE_CONNECT_SKIP_CYTHON=1 pip install .`	Compila em Python puro sem tentar gerar as extensões.
Obrigatório	`CLICKHOUSE_CONNECT_REQUIRE_C=1 pip install .`	Faz a compilação falhar caso as extensões não possam ser compiladas. Recomendado para CI e para gerar wheels redistribuíveis.

Definir CLICKHOUSE_CONNECT_SKIP_CYTHON=1 e CLICKHOUSE_CONNECT_REQUIRE_C=1 ao mesmo tempo é um erro. As wheels geradas pelo fallback padrão não contêm extensões compiladas, mas mantêm as tags de plataforma e de interpretador. Somente o modo de omissão produz py3-none-any. O pip pode armazenar em cache uma wheel de fallback compilada a partir de um sdist do índice e reutilizá-la em um Python e plataforma compatíveis mesmo depois de o compilador ser corrigido. Limpe-o com:

pip cache remove clickhouse_connect

Verifique se os três módulos de extensão estão presentes. Isso imprime True quando estiverem:

python -c "from importlib.util import find_spec; print(all(find_spec(m) for m in ('clickhouse_connect.driverc.buffer', 'clickhouse_connect.driverc.dataconv', 'clickhouse_connect.driverc.npconv')))"

Importar clickhouse_connect.driverc.npconv diretamente também exige que o NumPy esteja instalado. A versão instalada está disponível em clickhouse_connect.__version__.

Política de suporte

Atualize para a versão mais recente do ClickHouse Connect antes de relatar um issue. Registre issues no projeto do GitHub. O ClickHouse Connect é direcionado aos lançamentos do ClickHouse com suporte ativo no momento de cada lançamento do driver. Em geral, ele também funciona com versões mais antigas do servidor, mas tipos de dados e recursos de protocolo mais recentes podem exigir um servidor mais novo.

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.

detalhes de conexão HTTPS do ClickHouse Cloud

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 o seu banco de dados

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

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 consultar 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)
# Output: [(2000, -50.9035)]

client.close()

Backend embutido do chDB

O backend experimental do chDB executa consultas do ClickHouse dentro do processo do Python, sem um servidor HTTP. Instale o extra chdb e, em seguida, selecione o backend com interface="chdb" ou uma DSN chdb://:

import clickhouse_connect

with clickhouse_connect.get_client(interface="chdb") as client:
    result = client.query("SELECT number FROM numbers(3)")
    print(result.result_rows)
    # Output: [(0,), (1,), (2,)]

O banco de dados padrão fica em memória. Passe path="/data/my_chdb" ou use dsn="chdb:///data/my_chdb" para armazenamento persistente. O chDB permite apenas um caminho de engine por processo. Ele não oferece suporte ao cliente async nem a dados externos.

Início

JavaScript

Python

Go

Java

C++

C

Clientes de terceiros

Requisitos e compatibilidade

Instalação

Modos de compilação a partir do código-fonte

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 o seu banco de dados

Backend embutido do chDB

​Requisitos e compatibilidade

​Instalação

​Modos de compilação a partir do código-fonte

​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 o seu banco de dados

​Backend embutido do chDB

Requisitos e compatibilidade

Instalação

Modos de compilação a partir do código-fonte

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 o seu banco de dados

Backend embutido do chDB