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.

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.

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

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.

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

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.

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.

import clickhouse_connect

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

import clickhouse_connect

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

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()

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.