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

> La suite de projets ClickHouse Connect permettant de connecter Python à ClickHouse

# Introduction

ClickHouse Connect est un driver de base de données central qui assure l’interopérabilité avec un large éventail d’applications Python.

* Les principales interfaces sont le `Client` synchrone et l’`AsyncClient` natif basé sur aiohttp dans `clickhouse_connect.driver`. Le paquet du driver fournit également des contextes de requête et d’insertion, des helpers de streaming, la prise en charge de la DB-API, ainsi que des méthodes HTTP de plus bas niveau.
* Le paquet `clickhouse_connect.datatypes` sérialise et désérialise les types ClickHouse à l’aide du format binaire natif en colonnes de ClickHouse.
* Les extensions Cython optionnelles dans `clickhouse_connect.driverc` accélèrent les opérations courantes de sérialisation, de conversion et de mise en mémoire tampon. Une implémentation pure Python reste disponible sur les plateformes où les extensions ne peuvent pas être compilées.
* Le paquet inclut les informations de typage PEP 561, afin que les vérificateurs de types en aval puissent exploiter les annotations pour les interfaces publiques du driver, de la DB-API et de SQLAlchemy.
* Le dialecte [SQLAlchemy](https://www.sqlalchemy.org/) dans `clickhouse_connect.cc_sqlalchemy` prend en charge SQLAlchemy Core, la réflexion de schéma, les clauses de requête spécifiques à ClickHouse et les moteurs de table, ainsi que les migrations Alembic. Les lectures et insertions ORM de base fonctionnent, mais le dialecte est conçu pour des workloads analytiques plutôt que pour un comportement ORM complet de type unit-of-work.
* Le driver principal et l’implémentation [ClickHouse Connect SQLAlchemy](/fr/integrations/language-clients/python/sqlalchemy) sont la méthode privilégiée pour connecter ClickHouse à Apache Superset. Utilisez la connexion de base de données `ClickHouse Connect` ou la chaîne de connexion du dialecte SQLAlchemy `clickhousedb`.

Cette documentation est à jour pour clickhouse-connect 1.6.0. Si vous effectuez une mise à niveau depuis la version 0.15.x ou une version antérieure, consultez le [guide de migration 1.0](https://github.com/ClickHouse/clickhouse-connect/blob/main/MIGRATION.md).

<Note>
  Les clients ClickHouse Connect standard utilisent l’interface HTTP. Cela prend en charge les load balancers HTTP, les proxys et les contrôles réseau courants en entreprise. ClickHouse Connect dispose également d’un backend [chDB](#embedded-chdb-backend) expérimental en processus.
</Note>

<div id="requirements-and-compatibility">
  ## Exigences et compatibilité
</div>

| Composant   | Versions prises en charge                                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Python      | 3.10 à 3.14. Les builds free-threaded, comme 3.14t, sont pris en charge à titre expérimental.                                                     |
| ClickHouse  | Versions de ClickHouse activement prises en charge. Les tests d’intégration continue portent sur des versions récentes du serveur LTS et stables. |
| SQLAlchemy  | 1.4.40 ou version ultérieure, inférieure à 3.0                                                                                                    |
| Pandas      | 2.x et 3.x                                                                                                                                        |
| Polars      | 1.0 ou version ultérieure                                                                                                                         |
| aiohttp     | 3.9 ou version ultérieure                                                                                                                         |
| Plateformes | Linux, macOS et Windows sur les architectures pour lesquelles des wheels sont publiés pour chaque version de Python                               |

Le paquet inclut des wheels compilées lorsqu’elles sont disponibles et bascule sinon vers une implémentation pure Python lorsque les extensions Cython ne peuvent pas être compilées. PyArrow est pris en charge avec Python 3.10 à 3.14. Python 3.14 nécessite PyArrow 22 ou version ultérieure.

<div id="installation">
  ## Installation
</div>

Installez ClickHouse Connect depuis [PyPI](https://pypi.org/project/clickhouse-connect/) à l’aide de pip :

```bash theme={null}
pip install clickhouse-connect
```

Les intégrations facultatives s’installent à l’aide d’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[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 peut également être installé à partir du code source :

* Exécutez `git clone` sur le [dépôt GitHub](https://github.com/ClickHouse/clickhouse-connect).
* Placez-vous à la racine du projet et exécutez `pip install .`. Le système de build installe automatiquement Cython pour compiler les extensions C optionnelles.

La version installée est accessible via `clickhouse_connect.__version__`.

<div id="support-policy">
  ## Politique de support
</div>

Mettez à jour vers la dernière version de ClickHouse Connect avant de signaler un problème. Ouvrez les tickets dans le [projet GitHub](https://github.com/ClickHouse/clickhouse-connect/issues). ClickHouse Connect cible les [versions de ClickHouse activement prises en charge](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md) au moment de chaque publication du driver. Il fonctionne souvent avec des versions plus anciennes du serveur, mais les nouveaux types de données et les fonctionnalités plus récentes du protocole peuvent nécessiter un serveur plus récent.

<div id="basic-usage">
  ## Utilisation de base
</div>

<div id="gather-your-connection-details">
  ### Rassemblez vos paramètres de connexion
</div>

Pour vous connecter à ClickHouse via HTTP(S), vous avez besoin des informations suivantes :

| Paramètre(s)              | Description                                                                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `HOST` and `PORT`         | En général, le port est 8443 lors de l’utilisation de TLS, ou 8123 sans TLS.                                                                   |
| `DATABASE NAME`           | Par défaut, une base de données nommée `default` est disponible ; utilisez le nom de la base de données à laquelle vous voulez vous connecter. |
| `USERNAME` and `PASSWORD` | Par défaut, le nom d’utilisateur est `default`. Utilisez le nom d’utilisateur adapté à votre cas d’usage.                                      |

Les informations de votre service ClickHouse Cloud sont disponibles dans la console ClickHouse Cloud.
Sélectionnez un service, puis cliquez sur **Connect** :

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/APktBmhebGV1n1ZA/images/_snippets/cloud-connect-button.webp?fit=max&auto=format&n=APktBmhebGV1n1ZA&q=85&s=119293dc89fd9bb8fa178d0bec957ecc" alt="Bouton Connect du service ClickHouse Cloud" width="998" height="932" data-path="images/_snippets/cloud-connect-button.webp" />
  </Frame>
</div>

Choisissez **HTTPS**. Les détails de connexion s’affichent dans un exemple de commande `curl`.

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/APktBmhebGV1n1ZA/images/_snippets/connection-details-https.webp?fit=max&auto=format&n=APktBmhebGV1n1ZA&q=85&s=16a5a08d3a2c44601d981b9ee5a75216" alt="Détails de connexion HTTPS ClickHouse Cloud" width="1320" height="1184" data-path="images/_snippets/connection-details-https.webp" />
  </Frame>
</div>

Si vous utilisez ClickHouse autogéré, les détails de connexion sont définis par votre administrateur ClickHouse.

<div id="establish-a-connection">
  ### Établir une connexion
</div>

Voici deux exemples de connexion à ClickHouse :

* Connexion à un serveur ClickHouse sur localhost.
* Connexion à un service ClickHouse Cloud.

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-server-on-localhost">
  #### Utilisez une instance du client ClickHouse Connect pour vous connecter à un serveur ClickHouse sur 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">
  #### Utilisez une instance du client ClickHouse Connect pour vous connecter à un service ClickHouse Cloud :
</div>

<Tip>
  Utilisez les paramètres de connexion recueillis précédemment. Les services ClickHouse Cloud nécessitent le protocole TLS ; utilisez donc le port 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">
  ### Interagissez avec votre base de données
</div>

Pour exécuter une commande en ClickHouse SQL, utilisez la méthode `command` du client :

```python theme={null}
client.command(
    "CREATE TABLE new_table "
    "(key UInt32, value String, metric Float64) "
    "ENGINE MergeTree ORDER BY key"
)
```

Pour insérer des données par lot, utilisez la méthode `insert` du client avec un tableau bidimensionnel de lignes et de valeurs :

```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"])
```

Pour récupérer des données à l’aide de ClickHouse SQL, utilisez la méthode `query` du 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()
```

<div id="embedded-chdb-backend">
  ## Backend chDB intégré
</div>

Le backend chDB expérimental exécute des requêtes ClickHouse au sein du processus Python, sans serveur HTTP. Installez l’extra `chdb`, puis sélectionnez le backend avec `interface="chdb"` ou 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 données par défaut est en mémoire. Passez `path="/data/my_chdb"` ou utilisez `dsn="chdb:///data/my_chdb"` pour bénéficier d’un stockage persistant. chDB n’autorise qu’un seul chemin d’engine par processus. Il ne prend pas en charge le client async ni les données externes.