}`. Transmettez les valeurs sous la forme d'un dictionnaire Python.
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
```python theme={null}
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 à :
```sql theme={null}
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 est prise en charge pour les requêtes `SELECT`. Elle ne fonctionne pas avec `ALTER`, `DELETE`, `INSERT` ni avec les autres types d’instructions.
#### 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"](https://docs.python.org/3/library/stdtypes.html#old-string-formatting) 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
```python theme={null}
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 :
```sql theme={null}
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
```python theme={null}
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 :
```sql theme={null}
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 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](/fr/integrations/language-clients/python/advanced-inserting#timezone-naive-datetime-objects).
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 :
```python theme={null}
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](/fr/reference/settings/session-settings) 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](#settings-argument) `get_client`.
Exemple d’utilisation des settings ClickHouse :
```python theme={null}
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](#parameters-argument). |
| 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](#settings-argument-1). |
| 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)](/fr/integrations/language-clients/python/advanced-querying#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
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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.
| 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](#parameters-argument). |
| `settings` | dict | `None` | Voir [l'argument Settings](#settings-argument-1). |
| `query_formats` | dict | `None` | Format de lecture par type ClickHouse. Voir [Formats de lecture](/fr/integrations/language-clients/python/advanced-querying#read-formats). |
| `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](/fr/integrations/language-clients/python/advanced-querying#external-data). |
| `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
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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](/fr/integrations/language-clients/python/advanced-querying#streaming-queries) 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)](/fr/integrations/language-clients/python/advanced-querying#numpy-pandas-and-arrow-queries).
## 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)](/fr/integrations/language-clients/python/advanced-querying#streaming-queries) 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](#settings-argument-1). |
| `context` | `InsertContext` | `None` | Contexte d’insertion réutilisable. Voir [InsertContexts](/fr/integrations/language-clients/python/advanced-inserting#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)](/fr/integrations/language-clients/python/advanced-inserting#specialized-insert-methods).
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
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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)](/fr/integrations/language-clients/python/advanced-inserting#file-inserts).
## 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)](/fr/integrations/language-clients/python/advanced-usage#raw-api).
## 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`.
```python theme={null}
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`. `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](/fr/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids) 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, 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)](/fr/integrations/language-clients/python/advanced-usage#multithreaded-multiprocess-and-asyncevent-driven-use-cases).
## AsyncClient
Pour une utilisation native d’asyncio, consultez [Utilisation avancée (AsyncClient)](/fr/integrations/language-clients/python/advanced-usage#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)](/fr/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids).
## 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)](/fr/integrations/language-clients/python/advanced-usage#customizing-the-http-connection-pool).