Это не generic SQL chatbot. Trusted runtime построен вокруг deterministic
ClickHouse rule engine: каждое срабатывание имеет rule_id, severity, tier,
confidence, объяснение и rewrite-пример там, где rewrite безопасен. AI
используется как интерфейс через MCP и как исследовательский workflow, но не как
источник production-рекомендаций.
Planner rows/marks comparison без выполнения пользовательского запроса
MCP server
Local stdio MCP и Streamable HTTP MCP для remote-compatible demo
Local retrieval
Embedded Qdrant KB по ClickHouse docs, Altinity KB, blog/release notes
DS/ML lab
Expert dataset, EDA, features, group split, baselines, error analysis
Почему это важно для ClickHouse
ClickHouse быстро выполняет аналитические запросы, но performance зависит от
деталей движка: MergeTree, sparse primary key, marks/parts, FINAL, skip
indexes, PREWHERE, materialized views, distributed execution, memory/thread
settings и реального workload.
ClickAdvisor закрывает практическую задачу: не “угадать оптимизацию”, а дать
проверяемый ClickHouse-specific сигнал, который можно показать DBA, положить в
CI, передать AI-агенту через MCP или использовать для workload review queue.
Быстрый старт
git clone https://github.com/olyannaa/clickadvisor.git
cd clickadvisor
poetry install
poetry run chadvisor analyze --sql query.sql
По умолчанию Docker image поднимает lightweight Streamable HTTP MCP endpoint
на /mcp. Образ предназначен для demo/deploy сценария и не ставит тяжёлые
ML/retrieval зависимости.
SELECT
e.country,
COUNT(DISTINCT e.user_id) AS unique_users,
sumIf(e.revenue, e.status = 'paid') AS paid_revenue
FROM
(
SELECT *
FROM events FINAL
WHERE message LIKE '%timeout%'
AND (country = 'RU' OR country = 'KZ' OR country = 'BY')
) AS e
JOIN users AS u
ON toUInt64(e.user_id) = u.id
GROUP BY e.country
HAVING e.country = 'RU'
ORDER BY paid_revenue DESC;
На этом запросе ClickAdvisor находит 10 срабатываний, включая:
workload группирует похожие запросы по normalized fingerprint, считает
executions, total/avg/p95 latency, read rows/bytes и memory usage, затем
прогоняет representative SQL через rule engine и формирует top-N DBA review
queue.
Пример top risk из sample:
Priority: high
Executions: 2
Total duration: 2180 ms
Read bytes: 350000000
Rule IDs: D-003, D-004, D-005, D-007, R-102
Normalized SQL: select * from events final where message like ?
Если открыть /mcp в браузере, можно увидеть ошибку Not Acceptable: Client must accept text/event-stream. Это нормально: endpoint предназначен для MCP
clients, а не для обычной HTML-страницы.
ClickAdvisor выполняет только EXPLAIN ESTIMATE, не запускает пользовательский
запрос и не читает result data.
Data Science и ML
DS-часть нужна не для замены rule engine. Её задача — формализовать качество,
сравнить подходы, найти ограничения и подготовить triage/prioritization layer.
Expert dataset:
Показатель
Значение
SQL records
20 235
Real / synthetic
19 090 / 1 145
Successful local replay records
9 837
Final labels
low 4 253 / medium 14 285 / high 1 697
Numeric feature count
115
Rule vocabulary
54
Ключевой факт по источнику меток:
Label source
Records
Интерпретация
rule_only
14 693
модель в основном учит compressed rule-engine signal
measured_only
4 635
независимый сигнал из latency/read/memory
both
907
самый надёжный core, где static и measured signals согласны
Baseline ladder:
Model
CV macro-F1
Holdout macro-F1
Dummy most frequent
0.275 +/- 0.000
0.278
Dummy stratified
0.328 +/- 0.009
0.335
TF-IDF + Logistic Regression
0.864 +/- 0.011
0.882
Structural/rule LR
0.827 +/- 0.004
0.837
Random Forest all features
0.938 +/- 0.006
0.949
CatBoost tabular
0.873 +/- 0.008
0.871
Holdout error analysis для Random Forest:
Slice
Records
Macro-F1
High recall
all_holdout
3 039
0.949
0.887
rule_only
2 235
0.970
0.990
measured_only
672
0.595
0.785
both
132
0.975
1.000
Вывод: ML полезен для triage, confidence grouping и review queue ordering, но
production-рекомендации остаются rule-first.
poetry run ruff check clickadvisor tests scripts
poetry run mypy clickadvisor
poetry run pytest --ignore=tests/integration -q
poetry run python scripts/rules/validate_catalog.py
poetry run python scripts/benchmark/validate_cases.py
poetry run python scripts/eval/run_benchmark.py --cases-dir benchmark/cases/synthetic_expanded --mode strict
Security
ClickAdvisor можно запускать внутри компании, CI/CD или локальной среды
инженера без отправки SQL, DDL, EXPLAIN, environment context и query_log во
внешние LLM/API.
Что может читать ClickAdvisor:
SQL text;
optional schema DDL;
optional EXPLAIN output;
optional environment JSON;
sanitized system.query_log CSV или read-only live metadata;
SELECT version() при version detection;
EXPLAIN ESTIMATE только при явном флаге.
Что он не делает по умолчанию:
не выполняет пользовательский SQL для speedup measurement;
Chưa có danh sách công cụ. Máy chủ từ xa sẽ có danh sách sau lần kiểm tra tình trạng đầu tiên.
Câu hỏi thường gặp
Câu hỏi
Làm thế nào để cài đặt Clickadvisor?
Sao chép cấu hình stdio cho Cursor, Claude Desktop, Claude Code hoặc VS Code trên trang này. Cấu hình dùng bản cài đặt của nhà phát hành, không phải proxy của PlugMCP.
Clickadvisor có cần khóa API không?
Bản ghi này không liệt kê biến môi trường bắt buộc nào.
Clickadvisor dùng giao thức truyền tải nào?
Clickadvisor chạy cục bộ qua stdio.
Clickadvisor được kiểm tra lần cuối khi nào?
Kiểm tra lần cuối: 2026-10-28. CLI advisor for ClickHouse query optimization. Formally verified rewrite rules + RAG + MCP server.