Introduction - ClickHouse Documentation

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

clonez le repository GitHub 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 .

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 prises en charge au moment de leur publication. Les versions du serveur ClickHouse actuellement prises en charge sont disponibles ici. Si vous ne savez pas quelle version du serveur ClickHouse utiliser, consultez cette discussion ici. 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.

Utilisation de base

Munissez-vous de vos informations 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.

Détails de connexion HTTPS ClickHouse Cloud

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

Établir une connexion

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

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

​Exigences et compatibilité

​Installation

​Politique de support

​Utilisation de base

​Munissez-vous de vos informations 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

Exigences et compatibilité

Installation

Politique de support

Utilisation de base

Munissez-vous de vos informations 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