> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> La suite de proyectos ClickHouse Connect para conectar Python a ClickHouse

# 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](https://www.sqlalchemy.org/) 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](/es/integrations/language-clients/python/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.

<Note>
  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](/es/integrations/language-clients/third-party/client-libraries) que usan el protocolo nativo basado en TCP.
</Note>

<div id="requirements-and-compatibility">
  ## Requisitos y compatibilidad
</div>

|     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`](https://cibuildwheel.readthedocs.io/en/stable/). 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](/es/integrations/language-clients/python/sqlalchemy) para obtener más información.

³Por lo general, ClickHouse Connect funciona bien con versiones fuera del rango de compatibilidad oficial.

<div id="installation">
  ## Instalación
</div>

Instale ClickHouse Connect desde [PyPI](https://pypi.org/project/clickhouse-connect/) con pip:

`pip install clickhouse-connect`

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

* haga `git clone` del [repositorio de GitHub](https://github.com/ClickHouse/clickhouse-connect).
* (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 .`

<div id="support-policy">
  ## Política de soporte
</div>

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](https://github.com/ClickHouse/clickhouse-connect/issues). 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í](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md). Si no está seguro de qué versión del servidor de ClickHouse usar, lea esta explicación [aquí](/es/resources/support-center/knowledge-base/setup-installation/production#how-to-choose-between-clickhouse-releases). 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.

<div id="basic-usage">
  ## Uso básico
</div>

<div id="gather-your-connection-details">
  ### Obtén los detalles de conexión
</div>

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**:

<Image img="/images/_snippets/cloud-connect-button.png" size="md" alt="Botón Connect del servicio de ClickHouse Cloud" border />

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

<Image img="/images/_snippets/connection-details-https.png" size="md" alt="Detalles de conexión HTTPS de ClickHouse Cloud" border />

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

<div id="establish-a-connection">
  ### Establecer una conexión
</div>

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.

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-server-on-localhost">
  #### Usa una instancia cliente de ClickHouse Connect para conectarte a un servidor de ClickHouse en localhost:
</div>

```python theme={null}
import clickhouse_connect

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

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-cloud-service">
  #### Usa una instancia del cliente ClickHouse Connect para conectarte a un servicio de ClickHouse Cloud:
</div>

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

```python theme={null}
import clickhouse_connect

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

<div id="interact-with-your-database">
  ### Interactúa con tu base de datos
</div>

Para ejecutar un comando de ClickHouse SQL, utiliza el método `command` del cliente:

```python theme={null}
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:

```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 consultar datos con ClickHouse SQL, use el método `query` del cliente:

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