Guide

ClickHouse, une base de données en colonnes pour l'analytique

ClickHouse est une base en colonnes qui agrège des milliards de lignes en quelques centaines de millisecondes : MergeTree, mises à jour, tarifs et pièges.

L'équipe CodeWorlds20 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

ClickHouse est une base de données en colonnes construite autour d'une seule mission : calculer des agrégats sur des milliards de lignes en quelques centaines de millisecondes. Le prix de cette vitesse est un modèle de données dans lequel modifier ou supprimer une seule ligne est une opération coûteuse plutôt que courante. Ce texte explique quand ce compromis vaut la peine.

Pour quoi ClickHouse est conçu, et pour quoi il ne l'est pas

La différence entre un stockage en lignes et un stockage en colonnes ressemble à un détail d'implémentation, pourtant elle décide de tout ce qui se construit au-dessus. Dans PostgreSQL, une ligne est écrite dans un fichier comme une suite contiguë d'octets, donc récupérer un enregistrement complet par clé primaire se fait en une seule lecture. Dans ClickHouse, chaque colonne est un fichier distinct, compressé indépendamment des autres. Une requête qui additionne une colonne sur dix milliards de lignes ne touche que cette colonne et ne lit pas un octet du reste. Une requête qui récupère une ligne entière doit en revanche visiter autant de fichiers que la table compte de colonnes.

C'est de là que vient toute la répartition des cas d'usage. ClickHouse convient aux événements analytiques, aux logs, aux métriques, à la télémétrie et à tout ce qui arrive en masse et se consulte sous forme agrégée. Il ne convient pas pour stocker l'état d'une application, un panier d'achat, une session utilisateur ou tout ce qui demande de lire et d'écrire des enregistrements individuels par identifiant. Pour ce second ensemble, tu as Postgres, Supabase ou Redis, et aucun d'eux n'est remplacé par ClickHouse.

Une architecture de production typique place les deux bases côte à côte. La base transactionnelle conserve l'état, ClickHouse reçoit le flux d'événements et répond aux questions analytiques. C'est ainsi que fonctionne PostHog, qui garde les métadonnées dans Postgres et les événements produit dans ClickHouse, et c'est un bon exemple de ce à quoi ressemble cette séparation dans un vrai produit.

Certaines choses dont la présence dans une base SQL va de soi manquent aussi ici. Il n'y a pas de transactions couvrant plusieurs instructions. La clé primaire n'est pas unique et n'impose aucune unicité, car elle joue un rôle entièrement différent de celui d'un stockage en lignes. Les clés étrangères n'existent pas. Les jointures fonctionnent, mais elles sont un point bien plus faible du système que les agrégations et peuvent décevoir quand les deux côtés sont de grosses tables.

Versions, licence et distribution

La numérotation des versions suit un schéma année point mois. La dernière version stable au moment où ces lignes sont écrites est la 26.6.3.62, publiée dans le registre d'images le 19 août 2026 sous le tag latest. Des lignes à support long sont maintenues en parallèle : les images 26.3.20.7 et 25.8.31.9 sont arrivées dans le registre le 20 août 2026, un jour après la version courante. Si tu exploites ton propre déploiement, cette seconde voie est la plus raisonnable, car le rythme des versions majeures est très rapide.

La licence est ce cas rare où trois sources vérifiées disent la même chose. Le fichier LICENSE de la branche principale du dépôt contient le texte complet de l'Apache License 2.0 avec une mention de copyright de ClickHouse, Inc. couvrant 2016 à 2026. Le champ license du registre npm pour le paquet @clickhouse/client indique Apache-2.0. Le paquet décompressé publié dans le registre contient un fichier LICENSE avec le même texte Apache 2.0, sauf que sa mention de copyright couvre 2016 à 2024. C'est un écart de date plutôt que de conditions, donc il ne change rien pour un audit de dépendances, mais il montre que le fichier de licence à l'intérieur du paquet n'est pas actualisé à chaque version. L'écosystème Python donne le même résultat : le paquet clickhouse-connect en version 1.7.2 déclare Apache-2.0 à la fois dans son champ license et dans ses classifiers.

Le driver Node déclare la version 1.23.1. Garde ces numéros séparés du numéro du serveur, car les bibliothèques clientes ont leur propre cycle de publication et 1.23.1 ne dit rien du serveur avec lequel elle communique.

La conclusion pratique sur la licence est courte. Tout le cœur, y compris la réplication, le stockage sur des object stores et tous les moteurs de tables de la famille MergeTree, est sous une licence permissive et libre d'usage commercial. La frontière entre payant et gratuit passe ailleurs : non pas par la licence du code, mais par ce qui est disponible exclusivement dans le service managé.

Le modèle de données : MergeTree et la clé de tri

Le moteur MergeTree et ses dérivés sont la fondation sur laquelle tout le reste repose. Les données insérées dans une table atterrissent dans des fragments immuables appelés parts, et un processus en arrière-plan fusionne les petites parts en plus grandes. Chaque part est triée selon la clé de tri donnée dans la clause ORDER BY.

SQL
CREATE TABLE analytics.events
(
    project_id   UInt32,
    event_type   LowCardinality(String),
    event_time   DateTime,
    user_id      UInt64,
    session_id   UUID,
    country      LowCardinality(String),
    duration_ms  UInt32,
    properties   Map(String, String)
)
ENGINE = MergeTree
PARTITION BY toYYYYMM(event_time)
ORDER BY (project_id, event_type, event_time)
TTL event_time + INTERVAL 90 DAY DELETE
SETTINGS index_granularity = 8192;

La clause ORDER BY est la décision de conception la plus importante ici et en même temps la plus difficile à changer plus tard. Elle définit l'ordre physique des lignes sur le disque ainsi que l'index primaire clairsemé, qui, au lieu d'un pointeur par ligne, conserve une entrée par index_granularity lignes, soit 8192 par défaut. Une requête qui filtre sur un préfixe de cette clé ne lit que les granules susceptibles de contenir des données correspondantes. Une requête qui filtre sur une colonne hors de la clé lit tout.

De là découle la règle pour l'ordre des colonnes dans ORDER BY : les colonnes à faible cardinalité et celles sur lesquelles tu filtres toujours viennent en premier, les colonnes à forte cardinalité, généralement le temps, viennent en dernier. L'ordre inverse, avec un identifiant utilisateur en tête, annule en pratique l'index pour la plupart des requêtes et ruine en même temps la compression, car les valeurs voisines cessent de se ressembler.

Le type LowCardinality(String) dans la définition ci-dessus n'est pas décoratif. Il remplace les chaînes répétitives par un dictionnaire avec des index entiers, ce qui, pour une colonne comme un nom d'événement ou un code pays, réduit le stockage et accélère le regroupement. Sur une colonne avec beaucoup de valeurs uniques, le même type aggrave les choses, donc on ne l'applique pas aux identifiants ni aux URL.

Le partitionnement se comporte différemment de ce que suggère l'intuition Postgres. La clause PARTITION BY existe surtout pour la gestion des données, c'est-à-dire la suppression rapide de périodes entières via DROP PARTITION et pour les règles TTL. Accélérer les requêtes est le rôle de ORDER BY. Un excès de partitions, par exemple un découpage quotidien avec une rétention de trois ans, crée des milliers de répertoires et ralentit réellement le système.

Mises à jour et suppressions, la partie la plus coûteuse

C'est ici que les habitudes d'une base transactionnelle finissent le plus douloureusement. Les parts de données sont immuables, donc écraser une ligne sur place n'existe pas. Chaque modification signifie écrire de nouvelles données et les réconcilier avec les anciennes lors d'une fusion ou d'une lecture.

Historiquement, la seule voie était les mutations, c'est-à-dire ALTER TABLE ... UPDATE et ALTER TABLE ... DELETE. Une mutation réécrit des colonnes entières dans chaque part touchée par la condition. Sur une table de quelques centaines de gigaoctets, modifier un champ dans une ligne peut signifier réécrire une part substantielle de la table. Une mutation s'exécute de manière asynchrone, et sa progression se suit dans une table système.

SQL
-- mutation: rewrites entire columns in affected parts
ALTER TABLE analytics.events
    UPDATE duration_ms = 0
    WHERE event_type = 'heartbeat';

-- progress and any failure
SELECT mutation_id, command, parts_to_do, is_done, latest_fail_reason
FROM system.mutations
WHERE database = 'analytics' AND table = 'events' AND is_done = 0;

Une voie plus légère est arrivée plus tard et reste marquée comme fonctionnalité bêta. L'instruction DELETE FROM ... WHERE marque les lignes comme supprimées sans réécrire immédiatement les colonnes, et la suppression physique a lieu à la fusion suivante. Cela signifie que les données restent sur le disque pendant une durée indéterminée et cessent simplement d'apparaître dans les résultats. Pour une suppression à la demande d'un utilisateur, par exemple au titre d'un droit à l'effacement, ce détail a un poids juridique, et il existe un paramètre de table min_age_to_force_merge_seconds qui force une fusion dans un délai prévisible.

L'instruction UPDATE ... SET ... WHERE fonctionne sur un principe similaire, en écrivant des patch parts au lieu de réécrire les colonnes. Elle comporte des préconditions strictes sur lesquelles il est facile de trébucher.

SQL
-- required precondition for lightweight updates
ALTER TABLE analytics.events
    MODIFY SETTING enable_block_number_column = 1,
                   enable_block_offset_column = 1;

-- lightweight update, MergeTree family only
UPDATE analytics.events
    SET duration_ms = 0
    WHERE event_type = 'heartbeat' AND event_time >= '2026-08-01';

-- delete marks rows, they vanish physically at merge time
DELETE FROM analytics.events
    WHERE user_id = 918273;

Les limites sont concrètes. Une mise à jour légère ne prend en charge que la famille de moteurs MergeTree. Elle exige la matérialisation des colonnes _block_number et _block_offset, activée via les paramètres de table enable_block_number_column et enable_block_offset_column. Les colonnes appartenant à la clé primaire ou à la clé de partition ne peuvent pas être modifiées. Le comportement en cas de concurrence est régi par les paramètres update_sequential_consistency et update_parallel_mode, et le format des patch parts écrites par patch_parts_version, qui doit être figé sur v1 pendant une mise à niveau progressive d'un cluster.

Si les mises à jour font partie du flux normal des données plutôt que d'être une exception, la bonne réponse n'est aucune des instructions ci-dessus mais un autre moteur de table. ReplacingMergeTree accepte des versions successives de la même clé et en conserve une seule lors de la fusion.

SQL
CREATE TABLE analytics.subscriptions
(
    subscription_id UInt64,
    plan            LowCardinality(String),
    status          LowCardinality(String),
    updated_at      DateTime,
    is_deleted      UInt8
)
ENGINE = ReplacingMergeTree(updated_at, is_deleted)
ORDER BY subscription_id;

-- FINAL merges versions on the fly, at query time cost
SELECT subscription_id, plan, status
FROM analytics.subscriptions FINAL
WHERE status = 'active';

Le premier argument du moteur est la colonne de version, le second un marqueur de suppression, et le second ne peut pas être utilisé sans le premier. Le piège principal est que la fusion se produit à terme plutôt qu'immédiatement, donc sans le modificateur FINAL, une requête peut voir plusieurs versions du même enregistrement. Le modificateur FINAL donne un résultat correct mais déplace le coût de la fusion au moment de la requête, et sur de grosses tables cela se remarque.

Insertion de données et vues matérialisées

L'insertion obéit à une règle dont la violation finit par une panne dans chaque déploiement. Chaque instruction INSERT crée une nouvelle part sur le disque, et le processus de fusion ne suit que jusqu'à un certain point. Insérer une ligne à la fois inonde le système de milliers de minuscules parts et se termine par une erreur sur un trop grand nombre de parts dans une partition. Les données s'insèrent par lots, en pratique de quelques milliers à quelques centaines de milliers de lignes à la fois.

TypeScript
import { createClient } from '@clickhouse/client'

const client = createClient({
  url: process.env.CLICKHOUSE_URL,
  username: process.env.CLICKHOUSE_USER,
  password: process.env.CLICKHOUSE_PASSWORD,
  database: 'analytics',
  max_open_connections: 10,
  request_timeout: 30_000,
  clickhouse_settings: {
    async_insert: 1,
    wait_for_async_insert: 1
  }
})

await client.insert({
  table: 'events',
  values: batch,
  format: 'JSONEachRow',
  columns: ['project_id', 'event_type', 'event_time', 'user_id', 'duration_ms']
})

Le paramètre async_insert déplace la mise en tampon côté serveur, ce qui sauve la situation quand l'application n'a pas d'endroit naturel pour une file d'attente. Activer wait_for_async_insert fait que l'appel ne retourne qu'une fois le tampon écrit, ce qui préserve l'accusé de réception d'écriture au prix de la latence. Le désactiver donne une réponse plus rapide et un risque de perte de données en cas de panne d'un nœud, c'est donc un choix délibéré plutôt qu'un réglage à copier sans réfléchir.

Les vues matérialisées de ClickHouse sont différentes de leurs homonymes Postgres, et c'est l'un des malentendus les plus courants. Ce ne sont pas un instantané d'une requête rafraîchi périodiquement. Ce sont un trigger qui se déclenche à l'insertion : chaque nouvelle part de la table source passe par la requête de la vue, et le résultat va dans une table cible. Les données insérées avant l'existence de la vue ne seront pas traitées.

SQL
CREATE TABLE analytics.events_hourly
(
    project_id   UInt32,
    event_type   LowCardinality(String),
    hour         DateTime,
    events_count UInt64,
    unique_users AggregateFunction(uniq, UInt64)
)
ENGINE = AggregatingMergeTree
ORDER BY (project_id, event_type, hour);

CREATE MATERIALIZED VIEW analytics.events_hourly_mv
TO analytics.events_hourly
AS SELECT
    project_id,
    event_type,
    toStartOfHour(event_time) AS hour,
    count() AS events_count,
    uniqState(user_id) AS unique_users
FROM analytics.events
GROUP BY project_id, event_type, hour;

SELECT project_id, sum(events_count), uniqMerge(unique_users)
FROM analytics.events_hourly
WHERE hour >= now() - INTERVAL 7 DAY
GROUP BY project_id;

Le motif avec les suffixes State et Merge est obligatoire ici. La fonction uniqState écrit un état d'agrégat intermédiaire dans une colonne de type AggregateFunction, et uniqMerge combine ces états à la lecture. Sauter cette étape et stocker un simple nombre donne un résultat qui ne s'additionne pas correctement d'une période à l'autre, car les comptes d'utilisateurs uniques de deux heures ne peuvent pas être simplement sommés. Le remplissage de tables par lots à un rythme quotidien est plus souvent confié à un ordonnanceur externe comme Apache Airflow, en réservant les vues matérialisées aux agrégats calculés à la volée.

ClickHouse Cloud, tarifs et fonctionnalités réservées au cloud

Le service managé facture l'usage réel sur quatre postes : calcul, stockage, transfert de données et le mécanisme d'ingestion ClickPipes. Il n'y a pas d'abonnement pour la disponibilité du plan lui-même, il y a un prix par unité. Les chiffres ci-dessous viennent de la documentation de facturation pour la région AWS de Virginie du Nord et sont des exemples plutôt que des tarifs publics.

Le plan Basic démarre à 66,52 USD par mois pour un service avec un réplica de 8 GiB de mémoire et 2 cœurs virtuels, 500 Go de données compressées et une sauvegarde de même taille, fonctionnant six heures par jour. Ce montant se décompose en 39,91 USD pour le calcul, 25,30 USD pour le stockage, 1,15 USD pour la sortie vers l'internet public et 0,16 USD pour le trafic inter-régions. À douze heures par jour, le même service coûte 106,44 USD, et en fonctionnement continu 186,27 USD, car seul le poste de calcul augmente.

Le plan Scale démarre à 499,38 USD par mois avec deux réplicas de 8 GiB fonctionnant en continu. Passer les réplicas à 16 GiB fait monter à lui seul le poste de calcul à 873,89 USD. Pour le plan Enterprise, l'éditeur ne publie aucun prix d'entrée, seulement des exemples : deux réplicas de 32 GiB avec 5 To de données et une sauvegarde reviennent à 2 669,40 USD par mois.

Les tarifs de transfert sont donnés par région et peuvent être vérifiés. Pour la région de Virginie du Nord, la page des tarifs indique 0,1152 USD par gigaoctet de sortie vers l'internet public et 0,0312 USD par gigaoctet de trafic inter-régions, ce qui, multiplié par les volumes de l'exemple Basic, produit exactement les chiffres de 1,15 et 0,16 USD du tableau. Cette ligne de la facture est facile à négliger lors de la planification, et avec des dashboards qui interrogent la base directement depuis le navigateur, elle peut grossir.

La facturation se fait en unités appelées ClickHouse Credits, où un crédit équivaut à un dollar. Avec un paiement via Stripe, la facture affiche un crédit à 0,01 USD, car ce processeur ne gère pas les quantités fractionnaires. C'est un écart purement de présentation, mais quiconque analyse les factures automatiquement doit le connaître. Un nouveau compte bénéficie d'une période d'essai de trente jours.

La répartition des fonctionnalités entre les plans compte autant que les prix. Le plan Basic plafonne le stockage à 1 To et la mémoire à une plage de 8 à 12 GiB, fonctionne dans une seule zone de disponibilité et réalise des sauvegardes toutes les 24 heures avec une rétention d'un jour, sans option de configuration. Le plan Scale supprime le plafond de stockage et ajoute une mémoire configurable, deux zones de disponibilité ou plus, un réseau privé, une mise à l'échelle verticale automatique et la séparation compute-compute. Le plan Enterprise ajoute l'authentification unique SAML, des régions privées, des clés de chiffrement gérées par le client, la conformité HIPAA et PCI, des mises à niveau planifiées et un temps de réponse de trente minutes pour les incidents de plus haute gravité.

Des fonctionnalités réservées au cloud existent et il faut les connaître avant de choisir une voie de déploiement. La famille de moteurs SharedMergeTree, conçue pour remplacer ReplicatedMergeTree sur du stockage objet, alimente le service managé et ne fait pas partie de la version ouverte. ClickPipes, l'ingestion managée depuis Kafka, Kinesis, S3 et d'autres sources, ne fonctionne que dans le cloud. La séparation compute-compute n'est disponible qu'à partir des plans Scale et Enterprise, elle exige donc non seulement le cloud mais un niveau précis. Développé séparément, un Postgres managé intégré à ClickHouse, en bêta, est facturé à partir de 0,125 USD par unité et par heure.

ClickHouse face aux alternatives

CaractéristiqueClickHousePostgreSQLElasticsearchDuckDBSnowflake
Modèle de stockageen colonnesen lignesindex inverséen colonnesen colonnes
Usage typiqueagrégats sur des événementsétat de l'applicationrecherche de texteanalyse localeentrepôt managé
Modification d'une lignecoûteuse, asynchronepeu coûteuse et immédiateréécriture du documentexige une réécriturecoûteuse
Transactions multi-instructionsaucuneACID completaucuneprocessus uniquecomplètes
Mode d'exécutionserveur ou cloudserveur ou cloudserveur ou cloudbibliothèque in-processcloud uniquement
Licence du cœurApache 2.0PostgreSQLAGPLv3, ELv2, SSPLMITpropriétaire

Le choix se résume à quelques questions. Si les données tiennent sur une seule machine et que l'analyse est ponctuelle, DuckDB s'en charge sans serveur ni maintenance. Si les questions portent sur le contenu de textes plutôt que sur des nombres, le bon outil est Elasticsearch. Si le volume tient en quelques centaines de gigaoctets et que les requêtes ne sont pas particulièrement lourdes, les extensions en colonnes pour Postgres suffisent et évitent d'entretenir une base séparée. ClickHouse commence à être rentable là où le nombre de lignes se compte en milliards, où les requêtes agrègent quelques colonnes parmi beaucoup, et où le temps de réponse doit se mesurer en centaines de millisecondes face à un flux d'écriture en croissance constante.

Erreurs fréquentes

La première est de traiter la clé primaire comme dans une base transactionnelle. Dans ClickHouse, ORDER BY n'impose aucune unicité et n'empêche aucun doublon. Réinsérer les mêmes données donne deux jeux de lignes plutôt qu'une erreur de violation de contrainte, donc l'idempotence doit venir de la couche d'ingestion ou du moteur ReplacingMergeTree.

La deuxième est d'insérer une ligne à la fois, généralement dans le code qui traite une requête HTTP. Chaque écriture de ce type crée sa propre part, le processus de fusion prend du retard, et la base commence à rejeter les écritures avec un message sur un trop grand nombre de parts. Mets en tampon dans l'application ou active async_insert côté serveur.

La troisième est d'utiliser les mutations comme un outil du quotidien. Les instructions ALTER TABLE ... UPDATE et ALTER TABLE ... DELETE réécrivent des colonnes entières dans les parts touchées, s'exécutent de manière asynchrone et peuvent charger le cluster pendant des heures. Si tu les écris dans une boucle, le modèle de données est mal conçu.

La quatrième est d'ajouter le modificateur FINAL à chaque requête pour éviter les doublons de ReplacingMergeTree. Cela fonctionne, mais déplace la fusion au moment de la lecture et, sur une grande table, annule l'avantage de performance qui a motivé le choix de ClickHouse. Une approche plus saine utilise une agrégation avec la dernière version choisie via argMax, ou accepte une courte fenêtre d'incohérence.

La cinquième est un mauvais partitionnement. Un découpage quotidien avec une rétention de plusieurs années crée des milliers de partitions, chacune étant un ensemble distinct de fichiers. Un découpage mensuel est un point de départ raisonnable, et la vitesse des requêtes est le rôle de la clé de tri plutôt que de la partition.

La sixième est les requêtes SELECT * héritées de Postgres. Dans un stockage en colonnes, l'astérisque signifie lire chaque fichier de colonne et c'est la forme de requête la plus coûteuse possible. Liste les colonnes explicitement, même quand tu en as besoin de la plupart.

La septième est de sous-estimer le coût des transferts dans le cloud. Un dashboard qui interroge la base directement depuis le navigateur, à un tarif d'environ onze centimes par gigaoctet de sortie, peut produire une ligne de facture comparable au poste de calcul.

FAQ

ClickHouse peut-il remplacer PostgreSQL ?

Pas dans le rôle de base transactionnelle. Il lui manque les transactions couvrant plusieurs instructions, les clés primaires uniques, les clés étrangères et les mises à jour peu coûteuses d'une seule ligne. L'architecture standard place les deux bases côte à côte : Postgres pour l'état de l'application, ClickHouse pour les événements et l'analytique.

Comment supprimer les données d'un utilisateur sur sa demande ?

Avec l'instruction DELETE FROM ... WHERE, en gardant à l'esprit qu'elle marque les lignes comme supprimées et qu'elles ne disparaissent physiquement qu'à la fusion suivante. Pour répondre à des exigences légales, règle min_age_to_force_merge_seconds sur la table afin que la fusion ait lieu dans un délai prévisible, et vérifie si les données sont dupliquées dans des vues matérialisées.

La version ouverte a-t-elle toutes les fonctionnalités du cloud ?

Non. La famille de moteurs SharedMergeTree, le mécanisme d'ingestion ClickPipes et la séparation compute-compute ne sont disponibles que dans le service managé, et cette dernière uniquement à partir des plans Scale et Enterprise. Le cœur, la réplication et tous les moteurs de la famille MergeTree sont ouverts sous Apache 2.0.

Combien coûte réellement ClickHouse Cloud ?

Cela dépend de la durée d'activité du service et du volume de données qu'il contient. La documentation donne un exemple Basic à partir de 66,52 USD par mois pour six heures d'activité par jour et 186,27 USD en fonctionnement continu, ainsi qu'un plan Scale à partir de 499,38 USD par mois. Le transfert s'ajoute, facturé séparément pour chaque région.

Peut-on changer la clé de tri après la création d'une table ?

Pratiquement non. On peut ajouter des colonnes à la fin de la clé, mais l'ordre des colonnes existantes ne peut pas être modifié et une colonne ne peut pas être retirée de la clé. La changer signifie créer une nouvelle table avec le bon ORDER BY et réécrire les données, c'est pourquoi c'est une décision à arrêter avant la première insertion.

Quand utiliser une vue matérialisée plutôt qu'une requête simple ?

Une vue matérialisée est rentable quand le même agrégat est interrogé à répétition et que le flux d'écriture est régulier. Elle ne traitera pas les données insérées avant son existence et ajoute un coût à chaque insertion, donc pour des requêtes lancées de temps en temps, une requête simple sur la table source coûte moins cher.

La documentation se trouve sur le site de ClickHouse, les détails de facturation sur la page des tarifs, et le code source dans le dépôt GitHub.

À lire aussi