> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> La suite de projets ClickHouse Connect pour relier Python à ClickHouse

# Introduction

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

* L’interface principale est l’objet `Client` du paquet `clickhouse_connect.driver`. Ce paquet central inclut également diverses classes d’assistance et fonctions utilitaires utilisées pour communiquer avec le serveur ClickHouse, ainsi que des implémentations de "context" pour la gestion avancée des requêtes d’insertion et de sélection.
* Le paquet `clickhouse_connect.datatypes` fournit une implémentation de base et des sous-classes pour tous les types de données ClickHouse non expérimentaux. Sa fonction principale est la sérialisation et la désérialisation des données ClickHouse dans le format binaire colonnaire "Native" de ClickHouse, afin d’assurer le transport le plus efficace possible entre ClickHouse et les applications clientes.
* Les classes Cython/C du paquet `clickhouse_connect.cdriver` optimisent certaines des sérialisations et désérialisations les plus courantes afin d’offrir des performances nettement supérieures à celles du Python pur.
* Il existe un dialecte [SQLAlchemy](https://www.sqlalchemy.org/) dans le paquet `clickhouse_connect.cc_sqlalchemy`, construit à partir des paquets `datatypes` et `dbi`. Cette implémentation prend en charge les fonctionnalités de SQLAlchemy Core, y compris les requêtes `SELECT` avec des `JOIN` (`INNER`, `LEFT OUTER`, `FULL OUTER`, `CROSS`), les clauses `WHERE`, `ORDER BY`, `LIMIT`/`OFFSET`, les opérations `DISTINCT`, les instructions lightweight `DELETE` avec des conditions `WHERE`, la réflexion de tables et les opérations DDL de base (`CREATE TABLE`, `CREATE`/`DROP DATABASE`). Bien qu’elle ne prenne pas en charge les fonctionnalités ORM avancées ni les fonctionnalités DDL avancées, elle offre des capacités de requête robustes adaptées à la plupart des workloads analytiques sur la base de données orientée OLAP de ClickHouse.
* Le pilote central et l’implémentation [ClickHouse Connect SQLAlchemy](/docs/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 la version 0.9.2 de clickhouse-connect.

<Note>
  Le pilote Python officiel ClickHouse Connect utilise le protocole HTTP pour communiquer avec le serveur ClickHouse. Cela permet la prise en charge des équilibreurs de charge HTTP et fonctionne bien dans les environnements d’entreprise avec des pare-feu et des proxys, mais offre une compression et des performances légèrement inférieures à celles du protocole natif basé sur TCP, et ne prend pas en charge certaines fonctionnalités avancées comme l’annulation des requêtes. Selon le cas d’usage, vous pouvez envisager d’utiliser l’un des [pilotes Python de la communauté](/docs/fr/integrations/language-clients/third-party/client-libraries) qui utilisent le protocole natif basé sur TCP.
</Note>

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

|     Python |    |     Plateforme¹ |    |      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 (Stable) | ✅  |             |    |           2.0.x | ✅  |        |    |        |    |
|     3.12.x | ✅  |         Windows | ✅  | 25.7.x (Stable) | ✅  |             |    |           2.1.x | ✅  |        |    |        |    |
|     3.13.x | ✅  |                 |    |    25.8.x (LTS) | ✅  |             |    |           3.0.x | ✅  |        |    |        |    |
|            |    |                 |    | 25.9.x (Stable) | ✅  |             |    |                 |    |        |    |        |    |

¹ClickHouse Connect a été explicitement testé sur les plateformes indiquées. En outre, des wheels binaires non testées (avec optimisation C) sont générées pour toutes les architectures prises en charge par l’excellent projet [`cibuildwheel`](https://cibuildwheel.readthedocs.io/en/stable/). Enfin, comme ClickHouse Connect peut également s’exécuter en pure Python, l’installation à partir des sources devrait fonctionner sur toute installation récente de Python.

²La prise en charge de SQLAlchemy est limitée aux fonctionnalités Core (requêtes, DDL de base). Les fonctionnalités ORM ne sont pas prises en charge. Consultez la documentation [SQLAlchemy Integration Support](/docs/fr/integrations/language-clients/python/sqlalchemy) pour plus de détails.

³ClickHouse Connect fonctionne généralement bien avec des versions en dehors de la plage officiellement prise en charge.

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

Installez ClickHouse Connect depuis [PyPI](https://pypi.org/project/clickhouse-connect/) avec pip :

`pip install clickhouse-connect`

ClickHouse Connect peut également être installé from source :

* clonez le [repository GitHub](https://github.com/ClickHouse/clickhouse-connect) avec `git clone`.
* (Facultatif) exécutez `pip install cython` pour compiler et activer les optimisations C/Cython
* placez-vous dans le directory racine du projet avec `cd`, puis exécutez `pip install .`

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

Veuillez mettre à jour ClickHouse Connect vers sa dernière version avant de signaler un problème. Les problèmes doivent être signalés dans le [projet GitHub](https://github.com/ClickHouse/clickhouse-connect/issues). Les futures versions de ClickHouse Connect sont conçues pour être compatibles avec les versions de ClickHouse prises en charge au moment de leur publication. Les versions du serveur ClickHouse actuellement prises en charge sont disponibles [ici](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md). Si vous ne savez pas quelle version du serveur ClickHouse utiliser, consultez cette discussion [ici](/docs/fr/resources/support-center/knowledge-base/setup-installation/production#how-to-choose-between-clickhouse-releases). Notre matrice de tests d’intégration continue couvre les deux dernières versions LTS et les trois dernières versions stables. Cependant, grâce au protocole HTTP et au faible nombre de changements non rétrocompatibles entre les versions de ClickHouse, ClickHouse Connect fonctionne généralement bien avec des versions du serveur en dehors de la plage officiellement prise en charge, bien que la compatibilité avec certains types de données avancés puisse varier.

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

<div id="gather-your-connection-details">
  ### Munissez-vous de vos informations 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/CFFsa2agBPbviR4r/images/_snippets/cloud-connect-button.webp?fit=max&auto=format&n=CFFsa2agBPbviR4r&q=85&s=ec0a298a33ca841e947fa5e8bae47362" 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/CFFsa2agBPbviR4r/images/_snippets/connection-details-https.webp?fit=max&auto=format&n=CFFsa2agBPbviR4r&q=85&s=cb0fbd98aa2b5b7ca484c9f53395ee07" 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>

Deux exemples de connexion à ClickHouse sont présentés :

* 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 informations de connexion recueillies précédemment. Les services ClickHouse Cloud nécessitent 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 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 un lot de données, utilisez la méthode `insert` du client avec un tableau à deux dimensions 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 avec 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)]
```