Intégration de Python avec ClickHouse Connect

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 comprend également diverses classes d’assistance et fonctions utilitaires utilisées pour communiquer avec le serveur ClickHouse, ainsi que des implémentations de « contexte » 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 en colonnes « Native » de ClickHouse, afin d’assurer le transport le plus efficace 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, pour des performances nettement supérieures à celles d’une implémentation en Python pur.
Un dialecte SQLAlchemy est disponible 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 DELETE légères avec des conditions WHERE, l’introspection des 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 fournit de solides capacités de requête adaptées à la plupart des charges de travail analytiques sur la base de données OLAP de ClickHouse.
Le pilote 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 la version 0.9.2 de clickhouse-connect.

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 de requêtes. Selon le cas d’usage, vous pouvez envisager d’utiliser l’un des pilotes Python de la communauté qui utilisent le protocole natif basé sur TCP.

Exigences et compatibilité

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 répertorié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. Enfin, comme ClickHouse Connect peut aussi s’exécuter en pure Python, l’installation depuis les 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 pour plus de détails. ³ClickHouse Connect fonctionne généralement bien avec des versions en dehors de la plage officiellement prise en charge.

Installation

Installez ClickHouse Connect depuis PyPI avec pip : pip install clickhouse-connect ClickHouse Connect peut également être installé from source :

exécutez git clone sur le dépôt GitHub.
(Facultatif) exécutez pip install cython pour compiler et activer les optimisations C/Cython
placez-vous dans le répertoire racine du projet avec cd, puis exécutez pip install .

Politique de support

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. Les futures versions de ClickHouse Connect sont conçues pour être compatibles avec les versions de ClickHouse activement prises en charge au moment de leur publication. Les versions de serveur ClickHouse actuellement prises en charge sont indiquées ici. Si vous ne savez pas quelle version de serveur ClickHouse utiliser, consultez cette discussion ici. Notre matrice de tests CI 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, même si la compatibilité avec certains types de données avancés peut varier.

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 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 avec 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)]

​Introduction

​Exigences et compatibilité

​Installation

​Politique de support

​Utilisation de base

​Rassemblez vos paramètres de connexion

​Établir une connexion

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

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

​Interagissez avec votre base de données

Introduction

Exigences et compatibilité

Installation

Politique de support

Utilisation de base

Rassemblez vos paramètres de connexion

Établir une connexion

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

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

Interagissez avec votre base de données