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

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.

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

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.

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

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.

Voici deux exemples de connexion à ClickHouse :

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

import clickhouse_connect

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

import clickhouse_connect

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

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

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.