Introduction

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

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

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 expérimental en processus.

​

Exigences et compatibilité

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.

​

Installation

Installez ClickHouse Connect depuis PyPI à l’aide de pip :

pip install clickhouse-connect

Les intégrations facultatives s’installent à l’aide d’extras :

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

​

Modes de build depuis les sources

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 :

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 :

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

​

Politique de support

Mettez à jour vers la dernière version de ClickHouse Connect avant de signaler un problème. Ouvrez les tickets dans le projet GitHub. ClickHouse Connect cible les versions de ClickHouse activement prises en charge 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.

​

Utilisation de base

​

Rassemblez vos paramètres de connexion

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 :

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

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

​

Établir une connexion

Voici deux exemples de connexion à ClickHouse :

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

​

Utilisez une instance du client ClickHouse Connect pour vous connecter à un serveur ClickHouse sur localhost :

import clickhouse_connect

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

​

Utilisez une instance du client ClickHouse Connect pour vous connecter à un service ClickHouse Cloud :

Utilisez les paramètres de connexion recueillis précédemment. Les services ClickHouse Cloud nécessitent le protocole TLS ; utilisez donc le port 8443.

import clickhouse_connect

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

​

Interagissez avec votre base de données

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

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 :

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 :

result = client.query("SELECT max(key), avg(metric) FROM new_table")
print(result.result_rows)
# Output: [(2000, -50.9035)]

client.close()

​

Backend chDB intégré

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

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.