Introducción

El conjunto de proyectos ClickHouse Connect para conectar Python con ClickHouse

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. Un codec de Rust experimental y opcional puede sustituir por completo el procesamiento del Native format.
• 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.
• Los dialectos de SQLAlchemy en clickhouse_connect.cc_sqlalchemy incluyen conexiones síncronas clickhousedb:// y conexiones asíncronas clickhousedb+async://. Admiten 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.

Si está actualizando desde la versión 0.15.x o anterior, consulte la guía de migración a 1.0.

Los Clients estándar de ClickHouse Connect usan la interfaz HTTP. Esto permite usar balanceadores de carga HTTP, proxies y controles de red empresariales habituales. ClickHouse Connect también tiene un backend chDB experimental en el mismo proceso.

​

Requisitos y compatibilidad

Componente	Versiones compatibles
Python	De 3.10 a 3.14. Las compilaciones free-threaded, como 3.14t, tienen soporte experimental.
ClickHouse	Versiones de ClickHouse con soporte activo. CI realiza pruebas con releases recientes LTS y stable del servidor.
SQLAlchemy	1.4.40 o posterior, inferior a 3.0, para el dialecto síncrono. 2.0.44 o posterior, inferior a 3.0, para el dialecto async.
Pandas	2.x y 3.x
Polars	1.0 o posterior
aiohttp	3.9 o posterior
Plataformas	Linux, macOS y Windows en las arquitecturas para las que se publican wheels de cada versión de Python

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.

​

Instalación

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[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

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.

​

Modos de compilación desde el código fuente

Las compilaciones desde el código fuente admiten tres modos. Los modos predeterminado y obligatorio fallan si Cython no está disponible o si cythonize() falla. El modo de omisión no importa Cython.

Modo	Comando	Comportamiento
Predeterminado	pip install .	Intenta compilar las extensiones C. Si el compilador o el enlazador falla, la compilación recurre a una instalación pure Python.
Pure Python	CLICKHOUSE_CONNECT_SKIP_CYTHON=1 pip install .	Compila en pure Python sin intentar generar las extensiones.
Obligatorio	CLICKHOUSE_CONNECT_REQUIRE_C=1 pip install .	Hace fallar la compilación si las extensiones no se pueden compilar. Recomendado para CI y para generar wheels redistribuibles.

Establecer CLICKHOUSE_CONNECT_SKIP_CYTHON=1 y CLICKHOUSE_CONNECT_REQUIRE_C=1 a la vez es un error.

Los wheels de fallback predeterminados no contienen extensiones compiladas, pero conservan los tags de plataforma e intérprete. Solo el modo de omisión produce py3-none-any. pip puede almacenar en caché un wheel de fallback compilado a partir de un sdist del índice y reutilizarlo para un Python y una plataforma compatibles después de corregir el compilador. Bórralo con:

pip cache remove clickhouse_connect

Compruebe si los tres módulos de extensión están presentes. Si lo están, se imprime True:

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 directamente clickhouse_connect.driverc.npconv también requiere que NumPy esté instalado.

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

​

Política de soporte

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.

​

Uso básico

​

Obtén los detalles de conexión

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

Parámetro(s)	Descripción
HOST and PORT	Normalmente, el puerto es 8443 cuando se usa TLS o 8123 cuando no se usa TLS.
DATABASE NAME	De forma predeterminada, existe una base de datos llamada default; use el nombre de la base de datos a la que desea conectarse.
USERNAME and PASSWORD	De forma predeterminada, el nombre de usuario es default. Use el nombre de usuario adecuado para su caso de uso.

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.

​

Establecer una conexión

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.

​

Usa una instancia Client de ClickHouse Connect para conectarte a un servidor de ClickHouse en localhost:

import clickhouse_connect

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

​

Usa una instancia del Client ClickHouse Connect para conectarte a un servicio de ClickHouse Cloud:

Usa los datos de conexión recopilados anteriormente. Los servicios de ClickHouse Cloud requieren TLS, así que usa el puerto 8443.

import clickhouse_connect

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

​

Interactúa con tu base de datos

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

​

Backend embebido de chDB

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.