> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Utilisation avancée avec ClickHouse Connect
# Utilisation avancée
## API brute
Pour les cas d'utilisation qui ne nécessitent aucune transformation entre les données ClickHouse et des types de données ou structures natifs ou tiers, le client ClickHouse Connect fournit des méthodes permettant d'utiliser directement la connexion à ClickHouse.
### Méthode `raw_query` du Client
La méthode `Client.raw_query` permet d'utiliser directement l'interface de requête HTTP de ClickHouse via la connexion du client. La valeur renvoyée est un objet `bytes` brut. Elle fournit un wrapper pratique avec liaison des paramètres, gestion des erreurs, nouvelles tentatives et gestion des paramètres, au moyen d'une interface minimale :
| Parameter | Type | Default | Description |
| -------------- | ---------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | str | *Obligatoire* | Toute requête ClickHouse valide |
| parameters | dict or iterable | *None* | Voir la [description des paramètres](/docs/fr/integrations/language-clients/python/driver-api#parameters-argument). |
| settings | dict | *None* | Voir la [description des paramètres](/docs/fr/integrations/language-clients/python/driver-api#settings-argument). |
| fmt | str | *None* | Format de sortie ClickHouse pour les `bytes` renvoyés. (ClickHouse utilise TSV si rien n'est spécifié.) |
| use\_database | bool | True | Utilise la base de données assignée au client ClickHouse Connect pour le contexte de la requête |
| external\_data | ExternalData | *None* | Objet ExternalData contenant des données de fichier ou des données binaires à utiliser avec la requête. Voir [Requêtes avancées (données externes)](/docs/fr/integrations/language-clients/python/advanced-querying#external-data) |
Il revient à l'appelant de gérer l'objet `bytes` renvoyé. Notez que `Client.query_arrow` n'est qu'un fin wrapper autour de cette méthode, utilisant le format de sortie ClickHouse `Arrow`.
### Méthode `raw_stream` du Client
La méthode `Client.raw_stream` possède la même API que la méthode `raw_query`, mais elle renvoie un objet `io.IOBase` pouvant être utilisé comme générateur ou source de flux d’objets `bytes`. Elle est actuellement utilisée par la méthode `query_arrow_stream`.
### Méthode `raw_insert` de `Client`
La méthode `Client.raw_insert` permet d’effectuer des insertions directes d’objets `bytes` ou de générateurs d’objets `bytes` via la connexion du client. Comme elle n’effectue aucun traitement de la charge utile d’insertion, elle offre d’excellentes performances. Cette méthode propose des options pour spécifier les paramètres et le format d’insertion :
| Paramètre | Type | Défaut | Description |
| ------------- | --------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
| table | str | *Required* | Nom de table simple ou qualifié par la base de données |
| column\_names | Sequence\[str] | *None* | Noms de colonnes pour le bloc d’insertion. Obligatoire si le paramètre `fmt` ne contient pas les noms |
| insert\_block | str, bytes, Generator\[bytes], BinaryIO | *Required* | Données à insérer. Les chaînes seront encodées avec l’encodage du client. |
| settings | dict | *None* | Voir la [description du paramètre settings](/docs/fr/integrations/language-clients/python/driver-api#settings-argument). |
| fmt | str | *None* | Format d’entrée ClickHouse des octets de `insert_block`. (ClickHouse utilise TSV s’il n’est pas spécifié) |
Il revient à l’appelant de s’assurer que `insert_block` est dans le format spécifié et utilise la méthode de compression indiquée. ClickHouse Connect utilise ces insertions directes pour les téléversements de fichiers et les tables PyArrow, en déléguant l’analyse au serveur ClickHouse.
## Enregistrer les résultats de la requête dans des fichiers
Vous pouvez transférer des fichiers directement depuis ClickHouse vers le système de fichiers local à l’aide de la méthode `raw_stream`. Par exemple, si vous souhaitez enregistrer le résultat d’une requête dans un fichier CSV, vous pouvez utiliser l’extrait de code suivant :
```python theme={null}
import clickhouse_connect
if __name__ == '__main__':
client = clickhouse_connect.get_client()
query = 'SELECT number, toString(number) AS number_as_str FROM system.numbers LIMIT 5'
fmt = 'CSVWithNames' # or CSV, or CSVWithNamesAndTypes, or TabSeparated, etc.
stream = client.raw_stream(query=query, fmt=fmt)
with open("output.csv", "wb") as f:
for chunk in stream:
f.write(chunk)
```
Le code ci-dessus produit un fichier `output.csv` contenant le contenu suivant :
```csv theme={null}
"number","number_as_str"
0,"0"
1,"1"
2,"2"
3,"3"
4,"4"
```
De même, vous pouvez enregistrer les données au format [TabSeparated](/docs/fr/reference/formats/TabSeparated/TabSeparated), ainsi que dans d'autres formats. Consultez [Formats des données d'entrée et de sortie](/docs/fr/reference/formats) pour une vue d'ensemble de tous les formats disponibles.
## Cas d’usage multithread, multiprocessus et async/pilotés par événements
ClickHouse Connect fonctionne bien dans les applications multithread, multiprocessus et async/pilotées par événements. Tout le traitement des requêtes et des insertions s’effectue dans un seul thread, de sorte que les opérations sont généralement thread-safe. (Le traitement parallèle de certaines opérations à bas niveau constitue une amélioration possible à l’avenir pour surmonter le surcoût de performance lié à un seul thread, mais même dans ce cas, le caractère thread-safe sera maintenu.)
Comme chaque requête ou insertion exécutée conserve son état dans son propre objet `QueryContext` ou `InsertContext`, respectivement, ces objets auxiliaires ne sont pas thread-safe et ne doivent pas être partagés entre plusieurs flux de traitement. Consultez également la discussion sur les objets de contexte dans les sections [QueryContexts](/docs/fr/integrations/language-clients/python/advanced-querying#querycontexts) et [InsertContexts](/docs/fr/integrations/language-clients/python/advanced-inserting#insertcontexts).
De plus, dans une application qui a au moins deux requêtes et/ou insertions « en cours » en même temps, il y a deux autres points à garder à l’esprit. Le premier est la « session » ClickHouse associée à la requête/insertion, et le second est le pool de connexions HTTP utilisé par les instances de ClickHouse Connect Client.
## Wrapper pour AsyncClient
ClickHouse Connect fournit un wrapper async autour du `Client` standard, ce qui permet d'utiliser le client dans un environnement `asyncio`.
Pour obtenir une instance d'`AsyncClient`, vous pouvez utiliser la fonction de fabrique `get_async_client`, qui accepte les mêmes paramètres que `get_client` :
```python theme={null}
import asyncio
import clickhouse_connect
async def main():
client = await clickhouse_connect.get_async_client()
result = await client.query("SELECT name FROM system.databases LIMIT 1")
print(result.result_rows)
# Output:
# [('INFORMATION_SCHEMA',)]
asyncio.run(main())
```
`AsyncClient` possède les mêmes méthodes et les mêmes paramètres que le `Client` standard, mais il s’agit de coroutines lorsque c’est applicable. En interne, les méthodes du `Client` qui effectuent des opérations d’IO sont encapsulées dans un appel à [run\_in\_executor](https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor).
Les performances en mode multithread s’améliorent avec le wrapper `AsyncClient`, car les execution threads et le GIL sont libérés pendant l’attente de la fin des opérations d’IO.
Note : contrairement au `Client` classique, `AsyncClient` force `autogenerate_session_id` à `False` par défaut.
Voir aussi : [exemple run\_async](https://github.com/ClickHouse/clickhouse-connect/blob/main/examples/run_async.py).
## Gestion des ID de session ClickHouse
Chaque requête ClickHouse s’exécute dans le contexte d’une « session » ClickHouse. Les sessions sont actuellement utilisées à deux fins :
* Associer des paramètres ClickHouse spécifiques à plusieurs requêtes (voir les [paramètres utilisateur](/docs/fr/reference/settings/session-settings)). La commande ClickHouse `SET` permet de modifier les paramètres à l’échelle d’une session utilisateur.
* Assurer le suivi des [tables temporaires.](/docs/fr/reference/statements/create/table#temporary-tables)
Par défaut, chaque requête exécutée avec une instance `Client` de ClickHouse Connect utilise l’ID de session de ce client. Les instructions `SET` et les tables temporaires fonctionnent comme prévu lorsqu’un seul client est utilisé. En revanche, le serveur ClickHouse n’autorise pas les requêtes concurrentes au sein d’une même session (le client générera une `ProgrammingError` si vous essayez de le faire). Pour les applications qui exécutent des requêtes concurrentes, utilisez l’un des modèles suivants :
1. Créez une instance `Client` distincte pour chaque thread/processus/gestionnaire d’événements nécessitant une isolation de session. Cela préserve l’état de session propre à chaque client (tables temporaires et valeurs `SET`).
2. Utilisez un `session_id` unique pour chaque requête via l’argument `settings` lors de l’appel à `query`, `command` ou `insert`, si vous n’avez pas besoin d’un état de session partagé.
3. Désactivez les sessions sur un client partagé en définissant `autogenerate_session_id=False` avant de créer le client (ou en le passant directement à `get_client`).
```python theme={null}
from clickhouse_connect import common
import clickhouse_connect
common.set_setting('autogenerate_session_id', False) # This should always be set before creating a client
client = clickhouse_connect.get_client(host='somehost.com', user='dbuser', password=1234)
```
Vous pouvez également passer `autogenerate_session_id=False` directement à `get_client(...)`.
Dans ce cas, ClickHouse Connect n'envoie pas de `session_id` ; le serveur ne considère pas que des requêtes distinctes appartiennent à la même session. Les tables temporaires et les paramètres au niveau de la session ne persistent pas d'une requête à l'autre.
## Personnalisation du pool de connexions HTTP
ClickHouse Connect utilise les pools de connexions `urllib3` pour gérer la connexion HTTP sous-jacente avec le serveur. Par défaut, toutes les instances client partagent le même pool de connexions, ce qui suffit dans la majorité des cas d’usage. Ce pool par défaut maintient jusqu’à 8 connexions HTTP Keep Alive vers chaque serveur ClickHouse utilisé par l’application.
Pour les applications volumineuses multithreadées, il peut être préférable d’utiliser des pools de connexions distincts. Des pools de connexions personnalisés peuvent être fournis via l’argument nommé `pool_mgr` de la fonction principale `clickhouse_connect.get_client` :
```python theme={null}
import clickhouse_connect
from clickhouse_connect.driver import httputil
big_pool_mgr = httputil.get_pool_manager(maxsize=16, num_pools=12)
client1 = clickhouse_connect.get_client(pool_mgr=big_pool_mgr)
client2 = clickhouse_connect.get_client(pool_mgr=big_pool_mgr)
```
Comme le montre l’exemple ci-dessus, les clients peuvent partager un même PoolManager, ou un PoolManager distinct peut être créé pour chaque client. Pour plus de détails sur les options disponibles lors de la création d’un PoolManager, consultez la [documentation `urllib3`](https://urllib3.readthedocs.io/en/stable/advanced-usage.html#customizing-pool-behavior).