L’ingestion efficace des données est à la base des déploiements ClickHouse à hautes performances. Choisir la bonne stratégie d’insertion peut avoir un impact considérable sur le débit, le coût et la fiabilité. Cette section présente les bonnes pratiques, les compromis et les options de configuration afin de vous aider à prendre la bonne décision pour votre charge de travail.
Insertions synchrones par défaut
Utilisez les insertions synchrones si vous pouvez regrouper les données côté clientSinon, consultez la section Insertions asynchrones ci-dessous. Insertions par lot en mode synchrone
Quelle que soit la taille de vos insertions, nous vous recommandons de maintenir le nombre de requêtes d’insertion autour d’une par seconde. Cette recommandation s’explique par le fait que les parts créées sont fusionnées en arrière-plan en parts plus volumineuses (afin d’optimiser vos données pour les requêtes de lecture), et qu’un trop grand nombre de requêtes d’insertion par seconde peut conduire à des situations où les fusions en arrière-plan ne parviennent plus à suivre le rythme de création des nouvelles parts. Toutefois, vous pouvez utiliser un taux plus élevé de requêtes d’insertion par seconde avec les insertions asynchrones (voir Insertions asynchrones). Assurer des retries idempotents
- L’insertion a réussi, mais le client n’a jamais reçu d’accusé de réception en raison d’une interruption réseau.
- L’insertion a échoué côté serveur et a expiré.
Dans les deux cas, il est sans risque de réessayer l’insertion — tant que le contenu du lot et son ordre restent identiques. C’est pourquoi il est essentiel que les clients réessaient de manière cohérente, sans modifier ni réordonner les données.
Choisissez la bonne cible d’insertion
- Insérez directement dans une table MergeTree ou ReplicatedMergeTree. C’est l’option la plus efficace lorsque le client peut répartir la charge entre les shards. Avec
internal_replication = true, ClickHouse gère la réplication de manière transparente.
- Insérez dans une table Distributed. Les clients peuvent ainsi envoyer des données à n’importe quel nœud, puis laisser ClickHouse les acheminer vers le shard approprié. C’est plus simple, mais légèrement moins performant en raison de cette étape de transfert supplémentaire.
internal_replication = true reste recommandé.
Dans ClickHouse Cloud, tous les nœuds lisent et écrivent sur un seul et même shard. Les insertions sont automatiquement réparties entre les nœuds. Vous pouvez simplement envoyer vos insertions vers l’endpoint exposé.
Choisir le bon format d’entrée est essentiel pour assurer une ingestion de données efficace dans ClickHouse. Avec plus de 70 formats pris en charge, le choix de l’option la plus performante peut avoir un impact significatif sur la vitesse d’insertion, l’utilisation du CPU et de la mémoire, ainsi que sur l’efficacité globale du système.
Si la flexibilité est utile pour l’ingénierie des données et les imports à partir de fichiers, les applications doivent privilégier les formats optimisés pour les performances :
- Native format (recommandé) : le plus efficace. Format colonnaire, nécessitant un minimum de parsing côté serveur. Utilisé par défaut par les clients Go et Python.
- RowBinary : format en lignes efficace, idéal si la transformation en format colonnaire est difficile côté client. Utilisé par le client Java.
- JSONEachRow : simple à utiliser, mais coûteux à parser. Convient aux cas d’usage à faible volume ou aux intégrations rapides.
La compression joue un rôle essentiel pour réduire la surcharge réseau, accélérer les insertions et diminuer les coûts de stockage dans ClickHouse. Lorsqu’elle est utilisée efficacement, elle améliore les performances d’ingestion sans nécessiter de modifier le format des données ni le schéma.
La compression des données insérées réduit la taille des données envoyées sur le réseau, ce qui limite l’utilisation de la bande passante et accélère la transmission.
Pour les insertions, la compression est particulièrement efficace lorsqu’elle est utilisée avec le format Native, qui correspond déjà au modèle de stockage interne en colonnes de ClickHouse. Dans cette configuration, le serveur peut décompresser efficacement les données et les stocker directement avec un minimum de transformations.
Utilisez LZ4 pour la rapidité, ZSTD pour le taux de compression
- LZ4 : rapide et léger. Il réduit considérablement la taille des données avec une surcharge CPU minimale, ce qui en fait un choix idéal pour les insertions à haut débit, et c’est l’option par défaut dans la plupart des clients ClickHouse.
- ZSTD : taux de compression plus élevé, mais plus gourmand en CPU. Il est utile lorsque les coûts de transfert réseau sont élevés — par exemple dans des scénarios inter-région ou chez certains fournisseurs cloud — même s’il augmente légèrement les ressources de calcul côté client et le temps de décompression côté serveur.
Bonne pratique : utilisez LZ4, sauf si votre bande passante est limitée ou si vous supportez des coûts de sortie des données — dans ce cas, envisagez ZSTD.
Selon des tests du benchmark FastFormats, des insertions Native compressées avec LZ4 ont réduit la taille des données de plus de 50 %, faisant passer le temps d’ingestion de 150 s à 131 s pour un jeu de données de 5,6 GiB. En passant à ZSTD, ce même jeu de données a été compressé à 1,69 GiB, mais le temps de traitement côté serveur a légèrement augmenté. La compression réduit l’utilisation des ressources
Pré-trier si le coût est faible
Il n’est pas recommandé d’envoyer de nombreux petits batches en mode synchrone, car cela entraîne la création d’un grand nombre de parts. Cela dégrade les performances des queries et peut provoquer des erreurs “too many part”. async_insert.
Les insertions asynchrones sont prises en charge à la fois par les interfaces HTTP et native TCP.
Lorsqu’elles sont activées (async_insert = 1), les insertions sont mises en tampon et écrites sur disk uniquement lorsqu’une des conditions de flush suivantes est remplie :
Le premier seuil atteint déclenche le flush.
Ce processus de batching est invisible pour les clients et aide ClickHouse à fusionner efficacement le trafic d’insertions provenant de plusieurs sources. Cependant, tant qu’un flush n’a pas eu lieu, les données ne peuvent pas être interrogées. Il est important de noter qu’il existe plusieurs tampons par combinaison de forme d’insertion et de paramètres et que, dans les clusters, les tampons sont maintenus par nœud, ce qui permet un contrôle granulaire dans les environnements multi-tenant. Les mécanismes d’insertion sont par ailleurs identiques à ceux décrits pour les insertions synchrones.
Choisir un mode de retour
wait_for_async_insert.
Lorsqu’il est défini sur 1 (valeur par défaut), ClickHouse n’accuse réception de l’insert qu’une fois les données correctement écrites sur le disque. Cela garantit une forte durabilité et simplifie le traitement des erreurs : si un problème survient pendant le flush, l’erreur est renvoyée au client. Ce mode est recommandé dans la plupart des scénarios de production, en particulier lorsque les échecs d’insert doivent être suivis de manière fiable.
Les benchmarks montrent qu’il passe bien à l’échelle avec une forte concurrency — que vous exécutiez 200 ou 500 clients — grâce aux inserts adaptatifs et à un comportement stable lors de la création des parts.
Définir wait_for_async_insert = 0 active le mode « fire-and-forget ». Dans ce cas, le serveur accuse réception de l’insert dès que les données sont placées dans le tampon, sans attendre qu’elles soient écrites dans le stockage.
Cela permet des inserts à très faible latence et un throughput maximal, idéal pour des données à haut débit et à faible criticité. Cependant, cela implique des compromis : rien ne garantit que les données seront persistées, les erreurs n’apparaissent qu’au moment du flush, et il n’existe pas de dead-letter queue pour les inserts en échec — pour analyser les échecs, il faut inspecter les server logs et les system tables a posteriori. Utilisez ce mode uniquement si votre workload peut tolérer une perte de données.
Les benchmarks montrent également une réduction substantielle du nombre de parts et une baisse de l’utilisation CPU lorsque les flushes du tampon sont peu fréquents (par exemple, toutes les 30 secondes), mais le risque d’échec silencieux demeure.
Nous recommandons vivement d’utiliser async_insert=1,wait_for_async_insert=1 si vous utilisez des insertions asynchrones. Utiliser wait_for_async_insert=0 est très risqué, car votre client INSERT peut ne pas être informé en cas d’erreur. Cela peut également entraîner une surcharge si votre client continue à écrire rapidement alors que le ClickHouse server doit ralentir les écritures et appliquer une certaine contre-pression afin de garantir la fiabilité du service.
Insertions asynchrones adaptatives
async_insert_use_adaptive_busy_timeout). Au lieu d’un intervalle de flush fixe, le timeout s’ajuste dynamiquement entre un minimum (async_insert_busy_timeout_min_ms, 50 ms par défaut) et un maximum (async_insert_busy_timeout_max_ms, 200 ms par défaut ou 1000 ms sur Cloud) en fonction du débit des données entrantes.
Lorsque les données arrivent fréquemment, le timeout reste proche du minimum afin de déclencher le flush plus rapidement et de réduire la latence de bout en bout. Lorsque les données sont clairsemées, il se rapproche du maximum pour accumuler des lots plus volumineux. Cela est particulièrement utile dans le mode par défaut (wait_for_async_insert=1), où un timeout fixe élevé obligerait les clients à attendre pendant tout l’intervalle, même lorsque les données sont déjà prêtes à être écrites.
La validation du schéma et l’analyse des données ont lieu lors du flush du tampon, et non à la réception de l’insert. Si une ligne d’une requête d’insertion contient une erreur d’analyse ou de type, aucune des données de cette requête n’est écrite — l’intégralité de la charge utile de la requête est rejetée. En mode par défaut (wait_for_async_insert=1), l’erreur est renvoyée au client. En mode fire-and-forget, les erreurs sont consignées dans les journaux du serveur et dans la table system.asynchronous_inserts.
Chaque flush crée au moins une part par valeur distincte de clé de partitionnement dans le tampon. Même pour les tables sans clé de partitionnement, un seul flush peut produire plusieurs parts si les données mises en tampon dépassent max_insert_block_size (environ 1 million de lignes par défaut).
Même avec les insertions asynchrones, vous pouvez toujours rencontrer des erreurs “too many parts” si la clé de partitionnement présente une cardinalité élevée. Déduplication et fiabilité
Activation des insertions asynchrones
-
Activation des insertions asynchrones au niveau de l’utilisateur. Cet exemple utilise l’utilisateur
default ; si vous créez un autre utilisateur, remplacez-le par ce nom d’utilisateur :
-
Vous pouvez spécifier les paramètres d’insertion asynchrone à l’aide de la clause SETTINGS dans les requêtes d’insertion :
-
Vous pouvez également définir les paramètres d’insertion asynchrone comme paramètres de connexion lorsque vous utilisez un client ClickHouse pour un langage de programmation.
Par exemple, voici comment procéder dans une chaîne de connexion JDBC lorsque vous utilisez le pilote JDBC Java de ClickHouse pour vous connecter à ClickHouse Cloud :
Les insertions asynchrones ne s’appliquent pas aux requêtes INSERT INTO ... SELECT. Lorsqu’une insertion contient une clause SELECT, la requête est toujours exécutée de manière synchrone, quel que soit le paramètre async_insert.
Flush des tampons à l’arrêt
async insert en attente — par exemple, lors d’un arrêt propre ou avant une opération de maintenance — exécutez :
Cela garantit que toutes les données en mémoire tampon sont écrites dans le stockage avant que le serveur ne s’arrête.
Comparaison avec les tables Buffer
- Aucune modification DDL n’est requise. Les insertions asynchrones sont transparentes : vous activez un paramètre, sans créer de tables supplémentaires.
- Mise en tampon par forme de requête. Les insertions asynchrones conservent des tampons distincts pour chaque combinaison unique de forme de requête et de paramètres, ce qui permet des politiques de flush granulaires. Les tables Buffer utilisent un seul tampon par table cible.
- Durabilité. Dans le mode par défaut (
wait_for_async_insert=1), les données sont confirmées sur disque avant que le client ne reçoive la confirmation. Les tables Buffer fonctionnent en mode fire-and-forget : les données mises en tampon sont perdues en cas de crash.
- Comportement du cluster. Dans les clusters, les tampons d’insertion asynchrone sont maintenus par nœud. Les tables Buffer nécessitent une création explicite sur chaque nœud.
Choisissez une interface — HTTP ou native
Content-Encoding: lz4), la compression s’applique à l’ensemble de la charge utile plutôt qu’à des blocs de données individuels. Cette interface est souvent privilégiée dans les environnements où la simplicité du protocole, la répartition de charge ou la large compatibilité des formats importent davantage que les performances brutes.
Pour une description plus détaillée de ces interfaces, voir ici. 
