Integración de Python con ClickHouse Connect

Introducción

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

La interfaz principal es el objeto Client del paquete clickhouse_connect.driver. Ese paquete principal también incluye varias clases auxiliares y funciones de utilidad para comunicarse con el servidor de ClickHouse, así como implementaciones de “context” para la gestión avanzada de consultas de inserción y selección.
El paquete clickhouse_connect.datatypes proporciona una implementación base y subclases para todos los tipos de datos no experimentales de ClickHouse. Su función principal es la serialización y deserialización de datos de ClickHouse al formato binario columnar “Native” de ClickHouse, utilizado para lograr el transporte más eficiente entre ClickHouse y las aplicaciones cliente.
Las clases Cython/C del paquete clickhouse_connect.cdriver optimizan algunas de las serializaciones y deserializaciones más habituales para ofrecer un rendimiento significativamente superior al de Python puro.
El paquete clickhouse_connect.cc_sqlalchemy incluye un dialecto de SQLAlchemy construido sobre los paquetes datatypes y dbi. Esta implementación admite la funcionalidad Core de SQLAlchemy, incluidas consultas SELECT con JOIN (INNER, LEFT OUTER, FULL OUTER, CROSS), cláusulas WHERE, ORDER BY, LIMIT/OFFSET, operaciones DISTINCT, sentencias de eliminación ligera DELETE con condiciones WHERE, reflexión de tablas y operaciones DDL básicas (CREATE TABLE, CREATE/DROP DATABASE). Aunque no admite características avanzadas de ORM ni funcionalidades DDL avanzadas, ofrece capacidades de consulta sólidas, adecuadas para la mayoría de las cargas de trabajo analíticas sobre la base de datos orientada a OLAP de ClickHouse.
El controlador principal y la implementación de ClickHouse Connect SQLAlchemy son el método preferido para conectar ClickHouse a Apache Superset. Utilice 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 la versión 0.9.2 de clickhouse-connect.

El controlador oficial de Python ClickHouse Connect utiliza el protocolo HTTP para comunicarse con el servidor de ClickHouse. Esto permite la compatibilidad con balanceadores de carga HTTP y funciona bien en entornos empresariales con cortafuegos y proxies, pero ofrece una compresión y un rendimiento ligeramente inferiores en comparación con el protocolo nativo basado en TCP, y no admite algunas funciones avanzadas, como la cancelación de consultas. En algunos casos de uso, puede convenir utilizar uno de los controladores de Python de la comunidad que usan el protocolo nativo basado en TCP.

Requisitos y compatibilidad

Python		Plataforma¹		ClickHouse		SQLAlchemy²		Apache Superset		Pandas		Polars
2.x, <3.9	❌	Linux (x86)	✅	<25.x³	🟡	<1.4.40	❌	<1.4	❌	≥1.5	✅	1.x	✅
3.9.x	✅	Linux (Aarch64)	✅	25.x³	🟡	≥1.4.40	✅	1.4.x	✅	2.x	✅
3.10.x	✅	macOS (x86)	✅	25.3.x (LTS)	✅	≥2.x	✅	1.5.x	✅
3.11.x	✅	macOS (ARM)	✅	25.6.x (estable)	✅			2.0.x	✅
3.12.x	✅	Windows	✅	25.7.x (estable)	✅			2.1.x	✅
3.13.x	✅			25.8.x (LTS)	✅			3.0.x	✅
				25.9.x (estable)	✅

¹ClickHouse Connect se ha probado explícitamente en las plataformas indicadas. Además, se compilan ruedas binarias no probadas (con optimización en C) para todas las arquitecturas compatibles con el excelente proyecto cibuildwheel. Por último, como ClickHouse Connect también puede ejecutarse como Python puro, la instalación desde el código fuente debería funcionar en cualquier instalación reciente de Python. ²La compatibilidad con SQLAlchemy se limita a la funcionalidad de Core (consultas, DDL básico). Las funcionalidades de ORM no son compatibles. Consulta la documentación de SQLAlchemy Integration Support para obtener más información. ³Por lo general, ClickHouse Connect funciona bien con versiones fuera del rango de compatibilidad oficial.

Instalación

Instale ClickHouse Connect desde PyPI con pip: pip install clickhouse-connect ClickHouse Connect también puede instalarse desde el código fuente:

haga git clone del repositorio de GitHub.
(Opcional) ejecute pip install cython para compilar y habilitar las optimizaciones de C/Cython
cambie al directorio raíz del proyecto y ejecute pip install .

Política de soporte

Actualice a la versión más reciente de ClickHouse Connect antes de informar de cualquier problema. Los problemas deben notificarse en el proyecto de GitHub. Está previsto que las futuras versiones de ClickHouse Connect sean compatibles con las versiones de ClickHouse con soporte activo en el momento de cada lanzamiento. Las versiones del servidor de ClickHouse con soporte activo pueden consultarse aquí. Si no está seguro de qué versión del servidor de ClickHouse usar, lea esta explicación aquí. Nuestra matriz de pruebas de CI se ejecuta con las dos versiones LTS más recientes y las tres versiones estables más recientes. Sin embargo, debido al protocolo HTTP y a los mínimos cambios incompatibles entre versiones de ClickHouse, ClickHouse Connect por lo general funciona bien con versiones del servidor fuera del rango admitido oficialmente, aunque la compatibilidad con ciertos tipos de datos avanzados puede variar.

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 cliente 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 cliente 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, utiliza el método command del cliente:

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

Para insertar datos en lote, use el método insert del cliente 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 consultar datos con ClickHouse SQL, use el método query del cliente:

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

​Introducción

​Requisitos y compatibilidad

​Instalación

​Política de soporte

​Uso básico

​Obtén los detalles de conexión

​Establecer una conexión

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

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

​Interactúa con tu base de datos

Introducción

Requisitos y compatibilidad

Instalación

Política de soporte

Uso básico

Obtén los detalles de conexión

Establecer una conexión

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

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

Interactúa con tu base de datos