Diagnose Clickhouse Errors
Mappe un code d'erreur ClickHouse à un playbook de diagnostic par code et une réponse Cause/Correction en 3 sections
Fonctionne avec configuration
Ce que fait
Transforme une erreur d'exécution ClickHouse en une réponse fixe Cause / Correction / Exemple en extrayant le code d'erreur numérique et en chargeant un playbook par code (42, 47, 60, 115, 342 sont inclus). Se déclenche lorsqu'un utilisateur colle une DB::Exception ou nomme un code d'erreur ClickHouse et souhaite des conseils de cause et de correction au niveau de la base de données, et renvoie explicitement à l'inspection du code source lorsque l'objectif est de trouver où le SQL défaillant a été construit. La plupart des playbooks s'attendent à ce qu'un ClickHouse en direct exécute une recherche system.columns / system.tables / system.settings, avec un repli textuel documenté lorsque cette requête ne peut pas s'exécuter.
Rapport de test
L'API GitHub était limitée en débit, j'ai donc cloné le dépôt et trouvé SKILL.md à resources/skills/diagnose-clickhouse-errors/ ; récupéré SKILL.md, references/60.md et references/342.md (tous HTTP 200 ; un references/999.md inventé a renvoyé 404, confirmant que seuls 5 codes sont livrés), grep n'a trouvé aucun curl|sh, base64, identifiant ou texte d'injection, et j'ai exécuté le bloc d'installation dans un HOME temporaire ($(mktemp -d)) où il a placé SKILL.md plus les 5 fichiers de référence correctement. Phrases de déclenchement que j'ai jugées : DEVRAIT se déclencher — « My query failed with Code: 60. DB::Exception: Table analytics.evnts doesn't exist. (UNKNOWN_TABLE), what's wrong? », « ClickHouse throws error code 115 on my SETTINGS clause, how do I fix it? », « Getting NUMBER_OF_ARGUMENTS_DOESNT_MATCH from toStartOfInterval in ClickHouse » ; NE DEVRAIT PAS — « This ClickHouse query takes 40 seconds, help me speed it up » (optimisation, pas un échec) et « Our Java service logs a ClickHouse UNKNOWN_TABLE error, find where in our repo the table name is built » (la description et une section When-Not-To-Use renvoient explicitement cela à l'inspection du code source) ; 5/5 correct. Le test de sortie a utilisé l'erreur 342 car references/342.md est le seul playbook ne nécessitant pas l'outil execute_sql manquant : la base de référence a nommé la colonne `payload` manquante, a donné des vérifications en lecture seule (system.replicas, clusterAllReplicas sur system.columns) et trois options de remédiation incluant `SYSTEM DROP REPLICA ... FROM TABLE events.page_views_local`, tandis que l'exécution suivie par la compétence s'est effondrée à environ 180 mots avec les titres ## Cause / ## Fix, l'extraction fragmentaire stockée/analysée/locale obligatoire, zéro commandes mutantes et « escalate to the cluster maintainer / SRE » — plus sûr pour un incident de production mais strictement moins exploitable pour un utilisateur de Claude Code qui est le mainteneur, je l'ai donc noté pas mieux que la base de référence. Verdict setup : pour 4 des 5 codes, l'étape de preuve est un `execute_sql` en direct que je n'ai pas pu exécuter, et trois noms d'outils dans le corps (skill_resource, execute_sql, ask_user_question) sont des internes de produit DataStoria qu'aucun README ou note de compétence ne signale comme indisponibles en dehors de cette application.
Testé le: 2026-07-21 · Claude Code 2.x (agent harness)
Installation
git clone --depth 1 https://github.com/FrankChen021/datastoria.git /tmp/diagnose-clickhouse-errors-src
mkdir -p ~/.claude/skills
cp -R /tmp/diagnose-clickhouse-errors-src/resources/skills/diagnose-clickhouse-errors ~/.claude/skills/diagnose-clickhouse-errors
# Verified: places SKILL.md + references/{42,47,60,115,342}.md under ~/.claude/skills/diagnose-clickhouse-errors/
# The repo is the DataStoria web console (~large clone); only this one directory is needed.
# Sibling skills in the same folder that this one references: source-code-inspection, optimize-clickhouse-sql,
# clickhouse-system-queries, diagnose-clickhouse-clusters, sql-expert, visualization.
# MANUAL STEP: the skill body calls DataStoria-internal tools that do not exist in Claude Code:
# skill_resource -> read references/<code>.md yourself
# ask_user_question -> AskUserQuestion
# execute_sql -> needs a ClickHouse MCP server or a clickhouse-client you run by hand;
# without it, codes 42/47/60/115 fall back to text-only diagnosis (documented in each file). Commandes et exemples de prompts
/diagnose-clickhouse-errorsMappe un code d'erreur ClickHouse à un playbook de diagnostic par code et une réponse Cause/Correction en 3 sections
Les skills se déclenchent sur des demandes en langage courant — aucune commande à retenir. Après installation, des prompts comme ceux-ci l'activent (en anglais) :
Diagnose this ClickHouse error code 241Why did my ClickHouse query fail at runtimeExplain this ClickHouse memory limit exceeded error