Diagnose Clickhouse Errors
Mapuje kod błędu ClickHouse na playbook diagnostyczny dla każdego kodu i 3-sekcyjną odpowiedź Przyczyna/Naprawa
Działa po konfiguracji
Co robi ten skill
Przekształca błąd wykonawczy ClickHouse w stałą odpowiedź Przyczyna / Naprawa / Przykład poprzez wyodrębnienie numerycznego kodu błędu i załadowanie playbooka dla każdego kodu (42, 47, 60, 115, 342 są dołączone). Uruchamia się, gdy użytkownik wkleja DB::Exception lub podaje kod błędu ClickHouse i chce uzyskać wskazówki dotyczące przyczyny i naprawy na poziomie bazy danych, i wyraźnie odwołuje się do inspekcji kodu źródłowego, gdy celem jest znalezienie miejsca, w którym zbudowano wadliwy SQL. Większość playbooków oczekuje aktywnego ClickHouse do uruchomienia wyszukiwania system.columns / system.tables / system.settings, z udokumentowanym awaryjnym rozwiązaniem tylko tekstowym, gdy to zapytanie nie może zostać uruchomione.
Raport z testu
GitHub API miało ograniczenia szybkości, więc sklonowałem repozytorium i znalazłem SKILL.md w resources/skills/diagnose-clickhouse-errors/; surowo pobrałem SKILL.md, references/60.md i references/342.md (wszystkie HTTP 200; wymyślony references/999.md zwrócił 404, potwierdzając, że tylko 5 kodów jest dostarczanych), grep nie znalazł curl|sh, base64, poświadczeń ani tekstu iniekcji, i uruchomiłem blok instalacyjny w tymczasowym HOME=$(mktemp -d), gdzie umieścił SKILL.md plus wszystkie 5 plików referencyjnych poprawnie. Ocenione frazy wyzwalające: POWINNY uruchomić — "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"; NIE POWINNY — "This ClickHouse query takes 40 seconds, help me speed it up" (optymalizacja, nie błąd) i "Our Java service logs a ClickHouse UNKNOWN_TABLE error, find where in our repo the table name is built" (opis i sekcja When-Not-To-Use wyraźnie przekazują to do inspekcji kodu źródłowego); 5/5 poprawnie. Test wyjścia użył błędu 342, ponieważ references/342.md jest jedynym playbookiem, który nie wymaga brakującego narzędzia execute_sql: linia bazowa nazwała brakującą kolumnę `payload`, podała sprawdzenia tylko do odczytu (system.replicas, clusterAllReplicas nad system.columns) i trzy opcje naprawcze, w tym `SYSTEM DROP REPLICA ... FROM TABLE events.page_views_local`, podczas gdy uruchomienie zgodne z umiejętnością skróciło się do ~180 słów z nagłówkami ## Cause / ## Fix, wymaganym wyodrębnianiem przechowywanych/sparsowanych/lokalnych fragmentów, zerem poleceń mutujących i "escalate to the cluster maintainer / SRE" — bezpieczniejsze w przypadku incydentu produkcyjnego, ale ściśle mniej użyteczne dla użytkownika Claude Code, który jest konserwatorem, so I scored it no better than baseline. Werdykt konfiguracja: dla 4 z 5 kodów krok dowodowy to aktywne `execute_sql`, którego nie mogłem wykonać, a trzy nazwy narzędzi w treści (skill_resource, execute_sql, ask_user_question) to wewnętrzne elementy produktu DataStoria, których żadne README ani notatka umiejętności nie oznacza jako niedostępne poza tą aplikacją.
Testowano: 2026-07-21 · Claude Code 2.x (agent harness)
Instalacja
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). Komendy i przykładowe prompty
/diagnose-clickhouse-errorsMapuje kod błędu ClickHouse na playbook diagnostyczny dla każdego kodu i 3-sekcyjną odpowiedź Przyczyna/Naprawa
Skille uruchamiają się na zwykłe polecenia — bez komend do zapamiętania. Po instalacji aktywują go prompty takie jak te (po angielsku):
Diagnose this ClickHouse error code 241Why did my ClickHouse query fail at runtimeExplain this ClickHouse memory limit exceeded error