> ## 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.

> 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. Un [codec Rust](/fr/integrations/language-clients/python/rust-codec) expérimental, activable sur demande, peut remplacer entièrement le traitement du format natif.
* 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.
* Les dialectes [SQLAlchemy](https://www.sqlalchemy.org/) de `clickhouse_connect.cc_sqlalchemy` proposent des connexions synchrones `clickhousedb://` et des connexions asynchrones `clickhousedb+async://`. Ils prennent 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`.

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>

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

| 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, pour le dialecte synchrone. 2.0.44 ou version ultérieure, inférieure à 3.0, pour le dialecte asynchrone. |
| 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.

<h2 id="installation">
  Installation
</h2>

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

<h3 id="source-build-modes">
  Modes de build depuis les sources
</h3>

Les builds depuis les sources prennent en charge trois modes. Les modes par défaut et requis échouent si Cython n'est pas disponible ou si `cythonize()` échoue. Le mode skip n'importe pas Cython.

| Mode | Commande | Comportement |
| - | - | - |
| Par défaut | `pip install .` | Tente de compiler les extensions C. Si le compilateur ou l'éditeur de liens échoue, le build bascule vers une installation pure Python. |
| Pure Python | `CLICKHOUSE_CONNECT_SKIP_CYTHON=1 pip install .` | Effectue un build pure Python sans tenter de compiler les extensions. |
| Requis | `CLICKHOUSE_CONNECT_REQUIRE_C=1 pip install .` | Fait échouer le build si les extensions ne peuvent pas être compilées. Recommandé pour l'intégration continue et pour construire des wheels redistribuables. |

Définir à la fois `CLICKHOUSE_CONNECT_SKIP_CYTHON=1` et `CLICKHOUSE_CONNECT_REQUIRE_C=1` constitue une erreur.

Les wheels de fallback par défaut ne contiennent aucune extension compilée, mais conservent les tags de plateforme et d'interpréteur. Seul le mode skip produit `py3-none-any`. `pip` peut mettre en cache un wheel de fallback construit à partir d'un sdist d'index et le réutiliser pour un Python et une plateforme compatibles une fois le compilateur corrigé. Videz-le avec :

```bash theme={null}
pip cache remove clickhouse_connect
```

Vérifiez que les trois modules d'extension sont bien présents. La commande affiche `True` si c'est le cas :

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

L'importation directe de `clickhouse_connect.driverc.npconv` nécessite également que NumPy soit installé.

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

<h2 id="support-policy">
  Politique de support
</h2>

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.

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

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

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-parallel-read-in-order-multi-part/GTkpPcjoRQ_okrH3/images/_snippets/cloud-connect-button.webp?fit=max&auto=format&n=GTkpPcjoRQ_okrH3&q=85&s=d059c1bbcc7317ff8df85b20189e65f4" 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-parallel-read-in-order-multi-part/GTkpPcjoRQ_okrH3/images/_snippets/connection-details-https.webp?fit=max&auto=format&n=GTkpPcjoRQ_okrH3&q=85&s=f7a41f485276d8d238dbe28772bfa56c" 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.

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

Voici deux exemples de connexion à ClickHouse :

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

<h4 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 :
</h4>

```python theme={null}
import clickhouse_connect

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

<h4 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 :
</h4>

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

<h3 id="interact-with-your-database">
  Interagissez avec votre base de données
</h3>

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

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

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.