API du driver ClickHouse Connect

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.

La fabrique asynchrone accepte aussi connector_limit=100, connector_limit_per_host=20 et keepalive_timeout=30.0 pour configurer son pool de connexions aiohttp. Elle n'accepte pas pool_mgr. Le backend chDB synchrone accepte path et chdb_options ; voir backend chDB intégré.

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.

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

• 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

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.

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 :

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

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

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

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

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)

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.

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.

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 pilote 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 buffer 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\''

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'

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

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.

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

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)

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"}
)

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

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.

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']

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

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)

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)

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

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.

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

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.

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 :

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

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

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

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)

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"],
)

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",
)

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

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

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.

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. Cursor.execute accepte é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. executemany utilise le mécanisme Native d’insertion en bloc du driver pour les instructions INSERT ... VALUES compatibles, avec une séquence matérialisée de lignes. 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.

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

Les exceptions personnalisées, y compris la hiérarchie d’exceptions DB-API 2.0, 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.

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.

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

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

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

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