Meilleures pratiques ClickHouse

Guide complet pour ClickHouse couvrant la conception de schémas, l'optimisation des requêtes, l'ingestion de données et la connectivité des agents IA. Contient 31 règles réparties dans 4 catégories principales (schéma, requête, insertion, agent), classées par impact.

Documentation officielle : ClickHouse Best Practices

IMPORTANT : Comment appliquer cette compétence

Avant de répondre aux questions ClickHouse, suivez cet ordre de priorité :

1. Vérifiez les règles applicables dans le répertoire rules/
2. Si des règles existent : Appliquez-les et citez-les dans votre réponse en utilisant « Selon nom-règle... »
3. Si aucune règle n'existe : Utilisez les connaissances ClickHouse du LLM ou consultez la documentation
4. En cas d'incertitude : Effectuez une recherche web pour les meilleures pratiques actuelles
5. Citez toujours votre source : nom de la règle, « conseils généraux ClickHouse », ou URL

Pourquoi les règles ont la priorité : ClickHouse a des comportements spécifiques (stockage en colonnes, index peu denses, mécanique de merge tree) où l'intuition générale des bases de données peut être trompeuse. Les règles encodent des conseils validés et spécifiques à ClickHouse.

Connectivité des agents et workflow de requête

Avant d'interroger ClickHouse, les agents doivent établir une connexion et suivre le workflow de découverte :

1. rules/agent-connect-mcp.md - Configuration de la connexion (MCP + CLI), découverte des identifiants, sélection du format de sortie
2. rules/agent-discovery-schema.md - CRITIQUE : workflow de découverte de schéma en 7 étapes
3. rules/agent-query-safety.md - CRITIQUE : LIMIT, timeouts, exploration progressive

Chaque session d'agent doit suivre cette séquence :

1. Connexion — établir la connexion via MCP ou CLI (voir agent-connect-mcp)
2. Découverte — bases de données → tables → colonnes + commentaires → sort keys → skip indexes → échantillon → EXPLAIN
3. Planification — utiliser les connaissances de sort key et skip index pour écrire des clauses WHERE efficaces
4. Exécution — exécuter les requêtes avec LIMIT et timeouts
5. Récupération — en cas de timeout/erreurs mémoire, affinez les filtres et réessayez (voir agent-query-safety)

Notes sur l'architecture des sous-agents

Si votre système distribue les tâches ClickHouse à des sous-agents spécialisés :

• Découverte de schéma + exécution de requête : n'importe quel modèle — les étapes sont procédurales
• Analyse EXPLAIN + optimisation de requête : bénéficie du raisonnement de niveau intermédiaire
• Examen de conception de schéma par rapport aux 28 règles : bénéficie du raisonnement de niveau intermédiaire

Procédures d'examen

Pour les examens de schéma (CREATE TABLE, ALTER TABLE)

Lisez ces fichiers de règles dans l'ordre :

1. rules/schema-pk-plan-before-creation.md - ORDER BY est immuable
2. rules/schema-pk-cardinality-order.md - Ordre des colonnes dans les clés
3. rules/schema-pk-prioritize-filters.md - Inclusion de colonne filtrée
4. rules/schema-types-native-types.md - Sélection de type appropriée
5. rules/schema-types-minimize-bitwidth.md - Dimensionnement du type numérique
6. rules/schema-types-lowcardinality.md - Utilisation de LowCardinality
7. rules/schema-types-avoid-nullable.md - Nullable vs DEFAULT
8. rules/schema-partition-low-cardinality.md - Limites de décompte de partition
9. rules/schema-partition-lifecycle.md - Objectif du partitionnement

Vérifiez :

• [ ] Ordre des colonnes PRIMARY KEY / ORDER BY (cardinalité basse vers haute)
• [ ] Les types de données correspondent aux plages de données réelles
• [ ] LowCardinality appliqué aux colonnes de chaîne appropriées
• [ ] La cardinalité de clé de partition est bornée (100-1 000 valeurs)
• [ ] ReplacingMergeTree a une colonne de version si utilisée

Pour les examens de requête (SELECT, JOIN, agrégations)

Lisez ces fichiers de règles :

1. rules/query-join-choose-algorithm.md - Sélection d'algorithme
2. rules/query-join-filter-before.md - Filtrage avant join
3. rules/query-join-use-any.md - ANY vs JOIN normal
4. rules/query-index-skipping-indices.md - Utilisation d'index secondaire
5. rules/schema-pk-filter-on-orderby.md - Alignement des filtres avec ORDER BY

Vérifiez :

• [ ] Les filtres utilisent les colonnes de préfixe ORDER BY
• [ ] Les JOINs filtrent les tables avant de joindre (pas après)
• [ ] Algorithme de JOIN correct pour les tailles de table
• [ ] Indices de saut pour les colonnes de filtre non-ORDER BY

Pour les examens de stratégie d'insertion (ingestion de données, mises à jour, suppressions)

Lisez ces fichiers de règles :

1. rules/insert-batch-size.md - Exigences de dimensionnement de lot
2. rules/insert-mutation-avoid-update.md - Alternatives UPDATE
3. rules/insert-mutation-avoid-delete.md - Alternatives DELETE
4. rules/insert-async-small-batches.md - Utilisation d'insertion asynchrone
5. rules/insert-optimize-avoid-final.md - Risques OPTIMIZE TABLE

Vérifiez :

• [ ] Taille de lot 10 000-100 000 lignes par INSERT
• [ ] Pas d'ALTER TABLE UPDATE pour les changements fréquents
• [ ] ReplacingMergeTree ou CollapsingMergeTree pour les motifs de mise à jour
• [ ] Les insertions asynchrones activées pour les lots petits et haute fréquence

Format de sortie

Structurez votre réponse comme suit :

## Règles vérifiées
- `nom-règle-1` - Conforme / Violation détectée
- `nom-règle-2` - Conforme / Violation détectée
...

## Résultats

### Violations
- **`nom-règle`** : Description du problème
  - Actuel : [ce que le code fait]
  - Requis : [ce qu'il devrait faire]
  - Correction : [correction spécifique]

### Conforme
- `nom-règle` : Note brève sur pourquoi c'est correct

## Recommandations
[Liste priorisée des modifications, citant les règles]

Catégories de règles par priorité

Référence rapide

Conception de schéma - Clé primaire (CRITIQUE)

• schema-pk-plan-before-creation - Planifiez ORDER BY avant la création de table (immuable)
• schema-pk-cardinality-order - Ordonnez les colonnes de cardinalité basse à haute
• schema-pk-prioritize-filters - Incluez les colonnes filtrées fréquemment
• schema-pk-filter-on-orderby - Les filtres de requête doivent utiliser le préfixe ORDER BY

Conception de schéma - Types de données (CRITIQUE)

• schema-types-native-types - Utilisez les types natifs, pas String pour tout
• schema-types-minimize-bitwidth - Utilisez le plus petit type numérique qui convient
• schema-types-lowcardinality - LowCardinality pour <10 000 chaînes uniques
• schema-types-enum - Enum pour les ensembles de valeurs finies avec validation
• schema-types-avoid-nullable - Évitez Nullable ; utilisez DEFAULT à la place

Conception de schéma - Partitionnement (ÉLEVÉE)

• schema-partition-low-cardinality - Gardez le décompte de partition 100-1 000
• schema-partition-lifecycle - Utilisez le partitionnement pour le cycle de vie des données, pas les requêtes
• schema-partition-query-tradeoffs - Comprenez les compromis d'élagage de partition
• schema-partition-start-without - Envisagez de commencer sans partitionnement

Conception de schéma - JSON (MOYENNE)

• schema-json-when-to-use - JSON pour les schémas dynamiques ; colonnes typées pour les schémas connus

Optimisation de requête - JOINs (CRITIQUE)

• query-join-choose-algorithm - Sélectionnez l'algorithme en fonction des tailles de table
• query-join-use-any - ANY JOIN quand un seul match est nécessaire
• query-join-filter-before - Filtrez les tables avant de joindre
• query-join-consider-alternatives - Dictionnaires/dénormalisation vs JOIN
• query-join-null-handling - join_use_nulls=0 pour les valeurs par défaut

Optimisation de requête - Indices (ÉLEVÉE)

• query-index-skipping-indices - Indices de saut pour les filtres non-ORDER BY

Optimisation de requête - Vues matérialisées (ÉLEVÉE)

• query-mv-incremental - MVs incrémentielles pour les agrégations en temps réel
• query-mv-refreshable - MVs actualisables pour les joins complexes

Stratégie d'insertion - Traitement par lots (CRITIQUE)

• insert-batch-size - Lot de 10 000-100 000 lignes par INSERT

Stratégie d'insertion - Asynchrone (ÉLEVÉE)

• insert-async-small-batches - Insertions asynchrones pour les lots petits et haute fréquence
• insert-format-native - Format natif pour la meilleure performance

Stratégie d'insertion - Mutations (CRITIQUE)

• insert-mutation-avoid-update - ReplacingMergeTree au lieu d'ALTER UPDATE
• insert-mutation-avoid-delete - DELETE léger ou DROP PARTITION

Stratégie d'insertion - Optimisation (ÉLEVÉE)

• insert-optimize-avoid-final - Laissez les fusions en arrière-plan fonctionner

Intégration agent - Découverte (CRITIQUE)

• agent-discovery-schema - Découvrez toujours le schéma avant d'interroger

Intégration agent - Sécurité (CRITIQUE)

• agent-query-safety - LIMIT, timeouts, exploration progressive

Intégration agent - Connectivité + formats (ÉLEVÉE)

• agent-connect-mcp - Configuration MCP + CLI, découverte d'identifiants, sélection de format de sortie

Quand appliquer

Cette compétence s'active quand vous rencontrez :

• Agent IA se connectant à ClickHouse (MCP, CLI, HTTP)

• Conception de workflow d'agent pour ClickHouse

• Demandes de découverte ou d'exploration de schéma

• Instructions CREATE TABLE

• Modifications ALTER TABLE

• Discussions sur ORDER BY ou PRIMARY KEY

• Questions de sélection de type de données

• Dépannage de requêtes lentes

• Demandes d'optimisation JOIN

• Conception de pipeline d'ingestion de données

• Questions de stratégie de mise à jour/suppression

• Utilisation de ReplacingMergeTree ou d'autres moteurs spécialisés

• Décisions de stratégie de partitionnement

Structure des fichiers de règles

Chaque fichier de règle dans rules/ contient :

• Frontmatter YAML : titre, niveau d'impact, étiquettes
• Explication brève : Pourquoi cette règle importe
• Exemple incorrect : Antimodèle avec explication
• Exemple correct : Meilleure pratique avec explication
• Contexte supplémentaire : Compromis, quand appliquer, références

Document compilé complet

Pour le guide complet avec toutes les règles développées en ligne : AGENTS.md

Utilisez AGENTS.md quand vous devez vérifier plusieurs règles rapidement sans lire les fichiers individuels.