API du driver ClickHouse Connect - ClickHouse Documentation

Utilisez des arguments nommés pour les fabriques de clients et les méthodes comportant de nombreux paramètres facultatifs.Les méthodes qui ne sont pas documentées ici ne sont pas considérées comme faisant partie de l’API et peuvent être supprimées ou modifiées.

Initialisation du client

Utilisez clickhouse_connect.get_client pour créer un Client synchrone, ou installez l’extra async et attendez clickhouse_connect.get_async_client pour créer un AsyncClient natif.

Arguments de connexion

Paramètre	Type	Valeur par défaut	Description
`interface`	str	`"http"`	`"http"` ou `"https"`. La fabrique synchrone prend également en charge le backend expérimental `"chdb"`.
`host`	str	`"localhost"`	Nom d’hôte ou adresse IP du serveur ClickHouse.
`port`	int ou None	`8123` ou `8443`	La valeur par défaut est 8123 pour HTTP et 8443 pour HTTPS. En passant `None`, la valeur par défaut est utilisée.
`username`	str ou None	`"default"`	Nom d’utilisateur de ClickHouse. Les alias `user` et `user_name` sont également acceptés.
`password`	str	`""`	Mot de passe associé à `username`. Ne combinez pas l’authentification par nom d’utilisateur/mot de passe avec l’authentification par jeton.
`access_token`	str ou None	`None`	Jeton d’accès JWT pour ClickHouse Cloud. Ne peut pas être utilisé avec `token_provider` ni avec l’authentification par utilisateur/mot de passe.
`token_provider`	callable ou None	`None`	Objet appelable qui fournit un JWT au départ, puis de nouveau en cas de rejet d’authentification. Un fournisseur asynchrone peut être utilisé avec `get_async_client`.
`database`	str ou None	Valeur par défaut de l’utilisateur	Base de données par défaut. Passer `None` demande au serveur d’utiliser la base de données par défaut de l’utilisateur.
`secure`	bool ou str	`False`	Active HTTPS/TLS. `interface="https"` sélectionne également HTTPS, tout comme les ports 443 ou 8443 lorsque `interface` n’est pas défini.
`dsn`	str ou None	`None`	URL de connexion. Les arguments de mot-clé explicites prévalent sur les valeurs extraites du DSN. Encodez en pourcentage les caractères réservés dans les informations d’identification et les noms de base de données.
`settings`	dict ou None	`None`	Paramètres ClickHouse appliqués à chaque requête envoyée par le client.
`headers`	dict ou None	`None`	En-têtes HTTP appliqués à chaque requête, y compris lors de l’initialisation du client. Les en-têtes utilisateur sont appliqués après ceux par défaut du driver et peuvent les remplacer.
`compress`	bool ou str	`True`	Activez la compression ou choisissez `"lz4"`, `"zstd"`, `"br"` ou `"gzip"`. Voir Compression.
`query_limit`	int	`0`	Limite de lignes par défaut ajoutée aux requêtes éligibles. Zéro signifie illimité. Diffusez les résultats volumineux en flux plutôt que de tous les matérialiser en mémoire.
`query_retries`	int	`2`	Nombre de réessais alloué aux échecs de lecture pouvant donner lieu à un réessai. Les commandes et les insertions ne sont généralement pas réessayées, car leur réexécution peut dupliquer les effets de bord.
`connect_timeout`	int en synchrone, float en asynchrone	`10`	Délai d’expiration, en secondes, pour l’établissement d’une nouvelle connexion. L’attente d’un emplacement libre dans le pool de connexions n’est pas prise en compte. Le client asynchrone accepte les fractions de seconde.
`send_receive_timeout`	int en synchrone, float en asynchrone	`300`	Délai d’expiration de lecture du socket, en secondes. Le client asynchrone accepte les fractions de seconde.
`client_name`	str ou None	`None`	Préfixe ajouté au User-Agent HTTP pour l’identification dans `system.query_log`.
`session_id`	str ou None	Généré en synchrone	ID de session ClickHouse explicite. Les clients synchrones en génèrent un par défaut ; les clients async n’en génèrent pas.
`autogenerate_session_id`	bool ou None	Paramètre global en mode synchrone, `False` en mode asynchrone	Remplace la génération automatique de l’ID de session. Désactivez-la sur un client partagé entre des opérations concurrentes, sauf si l’état de session est requis.
`autogenerate_query_id`	bool ou None	Paramètre global, `True`	Remplace la génération automatique de l’ID de requête UUID.
`http_proxy`	str ou None	Environnement/par défaut	Adresse du proxy HTTP pour chaque client.
`https_proxy`	str ou None	Environnement/par défaut	Adresse du proxy HTTPS propre à chaque client.
`pool_mgr`	`urllib3.PoolManager` ou None	Partagé au sein du processus	Gestionnaire de pool personnalisé pour le client synchrone uniquement.
`tz_source`	str ou None	`"auto"`	Source de fuseau horaire par défaut pour les colonnes sans métadonnées de fuseau horaire : `"auto"`, `"server"` ou `"local"`.
`tz_mode`	str ou None	`"naive_utc"`	Politique des résultats UTC : `"naive_utc"`, `"aware"` ou `"schema"`. Voir Fuseaux horaires.
`show_clickhouse_errors`	bool, chaîne booléenne, `"scrub"` ou None	`True`	Contrôle `str(exc)` pour les erreurs du serveur, les erreurs de transport et les `StreamFailureError` survenant en cours de flux. `True` inclut l’URL de la requête et le suffixe indiquant la version du serveur. `"scrub"` conserve le texte de l’erreur SQL et le nom symbolique, mais supprime l’hôte/l’URL et le suffixe `(version ...)`. `False` renvoie un message générique (`code` reste défini pour les erreurs du serveur). Les chaînes booléennes sont acceptées. Les autres chaînes déclenchent une `ProgrammingError`. Pour les erreurs de transport, `__cause__` et les traces de pile contiennent toujours l’exception de transport d’origine.
`proxy_path`	str	`""`	Préfixe de chemin ajouté à l’URL du serveur lors du routage via un proxy.
`form_encode_query_params`	bool	`False`	Placez toujours les paramètres de requête dans le corps de la requête encodé au format formulaire. Les payloads volumineux de paramètres non binaires sont déplacés automatiquement même lorsque cette valeur est false.
`native_codec`	str ou None	Paramètre global, `"python"`	Codec expérimental pour le trafic au format Native géré par le client : `"python"`, `"rust"` ou `"rust_strict"`. Les valeurs Rust nécessitent le wheel `clickhouse-connect-core`. Voir Codec Rust.
`rename_response_column`	str ou None	`None`	Stratégie de renommage des colonnes : `"remove_prefix"`, `"to_camelcase"`, `"to_camelcase_without_prefix"`, `"to_underscore"`, ou `"to_underscore_without_prefix"`.

Les fabriques HTTP synchrones et asynchrones convertissent les valeurs de type chaîne issues des paramètres de requête du DSN ou de generic_args pour les options de client suivantes : connect_timeout, send_receive_timeout, query_limit et query_retries sont converties dans les types numériques indiqués ci-dessus ; autogenerate_query_id, autogenerate_session_id et form_encode_query_params sont converties en booléens. Toute valeur de type chaîne invalide pour ces options lève une ProgrammingError. La fabrique asynchrone accepte également connector_limit=100, connector_limit_per_host=20 et keepalive_timeout=30.0 pour configurer son pool de connexions aiohttp. Vous pouvez les transmettre directement comme arguments nommés, comme paramètres de requête du DSN ou via generic_args, utilisé en interne pour les connect_args de SQLAlchemy. Les valeurs de type chaîne de ces options de connector sont converties dans les types numériques documentés. Toute valeur de type chaîne invalide pour ces options lève une ProgrammingError. Les arguments nommés explicites différents de None ont préséance sur generic_args, qui a lui-même préséance sur le DSN. La fabrique asynchrone n’accepte pas pool_mgr. Le backend chDB synchrone accepte path et chdb_options ; voir Backend chDB intégré.

Arguments HTTPS/TLS

Parameter	Type	Default	Description
`verify`	bool or str	`True`	Valide le certificat du serveur et le nom d’hôte. `verify="proxy"` active le mode proxy TLS.
`ca_cert`	str or None	`None`	Chemin du bundle CA. Utilisez `"certifi"` pour sélectionner le bundle fourni avec le paquet `certifi`.
`client_cert`	str or None	`None`	Certificat client au format PEM, y compris les certificats intermédiaires si nécessaire.
`client_cert_key`	str or None	`None`	Chemin de la clé privée lorsque celle-ci n’est pas incluse dans `client_cert`.
`server_host_name`	str or None	`None`	Nom d’hôte du certificat TLS/SNI lorsqu’il diffère de `host`, par exemple via un tunnel ou un endpoint privé.
`tls_mode`	str or None	`None`	`"mutual"` utilise l’authentification mutual TLS de ClickHouse. `"proxy"` et `"strict"` envoient le certificat au niveau TLS sans activer les en-têtes d’authentification par certificat de ClickHouse. La valeur par défaut `None` se comporte comme `"mutual"` lorsqu’un certificat client est fourni.

Argument `settings`

Enfin, l’argument settings de get_client permet de transmettre au serveur des settings ClickHouse supplémentaires pour chaque requête client. Notez que, dans la plupart des cas, les utilisateurs disposant d’un accès readonly=1 ne peuvent pas modifier les settings envoyés avec une requête ; ClickHouse Connect supprimera donc ces settings de la requête finale et consignera un avertissement. Les settings suivants s’appliquent uniquement aux requêtes/sessions HTTP utilisées par ClickHouse Connect et ne sont pas documentés comme des settings généraux de ClickHouse.

Setting	Description
`buffer_size`	Taille du tampon de réponse HTTP côté serveur, en octets.
`session_id`	ID de session utilisé pour associer des requêtes liées. Requis pour les tables temporaires et l’état de session.
`compress`	Demande au serveur de compresser une réponse HTTP. Généralement géré par l’option de compression du client.
`decompress`	Indique au serveur de décompresser le corps de la requête. Utilisé pour les inserts bruts précompressés.
`quota_key`	Clé de quota associée à la requête.
`session_check`	Demande au serveur de valider qu’une session existe.
`session_timeout`	Délai d’expiration de l’inactivité de la session, en secondes.
`wait_end_of_query`	Met en tampon la réponse complète sur le serveur. Le client définit ce setting lorsque cela est nécessaire pour les informations récapitulatives non streaming.
`query_id`	ID de requête explicite pour la requête.
`client_protocol_version`	Niveau de capacité du protocole client au format natif. Généralement négocié automatiquement.
`role`	Rôle ClickHouse à utiliser pour la requête/session.

Pour les autres settings ClickHouse pouvant être envoyés avec chaque requête, consultez la documentation ClickHouse.

Exemples de création de client

Sans paramètre, un client ClickHouse Connect se connecte au port HTTP par défaut sur localhost, avec l’utilisateur par défaut et sans mot de passe :

import clickhouse_connect

client = clickhouse_connect.get_client()
print(client.server_version)

Connexion à un serveur ClickHouse externe sécurisé (HTTPS)

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="play.clickhouse.com",
    secure=True,
    port=443,
    username="play",
    password="clickhouse",
)
print(client.command("SELECT timezone()"))

Connexion avec un ID de session, d’autres paramètres de connexion personnalisés et des settings de ClickHouse.

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="play.clickhouse.com",
    username="play",
    password="clickhouse",
    port=443,
    secure=True,
    session_id="example_session_1",
    connect_timeout=15,
    database="github",
    settings={"distributed_ddl_task_timeout": 300},
)
print(client.database)
# Output: github

Backend chDB intégré

Installez clickhouse-connect[chdb] pour utiliser le backend chDB expérimental intégré au processus. Il expose les méthodes synchrones query, insert, streaming et Arrow du client :

import clickhouse_connect

with clickhouse_connect.get_client(interface="chdb") as client:
    result = client.query("SELECT sum(number) FROM numbers(10)")
    print(result.first_row)
    # Output: (45,)

Par défaut, il s’agit d’une base de données en mémoire. Passez path="/data/my_chdb" ou utilisez dsn="chdb:///data/my_chdb" pour bénéficier d’un stockage persistant. Le backend n’autorise qu’un seul path de moteur par processus et ne prend pas en charge get_async_client ni les données externes.

Cycle de vie du client et bonnes pratiques

Créer un client ClickHouse Connect est une opération coûteuse, car elle implique l’établissement d’une connexion, la récupération des métadonnées du serveur et l’initialisation des paramètres. Suivez ces bonnes pratiques pour obtenir des performances optimales :

Principes fondamentaux

Réutilisez les clients : créez les clients une seule fois au démarrage de l’application et réutilisez-les pendant toute sa durée de vie
Évitez les créations fréquentes : ne créez pas de nouveau client pour chaque requête ou demande
Nettoyez correctement : fermez toujours les clients lors de l’arrêt afin de libérer les ressources du pool de connexions
Partagez quand c’est possible : un seul client peut gérer de nombreuses requêtes concurrentes grâce à son pool de connexions (voir les remarques sur les threads ci-dessous)

Quelques principes de base

Réutiliser un seul client :

import clickhouse_connect

# Create once at startup
client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
)

# Reuse for all queries
for i in range(1000):
    result = client.query("SELECT count() FROM users")

# Close on shutdown
client.close()

À éviter : créer des clients à répétition :

# BAD: Creates 1000 clients with expensive initialization overhead
for i in range(1000):
    client = clickhouse_connect.get_client(
        host="my-host",
        username="default",
        password="password",
    )
    result = client.query("SELECT count() FROM users")
    client.close()

Applications multithreadées

Les instances de client ne sont PAS thread-safe lorsqu’elles utilisent des ID de session. Par défaut, les clients ont un ID de session généré automatiquement. Des requêtes concurrentes passant par un même client et la même session provoquent une ProgrammingError lorsque le client détecte un chevauchement local. L’état des sessions nommées et les vérifications de chevauchement de session côté serveur sont propres à un seul processus serveur ClickHouse : un session_id fixe ne constitue donc ni un état distribué ni un mutex distribué dans ClickHouse Cloud ou dans d’autres déploiements avec répartition de charge.

Pour partager un client entre plusieurs threads en toute sécurité :

import clickhouse_connect
import threading

# Option 1: Disable sessions (recommended for shared clients)
client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
    autogenerate_session_id=False,
)

def worker(thread_id):
    # All threads can now safely use the same client
    result = client.query(f"SELECT {thread_id}")
    print(f"Thread {thread_id}: {result.result_rows[0][0]}")

threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
for t in threads:
    t.start()
for t in threads:
    t.join()

client.close()

Option avec sessions : Si vous avez besoin de sessions (par exemple, pour des tables temporaires), créez un client distinct par thread :

def worker(thread_id):
    # Each thread gets its own client with isolated session
    client = clickhouse_connect.get_client(
        host="my-host",
        username="default",
        password="password",
    )
    client.command("CREATE TEMPORARY TABLE temp (id UInt32) ENGINE = Memory")
    # ... use temp table ...
    client.close()

Nettoyage approprié

Fermez toujours les clients lors de l’arrêt. Notez que client.close() libère le client et ferme les connexions HTTP du pool uniquement lorsque le client possède son propre gestionnaire de pool (par exemple, s’il a été créé avec des options TLS/proxy personnalisées). Pour le pool partagé par défaut, utilisez client.close_connections() pour fermer explicitement les sockets ; sinon, les connexions sont récupérées automatiquement à l’expiration de l’inactivité et à la fin du processus.

client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
)
try:
    result = client.query("SELECT 1")
finally:
    client.close()

Ou utilisez un gestionnaire de contexte :

with clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
) as client:
    result = client.query("SELECT 1")

Quand utiliser plusieurs clients

L’utilisation de plusieurs clients est appropriée dans les cas suivants :

Serveurs différents : un client par serveur ClickHouse ou cluster
Identifiants différents : des clients distincts pour différents utilisateurs ou niveaux d’accès
Bases de données différentes : lorsque vous devez travailler avec plusieurs bases de données
Sessions isolées : lorsque vous avez besoin de sessions distinctes pour des tables temporaires ou des paramètres propres à la session
Isolation par thread : lorsque les threads ont besoin de sessions indépendantes (comme indiqué ci-dessus)

Arguments courants des méthodes

Plusieurs méthodes du client utilisent l’un ou les deux arguments communs parameters et settings. Ces arguments nommés sont décrits ci-dessous.

Argument `parameters`

Les méthodes query* et command du ClickHouse Connect Client acceptent un argument nommé facultatif, parameters, utilisé pour associer des expressions Python à une expression de valeur ClickHouse. Deux types de liaison sont possibles.

Liaison côté serveur

ClickHouse prend en charge la liaison côté serveur pour les valeurs des requêtes. La valeur associée est envoyée séparément de la requête, sous forme de paramètre HTTP. ClickHouse Connect utilise ce mode lorsqu’il détecte une expression de la forme {<name>:<datatype>}. Transmettez les valeurs sous la forme d’un dictionnaire Python. Les noms de paramètres doivent être des noms ASCII BareWord ClickHouse. Le driver accepte $ au début, au milieu ou à la fin du nom lorsque le serveur l’accepte, comme dans {$tenant_id:String}. Une clé de dictionnaire qui commence et se termine par $ et dont la valeur est un tampon tel que bytes, bytearray ou memoryview est réservée à la convention de paramètres binaires bruts de ClickHouse Connect. Si une telle clé est utilisée pour un paramètre côté serveur non binaire, limitez-vous à un seul espace réservé {name:Type}. Des noms $tag$ répétés peuvent être interprétés par ClickHouse comme des marqueurs heredoc. Utilisez None de Python pour les valeurs Nullable. Les valeurs None imbriquées sont prises en charge dans les paramètres Array et Tuple, ainsi que dans les littéraux Map lorsque dict_parameter_format est défini sur "map".

Liaison côté serveur avec dictionnaire Python, valeur DateTime et valeur de chaîne de caractères

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {
    "table": "my_table",
    "v1": my_date,
    "v2": "a string with a single quote'",
}
client.query(
    "SELECT * FROM {table:Identifier} "
    "WHERE date >= {v1:DateTime} AND string ILIKE {v2:String}",
    parameters=parameters,
)

Cela équivaut à :

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

La liaison côté serveur fonctionne avec les requêtes SELECT et les instructions INSERT ... VALUES. Pour insérer de gros lots de données simples, privilégiez Client.insert.

Liaison côté client

ClickHouse Connect prend également en charge la liaison de paramètres côté client, ce qui offre davantage de souplesse pour générer des requêtes SQL basées sur des modèles. Pour la liaison côté client, l’argument parameters doit être un dictionnaire ou une séquence. La liaison côté client utilise le formatage de chaînes Python de style “printf” pour la substitution des paramètres. Notez que, contrairement à la liaison côté serveur, la liaison côté client ne fonctionne pas pour les identifiants de base de données tels que les noms de base de données, de table ou de colonne, car le formatage de style Python ne permet pas de distinguer les différents types de chaînes, qui doivent être mis en forme différemment (backticks ou guillemets doubles pour les identifiants de base de données, guillemets simples pour les valeurs de données).

Exemple avec un dictionnaire Python, une valeur DateTime et l’échappement des chaînes

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {"v1": my_date, "v2": "a string with a single quote'"}
client.query(
    "SELECT * FROM my_table "
    "WHERE date >= %(v1)s AND string ILIKE %(v2)s",
    parameters=parameters,
)

Cela génère la requête suivante sur le serveur :

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

Exemple avec une séquence Python (Tuple), Float64 et IPv4Address

import ipaddress

parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe))
client.query(
    "SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s",
    parameters=parameters,
)

Cela génère la requête suivante sur le serveur :

SELECT *
FROM some_table
WHERE metric >= 35200.44
  AND ip_address = '68.61.4.254'

La liaison de datetime considère les valeurs naïves comme des heures d’horloge. Le client met en forme un datetime naïf tel quel. ClickHouse l’interprète en utilisant le fuseau horaire déclaré dans un espace réservé côté serveur tel que {dt:DateTime('Europe/Berlin')}, puis session_timezone lorsqu’il est défini, puis le fuseau horaire du serveur. Un datetime avec fuseau horaire est converti dans le fuseau horaire déclaré dans l’espace réservé lorsqu’il est présent, sinon dans le fuseau horaire du serveur indiqué au moment de la connexion. Si le paramètre session_timezone diffère de ce fuseau horaire du serveur indiqué, déclarez un fuseau horaire dans l’espace réservé afin de conserver l’instant souhaité pour les valeurs avec fuseau horaire.Pour une compatibilité temporaire avec l’ancienne conversion locale à l’hôte, définissez common.set_setting("naive_datetime_binding", "legacy") avant de lier les paramètres. Pour préserver un instant, attachez le tzinfo voulu à la valeur datetime avant de la transmettre en tant que paramètre. Les insertions dans des colonnes DateTime ou DateTime64 via client.insert interprètent par défaut les valeurs datetime naïves dans le fuseau horaire local du processus. Définissez le paramètre global naive_datetime_insert sur "server" pour les interpréter comme des heures locales dans le fuseau horaire de la colonne, ou dans le fuseau horaire du serveur lorsque la colonne n’en possède pas. Consultez Objets datetime sans fuseau horaire.Les insertions natives dans des colonnes Date et Date32 utilisent la date calendaire propre à la valeur Python datetime, sans conversion de fuseau horaire. Lorsque la même date calendaire est nécessaire à la fois pour une insertion et pour un paramètre de requête, transmettez explicitement value.date(). Consultez Valeurs Date et Date32.Pour un espace réservé {value:DateTime64(precision)} côté serveur, le type déclaré préserve automatiquement la précision à la sous-seconde, y compris dans les indications Array et Tuple.La liaison %s côté client n’a pas de type déclaré. Enveloppez un datetime dans DT64Param lorsqu’il doit être mis en forme avec une précision à la sous-seconde :

from datetime import datetime

from clickhouse_connect.driver.binding import DT64Param

query = "SELECT toDateTime64(%s, 6)"
parameters = [DT64Param(datetime.now())]
client.query(query, parameters=parameters)

Pour la rétrocompatibilité, un nom de paramètre de dictionnaire se terminant par _64 demande également un formatage DateTime64 lorsque ce nom suffixé exact n’est pas présent dans la requête.Un paramètre datetime.time ou datetime.timedelta est mis en forme comme un littéral [-]HH:MM:SS[.ffffff] pour les colonnes ClickHouse Time et Time64, dans les deux styles de liaison et dans les valeurs Array et Tuple. Le client ajoute les guillemets ; ne mettez donc pas l’espace réservé entre guillemets dans la requête. Un timedelta peut être négatif et dépasser 24 heures. Un Timedelta pandas conserve ses nanosecondes et met en forme une fraction de neuf chiffres pour Time64(9). Les informations de fuseau horaire d’un time avec fuseau horaire sont ignorées, car ClickHouse Time ne possède pas de fuseau horaire.

Argument `settings`

Toutes les principales méthodes “insert” et “select” de ClickHouse Connect Client acceptent un argument de mot-clé settings facultatif pour transmettre les settings utilisateur du serveur ClickHouse pour l’instruction SQL concernée. L’argument settings doit être un dictionnaire. Chaque élément doit contenir un nom de setting ClickHouse et la valeur associée. Notez que les valeurs seront converties en chaînes de caractères lorsqu’elles seront envoyées au serveur comme paramètres de requête. Comme pour les settings au niveau du client, ClickHouse Connect ignorera tous les settings que le serveur marque comme readonly=1, avec un message de log associé. Les settings qui s’appliquent uniquement aux requêtes via l’interface HTTP de ClickHouse sont toujours valides. Ces settings sont décrits dans l’API get_client. Exemple d’utilisation des settings ClickHouse :

settings = {
    "merge_tree_min_rows_for_concurrent_read": 65535,
    "session_id": "session_1234",
    "use_skip_indexes": False,
}
client.query(
    "SELECT event_type, sum(timeout) "
    "FROM event_errors WHERE event_time > '2022-08-01'",
    settings=settings,
)

Méthode `command` du Client

Utilisez Client.command pour les instructions qui ne renvoient pas de jeu de données tabulaire, ou pour les requêtes qui renvoient une valeur primitive ou une ligne de valeurs. Selon la réponse, cette méthode peut renvoyer une chaîne, un entier, une séquence de chaînes ou QuerySummary. Une lecture qui produit un jeu de résultats vide renvoie une chaîne vide.

Paramètre	Type	Par défaut	Description
cmd	str	Obligatoire	Une instruction ClickHouse SQL qui renvoie une seule valeur ou une seule ligne de valeurs.
parameters	dict or sequence	None	Voir la description des paramètres.
data	str or bytes	None	Données facultatives à inclure avec la commande dans le corps de la requête POST.
settings	dict	None	Voir la description des settings.
use_database	bool	True	Utilise la base de données du client (spécifiée lors de la création du client). False signifie que la commande utilisera la base de données par défaut du serveur ClickHouse pour l’utilisateur connecté.
external_data	ExternalData	None	Objet `ExternalData` contenant des fichiers ou des données binaires à utiliser avec la requête. Voir Advanced Queries (External Data)
transport_settings	dict	None	Dictionnaire facultatif d’en-têtes HTTP à inclure dans cette requête. Chaque paire clé-valeur est ajoutée comme un en-tête HTTP (par ex., `{'X-Custom-Header': 'value'}`). Utile pour l’authentification du proxy, le traçage des requêtes ou la transmission d’en-têtes requis par l’infrastructure intermédiaire.

Exemples de commandes

Instructions DDL

import clickhouse_connect

client = clickhouse_connect.get_client()

# Create a table. A successful DDL returns QuerySummary.
summary = client.command(
    "CREATE TABLE test_command "
    "(col_1 String, col_2 DateTime) "
    "ENGINE MergeTree ORDER BY tuple()"
)
print(summary.query_id())

# Show table definition
result = client.command("SHOW CREATE TABLE test_command")
print(result)
# Output:
# CREATE TABLE default.test_command
# (
#     `col_1` String,
#     `col_2` DateTime
# )
# ENGINE = MergeTree
# ORDER BY tuple()

# Drop table
client.command("DROP TABLE test_command")

Requêtes simples renvoyant une seule valeur

import clickhouse_connect

client = clickhouse_connect.get_client()

# Single value result
count = client.command("SELECT count() FROM system.tables")
print(count)

# Server version
version = client.command("SELECT version()")
print(version)

Commandes avec paramètres

import clickhouse_connect

client = clickhouse_connect.get_client()

# Using client-side parameters
table_name = "system"
result = client.command(
    "SELECT count() FROM system.tables WHERE database = %(db)s",
    parameters={"db": table_name}
)

# Using server-side parameters
result = client.command(
    "SELECT count() FROM system.tables WHERE database = {db:String}",
    parameters={"db": "system"}
)

Commandes avec settings

import clickhouse_connect

client = clickhouse_connect.get_client()

# Execute command with specific settings
result = client.command(
    "OPTIMIZE TABLE large_table FINAL",
    settings={"optimize_throw_if_noop": 1}
)

Méthode `query` du Client

Client.query récupère un jeu de données tabulaire au format Native de ClickHouse et renvoie un QueryResult. Le résultat complet est matérialisé dès qu’une propriété du résultat est consultée. Utilisez une méthode de streaming pour les résultats qui ne doivent pas être conservés en mémoire.

Lorsque le client détecte un LIMIT 0 en fin de requête, il demande les métadonnées des colonnes au format JSON. Si la réponse contient des lignes, il lève clickhouse_connect.driver.exceptions.InternalError sans réexécuter la requête. Cela peut se produire avec des requêtes UNION, EXCEPT ou EXPLAIN se terminant par LIMIT 0.Pour ces requêtes, utilisez raw_query avec un format de sortie tel que fmt="JSON". Cette méthode renvoie des bytes que votre application devra décoder. Ce comportement s’applique aux clients HTTP synchrones, HTTP asynchrones et chDB.

Paramètre	Type	Par défaut	Description
`query`	str	Obligatoire	Requête ClickHouse qui renvoie un résultat tabulaire, le plus souvent `SELECT` ou `DESCRIBE`. Peut être omise si elle est fournie par `context`.
`parameters`	dict or sequence	`None`	Voir l’argument Parameters.
`settings`	dict	`None`	Voir l’argument paramètres.
`query_formats`	dict	`None`	Format de lecture par type ClickHouse. Voir Formats de lecture.
`column_formats`	dict	`None`	Format de lecture par colonne de résultat, y compris les mappages de format pour le type Nested.
`encoding`	str	`None`	Encodage des colonnes de type String. UTF-8 est utilisé par défaut.
`use_none`	bool	`True`	Renvoyer `None` pour SQL NULL. Si false, renvoyer la valeur NULL par défaut du type. Les méthodes NumPy/Pandas choisissent des valeurs par défaut optimisées pour les performances.
`column_oriented`	bool	`False`	Présente le résultat en colonnes plutôt qu’en lignes.
`use_numpy`	bool	`False`	Lit les colonnes de résultat compatibles dans des tableaux NumPy au sein du `QueryResult`. Préférez `query_np` si le résultat souhaité est une seule matrice NumPy.
`max_str_len`	int	`0`	Avec `use_numpy`, utilise un `dtype` Unicode à largeur fixe pour les colonnes de type String jusqu’à cette longueur. La valeur zéro utilise des tableaux d’objets.
`context`	`QueryContext`	`None`	Contexte de requête réutilisable. Les arguments de méthode explicitement fournis remplacent les valeurs du contexte.
`query_tz`	str or `tzinfo`	`None`	Fuseau horaire appliqué à toutes les colonnes de résultat `DateTime` et `DateTime64`.
`column_tzs`	dict	`None`	Mappage des fuseaux horaires par colonne.
`external_data`	`ExternalData`	`None`	Fichier externe ou données binaires. Voir Données externes.
`transport_settings`	dict	`None`	En-têtes HTTP ajoutés à cette requête.
`tz_mode`	str	Par défaut du client	Remplacement par requête pour la gestion des fuseaux horaires `"naive_utc"`, `"aware"` ou `"schema"`.

Exemples de requêtes

Requête de base

import clickhouse_connect

client = clickhouse_connect.get_client()

# Simple SELECT query
result = client.query(
    "SELECT number, toString(number) AS label FROM numbers(3)"
)

# Access results as rows
for row in result.result_rows:
    print(row)
# Output:
# (0, '0')
# (1, '1')
# (2, '2')

# Access column names and types
print(result.column_names)
# Output: ('number', 'label')
print([col_type.name for col_type in result.column_types])
# Output: ['UInt64', 'String']

Accéder au résultat de la requête

import clickhouse_connect

client = clickhouse_connect.get_client()

result = client.query("SELECT number, toString(number) AS str FROM system.numbers LIMIT 3")

# Row-oriented access (default)
print(result.result_rows)
# Output: [(0, '0'), (1, '1'), (2, '2')]

# Column-oriented access
print(result.result_columns)
# Output: [[0, 1, 2], ['0', '1', '2']]

# Named results (list of dictionaries)
for row_dict in result.named_results():
    print(row_dict)
# Output:
# {'number': 0, 'str': '0'}
# {'number': 1, 'str': '1'}
# {'number': 2, 'str': '2'}

# First row as dictionary
print(result.first_item)
# Output: {'number': 0, 'str': '0'}

# First row as tuple
print(result.first_row)
# Output: (0, '0')

Requête avec paramètres côté client

import clickhouse_connect

client = clickhouse_connect.get_client()

# Using dictionary parameters (printf-style)
query = "SELECT * FROM system.tables WHERE database = %(db)s AND name LIKE %(pattern)s"
parameters = {"db": "system", "pattern": "%query%"}
result = client.query(query, parameters=parameters)

# Using tuple parameters
query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s"
parameters = ("system", 5)
result = client.query(query, parameters=parameters)

Requête avec paramètres côté serveur

import clickhouse_connect

client = clickhouse_connect.get_client()

# Server-side binding (more secure, better performance for SELECT queries)
query = "SELECT * FROM system.tables WHERE database = {db:String} AND name = {tbl:String}"
parameters = {"db": "system", "tbl": "query_log"}

result = client.query(query, parameters=parameters)

Requête avec setting

import clickhouse_connect

client = clickhouse_connect.get_client()

# Pass ClickHouse settings with the query
result = client.query(
    "SELECT sum(number) FROM numbers(1000000)",
    settings={
        "max_block_size": 100000,
        "max_execution_time": 30
    }
)

L’objet `QueryResult`

La méthode query de base renvoie un objet QueryResult avec les propriétés publiques suivantes :

result_rows — Matrice de résultats orientée par lignes.
result_columns — Matrice de résultats orientée par colonnes.
result_set — result_rows ou result_columns, selon l’orientation de la requête.
column_names — Tuple contenant les noms des colonnes du résultat.
column_types — Tuple d’objets ClickHouseType.
row_count — Nombre de lignes de résultat matérialisées.
query_id — ID de requête renvoyé ou généré pour la requête. Une chaîne vide signifie qu’aucun n’était disponible.
summary — Dictionnaire décodé à partir de l’en-tête de réponse X-ClickHouse-Summary.
first_item — Première ligne sous forme de dictionnaire, ou None si le résultat est vide.
first_row — Première ligne sous forme de séquence, ou None si le résultat est vide.
column_block_stream, row_block_stream et rows_stream — Contextes de flux internes. Utilisez plutôt les méthodes de streaming correspondantes du client.

Voir Requêtes en streaming pour les API StreamContext prises en charge.

Consommer les résultats des requêtes avec NumPy, Pandas ou Arrow

ClickHouse Connect fournit des méthodes de requête spécialisées pour les formats de données NumPy, Pandas et Arrow. Pour plus d’informations sur l’utilisation de ces méthodes, notamment des exemples, la prise en charge du streaming et la gestion avancée des types, consultez Requêtes avancées (requêtes NumPy, Pandas et Arrow).

Méthodes du Client pour les requêtes en streaming

Pour le streaming de grands ensembles de résultats, ClickHouse Connect propose plusieurs méthodes de streaming. Consultez Requêtes avancées (requêtes en streaming) pour plus de détails et d’exemples.

Méthode `insert` du Client

Pour le cas d’usage courant consistant à insérer plusieurs enregistrements dans ClickHouse, il existe la méthode Client.insert. Elle accepte les paramètres suivants :

Paramètre	Type	Par défaut	Description
`table`	str	Obligatoire	Table cible. Un nom qualifié par la base de données est autorisé. Peut être omis lorsqu’il est fourni par `context`.
`data`	Sequence of Sequences	Obligatoire	Matrice de données orientée lignes ou orientée colonnes. Peut être fournie ultérieurement via un `InsertContext`.
`column_names`	str or Sequence[str]	`"*"`	Colonnes ordonnées. `"*"` exécute une requête de métadonnées pour découvrir toutes les colonnes dans lesquelles des insertions sont possibles.
`database`	str or None	Base de données du client	Base de données cible lorsque `table` n’est pas qualifiée.
`column_types`	Sequence[`ClickHouseType`]	`None`	Types de colonnes explicites. Évite la requête de métadonnées lorsqu’ils sont fournis.
`column_type_names`	Sequence[str]	`None`	Noms de types ClickHouse explicites. Alternative à `column_types`.
`column_oriented`	bool	`False`	Interprète `data` comme des colonnes plutôt que comme des lignes.
`settings`	dict	`None`	Voir Settings argument.
`context`	`InsertContext`	`None`	Contexte d’insertion réutilisable. Voir InsertContexts.
`transport_settings`	dict	`None`	En-têtes HTTP ajoutés à cette requête.

Cette méthode renvoie QuerySummary. Son dictionnaire summary contient les valeurs renvoyées par le server. written_rows est une propriété pratique, tandis que written_bytes() et query_id() renvoient les valeurs correspondantes. En cas d’échec de l’insertion, une exception est levée. Pour les méthodes d’insertion spécialisées qui fonctionnent avec les Pandas DataFrames, les tables PyArrow et les DataFrames basés sur Arrow, voir Insertion avancée (méthodes d’insertion spécialisées).

Un tableau NumPy est une Sequence of Sequences valide et peut être utilisé comme argument data de la méthode principale insert ; une méthode spécialisée n’est donc pas nécessaire.

Exemples

Les exemples ci-dessous partent du principe qu’une table users existe déjà, avec le schéma (id UInt32, name String, age UInt8).

Insertion simple par ligne

import clickhouse_connect

client = clickhouse_connect.get_client()

# Row-oriented data: each inner list is a row
data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

client.insert("users", data, column_names=["id", "name", "age"])

Insertion par colonnes

import clickhouse_connect

client = clickhouse_connect.get_client()

# Column-oriented data: each inner list is a column
data = [
    [13, 79],  # id column
    ["user_1", "user_2"],  # name column
    [25, 30],  # age column
]

client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True)

Insertion avec des types de colonnes explicitement spécifiés

import clickhouse_connect

client = clickhouse_connect.get_client()

# Useful when you want to avoid a DESCRIBE query to the server
data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    column_type_names=["UInt32", "String", "UInt8"],
)

Insérer dans une base de données spécifique

import clickhouse_connect

client = clickhouse_connect.get_client()

data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

# Insert into a table in a specific database
client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    database="production",
)

Insertions depuis des fichiers

Pour insérer des données directement depuis des fichiers dans des tables ClickHouse, consultez Insertion avancée (insertions depuis des fichiers).

API brute

Pour les cas d’usage avancés nécessitant un accès direct à l’interface HTTP de ClickHouse, sans transformation de type, consultez Utilisation avancée (API brute).

Python DB-API 2.0

Le module clickhouse_connect.dbapi implémente l’interface de connexion et de curseur définie par la PEP 249. Il déclare un niveau d’API de 2.0, threadsafety=2 et paramstyle="pyformat". Le module fournit également les constructeurs de types PEP 249 Date, Time, Timestamp et Binary, ainsi que les fonctions DateFromTicks, TimeFromTicks et TimestampFromTicks. Le module exporte la hiérarchie d’exceptions de la PEP 249 : Warning, Error, InterfaceError, DatabaseError, DataError, OperationalError, IntegrityError, InternalError, ProgrammingError et NotSupportedError. Il s’agit des mêmes objets de classe que ceux exposés par clickhouse_connect.driver.exceptions : quel que soit le chemin d’importation utilisé, les erreurs du driver sont donc interceptées. L’exception StreamFailureError, propre au driver, reste disponible dans clickhouse_connect.driver.exceptions et hérite de OperationalError.

from clickhouse_connect import dbapi

connection = dbapi.connect(
    host="localhost",
    username="default",
    password="password",
    database="default",
)
cursor = connection.cursor()

try:
    cursor.execute(
        "SELECT name FROM system.tables "
        "WHERE database = %(database)s ORDER BY name LIMIT 5",
        {"database": "system"},
    )
    print(cursor.description)
    print(cursor.fetchall())
finally:
    cursor.close()
    connection.close()

Cursor.execute et Cursor.executemany acceptent des arguments nommés supplémentaires settings et query_formats. settings transmet les paramètres de ClickHouse. query_formats applique des formats de lecture selon le type ClickHouse lorsqu’une instruction renvoie des lignes, en utilisant le même mapping que Client.query. Les deux méthodes acceptent également l’argument nommé uniquement pyformat_encoded. Sa valeur par défaut, True, respecte le contrat DB-API pyformat. Le dialecte SQLAlchemy le définit sur False lorsque le compilateur d’instructions a émis des signes de pourcentage bruts, les applications ne devraient donc normalement pas le définir. Les opérations Cursor.executemany paramétrées s’exécutent une fois par set de paramètres, en préservant la sémantique de liaison SQL et d’évaluation des expressions. Avec HTTP, une requête est donc envoyée par set de paramètres. Si un set de paramètres ultérieur échoue, les écritures précédentes restent validées. Pour ces insertions via executemany, Cursor.rowcount correspond à la somme des valeurs written_rows renvoyées par ClickHouse, ou à -1 lorsque cette valeur n’est pas disponible. Les instructions INSERT envoyées via Cursor.execute renvoient 0. La forme de compatibilité INSERT INTO table (columns) VALUES sans caractère de substitution utilise l’insertion Native. Une instruction INSERT sans caractère de substitution se terminant par VALUES lève ProgrammingError si elle n’est pas reconnue comme cette forme de compatibilité. Les applications qui ont besoin d’une insertion en bloc Native explicite doivent utiliser Client.insert. fetchone, fetchmany et fetchall consomment le jeu de résultats matérialisé courant. Cursor.description déduit null_ok du type de chaque colonne de résultat. Les types non nullables renvoient False, et les types nullables renvoient True, y compris les wrappers Nullable, Variant et Dynamic. None signifie que la nullabilité est inconnue. Lorsqu’une requête commençant par SELECT ou WITH, en ignorant les commentaires initiaux, ne renvoie ni lignes ni métadonnées de colonnes, le curseur exécute une requête de métadonnées avec LIMIT 0 pour renseigner description. Si cette requête de métadonnées échoue, description reste vide. ClickHouse ne fournit pas de transactions traditionnelles via cette interface HTTP. Connection.commit() et Connection.rollback() sont des opérations sans effet. Les règles de concurrence liées aux ID de session s’appliquent toujours lorsqu’une connexion est partagée.

Classes et fonctions utilitaires

Les modules suivants fournissent des utilitaires publics supplémentaires pour les applications clientes. La version du paquet installé est exposée sous forme de chaîne dans clickhouse_connect.__version__.

Exceptions

Les exceptions personnalisées, y compris la hiérarchie d’exceptions DB-API 2.0 réexportée par clickhouse_connect.dbapi, sont définies dans clickhouse_connect.driver.exceptions. DatabaseError et OperationalError exposent un attribut numérique code contenant le code d’erreur ClickHouse, ainsi qu’un attribut name contenant le nom symbolique tel que UNKNOWN_TABLE, afin que les applications puissent s’appuyer sur exc.code au lieu d’analyser le message. code est défini même lorsque show_clickhouse_errors est désactivé, tandis que name exige les détails de l’erreur (True ou "scrub"). Tous deux valent None lorsqu’ils ne sont pas disponibles, par exemple en cas d’erreurs de transport. Utilisez show_clickhouse_errors="scrub" lorsque les utilisateurs finaux doivent voir les erreurs SQL sans informations sur l’hôte ou la version du server. Ce paramètre contrôle également les messages StreamFailureError en cours de transmission et les messages de transport génériques. Il régit uniquement str(exc). Les erreurs de transport restent attachées en tant que __cause__, et les traces de pile peuvent contenir le texte d’erreur d’origine de l’hôte, de l’URL ou de la bibliothèque.

Utilitaires SQL ClickHouse

Les fonctions et la classe DT64Param du module clickhouse_connect.driver.binding peuvent être utilisées pour construire correctement les requêtes ClickHouse SQL et en échapper correctement le contenu. De même, les fonctions du module clickhouse_connect.driver.parser peuvent être utilisées pour analyser les noms de types de données ClickHouse.

Cas d’utilisation pour les applications multithread, multiprocessus et asynchrones/événementielles

Pour savoir comment utiliser ClickHouse Connect dans des applications multithread, multiprocessus et asynchrones/événementielles, consultez Utilisation avancée (cas d’utilisation pour les applications multithread, multiprocessus et asynchrones/événementielles).

AsyncClient

Pour une utilisation native d’asyncio, consultez Utilisation avancée (AsyncClient).

Gestion des ID de session de ClickHouse

Pour savoir comment gérer les ID de session de ClickHouse dans des applications multithreadées ou concurrentes, consultez Utilisation avancée (Gestion des ID de session de ClickHouse).

Personnaliser le pool de connexions HTTP

Pour plus d’informations sur la personnalisation du pool de connexions HTTP pour les applications multithread de grande taille, consultez Utilisation avancée (Personnaliser le pool de connexions HTTP).

​Initialisation du client

​Arguments de connexion

​Arguments HTTPS/TLS

​Argument settings

​Exemples de création de client

​Backend chDB intégré

​Cycle de vie du client et bonnes pratiques

​Principes fondamentaux

​Quelques principes de base

​Applications multithreadées

​Nettoyage approprié

​Quand utiliser plusieurs clients

​Arguments courants des méthodes

​Argument parameters

​Liaison côté serveur

​Liaison côté client

​Argument settings

​Méthode command du Client

​Exemples de commandes

​Instructions DDL

​Requêtes simples renvoyant une seule valeur

​Commandes avec paramètres

​Commandes avec settings

​Méthode query du Client

​Exemples de requêtes

​Requête de base

​Accéder au résultat de la requête

​Requête avec paramètres côté client

​Requête avec paramètres côté serveur

​Requête avec setting

​L’objet QueryResult

​Consommer les résultats des requêtes avec NumPy, Pandas ou Arrow

​Méthodes du Client pour les requêtes en streaming

​Méthode insert du Client

​Exemples

​Insertion simple par ligne

​Insertion par colonnes

​Insertion avec des types de colonnes explicitement spécifiés

​Insérer dans une base de données spécifique

​Insertions depuis des fichiers

​API brute

​Python DB-API 2.0

​Classes et fonctions utilitaires

​Exceptions

​Utilitaires SQL ClickHouse

​Cas d’utilisation pour les applications multithread, multiprocessus et asynchrones/événementielles

​AsyncClient

​Gestion des ID de session de ClickHouse

​Personnaliser le pool de connexions HTTP

Initialisation du client

Arguments de connexion

Arguments HTTPS/TLS

Argument `settings`

Exemples de création de client

Backend chDB intégré

Cycle de vie du client et bonnes pratiques

Principes fondamentaux

Quelques principes de base

Applications multithreadées

Nettoyage approprié

Quand utiliser plusieurs clients

Arguments courants des méthodes

Argument `parameters`

Liaison côté serveur

Liaison côté client

Argument `settings`

Méthode `command` du Client

Exemples de commandes

Instructions DDL

Requêtes simples renvoyant une seule valeur

Commandes avec paramètres

Commandes avec settings

Méthode `query` du Client

Exemples de requêtes

Requête de base

Accéder au résultat de la requête

Requête avec paramètres côté client

Requête avec paramètres côté serveur

Requête avec setting

L’objet `QueryResult`

Consommer les résultats des requêtes avec NumPy, Pandas ou Arrow

Méthodes du Client pour les requêtes en streaming

Méthode `insert` du Client

Exemples

Insertion simple par ligne

Insertion par colonnes

Insertion avec des types de colonnes explicitement spécifiés

Insérer dans une base de données spécifique

Insertions depuis des fichiers

API brute

Python DB-API 2.0

Classes et fonctions utilitaires

Exceptions

Utilitaires SQL ClickHouse

Cas d’utilisation pour les applications multithread, multiprocessus et asynchrones/événementielles

AsyncClient

Gestion des ID de session de ClickHouse

Personnaliser le pool de connexions HTTP