Diagnose Clickhouse Errors
Mappa un codice di errore ClickHouse a un playbook di diagnosi per codice e una risposta Causa/Correzione in 3 sezioni
Richiede configurazione
Cosa fa
Trasforma un errore di runtime di ClickHouse in una risposta fissa Causa / Correzione / Esempio estraendo il codice di errore numerico e caricando un playbook per codice (42, 47, 60, 115, 342 sono inclusi). Si attiva quando un utente incolla una DB::Exception o nomina un codice di errore ClickHouse e desidera una guida sulla causa e la correzione a livello di database, e si rimette esplicitamente all'ispezione del codice sorgente quando l'obiettivo è trovare dove è stata costruita la query SQL fallita. La maggior parte dei playbook si aspetta un ClickHouse live per eseguire una ricerca system.columns / system.tables / system.settings, con un fallback documentato solo testuale quando tale query non può essere eseguita.
Rapporto di test
L'API di GitHub era soggetta a limitazioni di frequenza, quindi ho clonato il repository e trovato SKILL.md in resources/skills/diagnose-clickhouse-errors/; recuperati raw SKILL.md, references/60.md e references/342.md (tutti HTTP 200; un references/999.md inventato ha restituito 404, confermando che solo 5 codici sono inclusi), grep non ha trovato curl|sh, base64, credenziali o testo di iniezione, e ho eseguito il blocco di installazione in una HOME temporanea=$(mktemp -d) dove ha posizionato correttamente SKILL.md più tutti e 5 i file di riferimento. Frasi di attivazione che ho giudicato: DOVREBBE attivarsi — "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"; NON DOVREBBE — "This ClickHouse query takes 40 seconds, help me speed it up" (ottimizzazione, non un fallimento) e "Our Java service logs a ClickHouse UNKNOWN_TABLE error, find where in our repo the table name is built" (la descrizione e una sezione When-Not-To-Use lo rimettono esplicitamente all'ispezione del codice sorgente); 5/5 corretto. Il test di output ha utilizzato l'errore 342 perché references/342.md è l'unico playbook che non richiede lo strumento execute_sql mancante: la baseline ha nominato la colonna `payload` mancante, ha fornito controlli di sola lettura (system.replicas, clusterAllReplicas su system.columns) e tre opzioni di rimedio inclusa `SYSTEM DROP REPLICA ... FROM TABLE events.page_views_local`, mentre l'esecuzione seguita dalla skill si è ridotta a circa 180 parole con intestazioni ## Cause / ## Fix, l'estrazione frammentata memorizzata/analizzata/locale obbligatoria, zero comandi mutanti e "escalate to the cluster maintainer / SRE" — più sicuro per un incidente di produzione ma strettamente meno azionabile per un utente Claude Code che è il manutentore, quindi non l'ho valutato migliore della baseline. Verdetto setup: per 4 dei 5 codici il passaggio di evidenza è un `execute_sql` live che non sono riuscito a eseguire, e tre nomi di strumenti nel corpo (skill_resource, execute_sql, ask_user_question) sono interni al prodotto DataStoria che nessun README o nota sulla skill segnala come non disponibili al di fuori di quell'app.
Testato il: 2026-07-21 · Claude Code 2.x (agent harness)
Installazione
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). Comandi e prompt di esempio
/diagnose-clickhouse-errorsMappa un codice di errore ClickHouse a un playbook di diagnosi per codice e una risposta Causa/Correzione in 3 sezioni
Gli skill si attivano con richieste in linguaggio naturale, senza comandi da ricordare. Dopo l'installazione, prompt come questi lo attivano (in inglese):
Diagnose this ClickHouse error code 241Why did my ClickHouse query fail at runtimeExplain this ClickHouse memory limit exceeded error