> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> El conjunto de proyectos ClickHouse Connect para conectar Python con ClickHouse
# 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. Un [codec de Rust](/es/integrations/language-clients/python/rust-codec) 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](https://www.sqlalchemy.org/) 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](/es/integrations/language-clients/python/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](https://github.com/ClickHouse/clickhouse-connect/blob/main/MIGRATION.md).
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](#embedded-chdb-backend) 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](https://pypi.org/project/clickhouse-connect/) con pip:
```bash theme={null}
pip install clickhouse-connect
```
Las integraciones opcionales se instalan con extras:
```bash theme={null}
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](https://github.com/ClickHouse/clickhouse-connect).
* 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:
```bash theme={null}
pip cache remove clickhouse_connect
```
Compruebe si los tres módulos de extensión están presentes. Si lo están, se imprime `True`:
```bash theme={null}
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](https://github.com/ClickHouse/clickhouse-connect/issues). ClickHouse Connect está pensado para las [versiones de ClickHouse con soporte activo](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md) 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:
```python theme={null}
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.
```python theme={null}
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:
```python theme={null}
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:
```python theme={null}
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:
```python theme={null}
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://`:
```python theme={null}
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.
