API brute
Méthode raw_query de Client
Client.raw_query permet d’utiliser directement l’interface de requête HTTP de ClickHouse via la connexion du client. La valeur de retour est un objet bytes non traité. Elle fournit un wrapper pratique avec liaison de paramètres, gestion des erreurs, réessais et gestion des paramètres via une interface minimale :
Il incombe à l’appelant de traiter l’objet
bytes renvoyé. Notez que Client.query_arrow n’est qu’un simple wrapper de cette méthode utilisant le format de sortie ClickHouse Arrow.
Méthode raw_stream de Client
Client.raw_stream a la même API que la méthode raw_query, mais renvoie un objet io.IOBase qui peut être utilisé comme générateur ou comme source de flux d’objets bytes. Elle est actuellement utilisée par la méthode query_arrow_stream.
Méthode raw_insert de Client
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 est très performante. La méthode propose des options pour spécifier les settings et le format d’insertion :
Il incombe à l’appelant de s’assurer que
insert_block est dans le format spécifié et utilise la méthode de compression spécifiée. ClickHouse Connect utilise ces insertions brutes pour les téléversements de fichiers et les tables PyArrow, en déléguant le parsing au serveur ClickHouse.
Enregistrer les résultats d’une requête dans des fichiers
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 :
output.csv avec le contenu suivant :
Cas d’utilisation multithread, multiprocessus et asynchrones/pilotés par événements
QueryContext ou InsertContext, respectivement, ces objets utilitaires ne sont pas thread-safe et ne doivent pas être partagés entre plusieurs flux de traitement. Consultez également les explications supplémentaires sur les objets de contexte dans les sections QueryContexts et InsertContexts.
De plus, dans une application où deux requêtes et/ou insertions ou plus sont « en cours » au même moment, il faut garder à l’esprit deux autres points. Le premier concerne la « session » ClickHouse associée à la requête/insertion, et le second le pool de connexions HTTP utilisé par les instances de ClickHouse Connect Client.
Wrapper AsyncClient
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 la fonction standard get_client :
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’E/S sont encapsulées dans un appel à run_in_executor.
Les performances en environnement multithread s’améliorent lors de l’utilisation du wrapper AsyncClient, car les threads d’exécution et le GIL sont libérés pendant l’attente de la fin des opérations d’E/S.
Remarque : contrairement au Client standard, AsyncClient impose autogenerate_session_id à False par défaut.
Voir aussi : exemple run_async.
Gestion des ID de session ClickHouse
- Associer des paramètres ClickHouse spécifiques à plusieurs requêtes (voir les paramètres utilisateur). La commande ClickHouse
SETest utilisée pour modifier les paramètres dans le cadre d’une session utilisateur. - Suivre les tables temporaires.
Client de ClickHouse Connect utilise l’ID de session de ce client. Les instructions SET et les tables temporaires fonctionnent comme prévu lors de l’utilisation d’un seul client. Cependant, le serveur ClickHouse n’autorise pas les requêtes concurrentes au sein d’une même session (le client lèvera une ProgrammingError si vous essayez). Pour les applications qui exécutent des requêtes concurrentes, utilisez l’une des approches suivantes :
- Créez une instance
Clientdistincte pour chaque thread/process/event handler nécessitant une isolation de session. Cela préserve l’état de session propre à chaque client (tables temporaires et valeursSET). - Utilisez un
session_idunique pour chaque requête via l’argumentsettingslors de l’appel àquery,commandouinsert, si vous n’avez pas besoin d’un état de session partagé. - Désactivez les sessions sur un client partagé en définissant
autogenerate_session_id=Falseavant de créer le client (ou transmettez-le directement àget_client).
autogenerate_session_id=False directement à get_client(...).
Dans ce cas, ClickHouse Connect n’envoie pas de session_id ; le serveur ne considère pas les requêtes distinctes comme appartenant à la même session. Les tables temporaires et les paramètres de session ne seront pas conservés d’une requête à l’autre.
Personnalisation du pool de connexions HTTP
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 plupart des cas d’usage. Ce pool par défaut gère jusqu’à 8 connexions HTTP Keep Alive vers chaque serveur ClickHouse utilisé par l’application.
Pour les applications multithreadées de grande taille, 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 :
urllib3.