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.
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.
O dialeto do SQLAlchemy em clickhouse_connect.cc_sqlalchemy oferece 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 dialeto 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 dialeto SQLAlchemy clickhousedb.

Esta documentação está atualizada até a versão 1.6.0 do clickhouse-connect. 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
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[alembic]"    # SQLAlchemy and Alembic
pip install "clickhouse-connect[chdb]"       # Embedded chDB backend
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.

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.

Página inicial

JavaScript

Python

Go

Java

C#

Rust

C++

C

Clientes de terceiros

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

Backend embutido do chDB

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

​Backend embutido do chDB

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

Backend embutido do chDB