Diagnose Clickhouse Errors
Mapper en ClickHouse-fejlkode til en per-kode diagnose-playbook og et 3-sektions årsag/løsning-svar
Virker med opsætning
Hvad det gør
Omdanner en ClickHouse runtime-fejl til et fast årsag / løsning / eksempel-svar ved at udtrække den numeriske fejlkode og indlæse en per-kode playbook (42, 47, 60, 115, 342 er bundtet). Udløses, når en bruger indsætter en DB::Exception eller navngiver en ClickHouse-fejlkode og ønsker database-niveau årsags- og løsningsvejledning, og udskyder eksplicit til kildekodeinspektion, når målet er at finde, hvor den fejlagtige SQL blev bygget. De fleste playbooks forventer en live ClickHouse til at køre en system.columns / system.tables / system.settings opslag, med en dokumenteret tekst-kun fallback, når den forespørgsel ikke kan køre.
Testrapport
GitHub API var rate-begrænset, so I cloned the repo and found SKILL.md at resources/skills/diagnose-clickhouse-errors/; rå-hentede SKILL.md, references/60.md og references/342.md (alle HTTP 200; en opdigtet references/999.md returnerede 404, hvilket bekræftede, at kun 5 koder sendes), grep fandt ingen curl|sh, base64, legitimationsoplysninger eller injection-tekst, og jeg kørte installationsblokken i en midlertidig HOME=$(mktemp -d), hvor den placerede SKILL.md plus alle 5 referencefiler korrekt. Udløsningsfraser jeg bedømte: SKULLE udløses — "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"; SKULLE IKKE — "This ClickHouse query takes 40 seconds, help me speed it up" (optimering, ikke en fejl) og "Our Java service logs a ClickHouse UNKNOWN_TABLE error, find where in our repo the table name is built" (beskrivelsen og en When-Not-To-Use-sektion overdrager eksplicit dette til kildekodeinspektion); 5/5 korrekt. Output-test brugte fejl 342, fordi references/342.md er den eneste playbook, der ikke kræver det manglende execute_sql-værktøj: baseline navngav den manglende `payload`-kolonne, gav skrivebeskyttede checks (system.replicas, clusterAllReplicas over system.columns) og tre afhjælpningsmuligheder, herunder `SYSTEM DROP REPLICA ... FROM TABLE events.page_views_local`, mens den skill-fulgte kørsel kollapsede til ~180 ord med overskrifterne ## Cause / ## Fix, den påbudte lagrede/parsed/lokale fragmentudtrækning, nul muterende kommandoer og "escalate to the cluster maintainer / SRE" — sikrere for en prod-hændelse, men strengt taget mindre handlingsorienteret for en Claude Code-bruger, der er maintainer, så jeg scorede den ikke bedre end baseline. Dom opsætning: for 4 ud af de 5 koder er bevis-trinnet en live `execute_sql`, jeg ikke kunne udføre, og tre værktøjsnavne i kroppen (skill_resource, execute_sql, ask_user_question) er DataStoria-produktinterne, som ingen README eller skill-note flagger som utilgængelige uden for den app.
Testet: 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). Kommandoer og eksempelprompter
/diagnose-clickhouse-errorsMapper en ClickHouse-fejlkode til en per-kode diagnose-playbook og et 3-sektions årsag/løsning-svar
Skills udløses af almindelige forespørgsler — ingen kommandoer at huske. Efter installationen aktiverer prompter som disse skillen (på engelsk):
Diagnose this ClickHouse error code 241Why did my ClickHouse query fail at runtimeExplain this ClickHouse memory limit exceeded error