Introducción

ClickHouse Connect es un driver principal de base de datos que ofrece interoperabilidad con una amplia variedad de aplicaciones Python.

• Las interfaces principales son Client, síncrona, y AsyncClient, nativa basada en aiohttp, en clickhouse_connect.driver. El paquete del driver también proporciona contextos de consulta e inserción, funciones auxiliares de streaming, compatibilidad con DB-API y métodos HTTP de nivel inferior.
• El paquete clickhouse_connect.datatypes serializa y deserializa tipos de ClickHouse mediante el formato binario nativo columnar de ClickHouse.
• Las extensiones opcionales de Cython en clickhouse_connect.driverc aceleran las rutas habituales de serialización, conversión y almacenamiento en búfer. También sigue disponible una ruta en pure Python en plataformas donde no se pueden compilar las extensiones.
• El paquete incluye información de tipos PEP 561, por lo que los verificadores de tipos posteriores pueden usar annotations para las superficies públicas del driver, DB-API y SQLAlchemy.
• El dialecto de SQLAlchemy en clickhouse_connect.cc_sqlalchemy admite SQLAlchemy Core, reflection de esquemas, clauses de consulta específicas de ClickHouse y table engines, así como migrations de Alembic. Las lecturas e inserciones básicas de ORM funcionan, pero el dialecto está diseñado para cargas de trabajo analíticas, no para ofrecer todo el comportamiento ORM de unidad de trabajo.
• El driver principal y la implementación de ClickHouse Connect SQLAlchemy son el método preferido para conectar ClickHouse con Apache Superset. Use la conexión de base de datos ClickHouse Connect o la cadena de conexión del dialecto SQLAlchemy clickhousedb.

Esta documentación está actualizada para clickhouse-connect 1.6.0. Si está actualizando desde la versión 0.15.x o anterior, consulte la guía de migración a 1.0.

El package incluye wheels compilados cuando están disponibles y recurre a una implementación en pure Python cuando no se pueden compilar las extensiones de Cython. PyArrow es compatible con Python de 3.10 a 3.14. Python 3.14 requiere PyArrow 22 o posterior.

Instala ClickHouse Connect desde PyPI con pip:

pip install clickhouse-connect

Las integraciones opcionales se instalan con 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

ClickHouse Connect también puede instalarse desde el código fuente:

• Haz git clone del repositorio de GitHub.
• Ve a la raíz del proyecto y ejecuta pip install .. El sistema de compilación instala Cython automáticamente para compilar las extensiones C opcionales.

La versión instalada está disponible en clickhouse_connect.__version__.

Actualiza a la versión más reciente de ClickHouse Connect antes de reportar un issue. Registra los issues en el proyecto de GitHub. ClickHouse Connect está pensado para las versiones de ClickHouse con soporte activo en el momento de cada versión del driver. A menudo también funciona con versiones anteriores del servidor, pero los tipos de datos y las funciones del protocolo más recientes pueden requerir un servidor más reciente.

Para conectarse a ClickHouse con HTTP(S), necesita esta información:

Los detalles de su servicio de ClickHouse Cloud están disponibles en la consola de ClickHouse Cloud. Seleccione un servicio y haga clic en Connect:

Elija HTTPS. Los detalles de conexión se muestran en un comando curl de ejemplo.

Si usa ClickHouse autogestionado, los detalles de conexión los establece su administrador de ClickHouse.

Se muestran dos ejemplos de conexión a ClickHouse:

• Conexión a un servidor de ClickHouse en localhost.
• Conexión a un servicio de 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 ejecutar un comando de ClickHouse SQL, usa el método command del Client:

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

Para insertar datos por lotes, use el método insert del Client con un array bidimensional de filas y 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 recuperar datos con ClickHouse SQL, use el método query del Client:

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

client.close()

El backend experimental de chDB ejecuta consultas de ClickHouse dentro del proceso de Python, sin necesidad de un servidor HTTP. Instala el extra chdb y luego selecciona el backend con interface="chdb" o un 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,)]

La base de datos predeterminada está en memoria. Pase path="/data/my_chdb" o use dsn="chdb:///data/my_chdb" para almacenamiento persistente. chDB permite una sola ruta de engine por proceso. No es compatible con el Client async ni con datos externos.