ClickAdvisor

Local-first ClickHouse Performance Advisor для SQL, workload и AI-agent workflow.

ClickAdvisor помогает DBA, data engineers, backend engineers и platform-командам находить рискованные ClickHouse SQL-паттерны до production-инцидентов, перерасхода CPU/RAM и дорогих cloud-счетов.

Это не generic SQL chatbot. Trusted runtime построен вокруг deterministic ClickHouse rule engine: каждое срабатывание имеет rule_id, severity, tier, confidence, объяснение и rewrite-пример там, где rewrite безопасен. AI используется как интерфейс через MCP и как исследовательский workflow, но не как источник production-рекомендаций.

Содержание

• Что умеет
• Быстрый старт
• Single-query advisor
• Workload analyzer
• MCP
• Data Science и ML
• Evaluation
• Security
• Документация

Что умеет

Почему это важно для 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:

docker build -t clickadvisor .
docker run --rm -p 8000:8000 clickadvisor

По умолчанию Docker image поднимает lightweight Streamable HTTP MCP endpoint на /mcp. Образ предназначен для demo/deploy сценария и не с��авит тяжёлые ML/retrieval зависимости.

Single-query Advisor

poetry run chadvisor analyze \
  --sql query.sql \
  --ch-version 25.3 \
  --output-format markdown \
  --no-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 срабатываний, включая:

• R-001: COUNT(DISTINCT user_id) -> uniqExact(user_id);
• R-002: approximate distinct через uniq, если это допустимо;
• D-005 / R-102: leading wildcard search и skip-index/search strategy;
• D-007: дорогой FINAL на MergeTree;
• D-011, R-008, R-020: приведение типов вокруг JOIN/filter keys;
• R-011: non-aggregate HAVING можно перенести в WHERE;
• R-014: дорогой GROUP BY по строковой колонке.

Workload Analyzer

CSV export из system.query_log:

poetry run chadvisor workload \
  --query-log examples/query_log_sample.csv \
  --output-format markdown \
  --top-n 3

Live read-only режим через ClickHouse HTTP API:

poetry run chadvisor workload \
  --connect http://localhost:8123 \
  --user default \
  --password secret \
  --since 24h \
  --output-format markdown \
  --top-n 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 ?

Подробнее: docs/workload.md.

MCP

Локальный stdio MCP для Claude Desktop, Cursor, Zed и других MCP-клиентов:

poetry run chadvisor mcp-server

Публичный MCP endpoint для проверки без локальной установки:

https://clickadvisor-mcp-production.up.railway.app/mcp

В Claude / Anthropic API remote MCP подключается как URL-based server:

Claude / Claude Desktop:
Customize -> Connectors -> Add custom connector
Name: ClickAdvisor
URL:  https://clickadvisor-mcp-production.up.railway.app/mcp

Claude Code:

claude mcp add --transport http clickadvisor \
  https://clickadvisor-mcp-production.up.railway.app/mcp

Anthropic API:

{
  "mcp_servers": [
    {
      "type": "url",
      "name": "clickadvisor",
      "url": "https://clickadvisor-mcp-production.up.railway.app/mcp"
    }
  ]
}

Доступные MCP tools:

Если открыть /mcp в браузере, можно увидеть ошибку Not Acceptable: Client must accept text/event-stream. Это нормально: endpoint предназначен для MCP clients, а не для обычной HTML-страницы.

Подробнее:

• docs/MCP.md
• docs/mcp-deployment.md
• docs/ai-mcp-workflow.md

Schema, EXPLAIN и Environment

poetry run chadvisor analyze \
  --sql query.sql \
  --schema schema.sql \
  --explain explain.json \
  --environment environment.json

Environment context включает настройки, hardware, cluster и workload facts для E-* и части Tier 2 advisory rules:

{
  "settings": {
    "max_threads": 64,
    "max_memory_usage": 90000000000,
    "join_use_nulls": true
  },
  "hardware": {
    "cpu_cores": 16,
    "ram_bytes": 128000000000,
    "disk_type": "hdd"
  },
  "workload": {
    "interactive_queries": true,
    "large_join": true,
    "bulk_inserts": true
  },
  "cluster": {
    "shards": 4,
    "replicas": 2
  }
}

EXPLAIN ESTIMATE:

poetry run chadvisor analyze \
  --sql query.sql \
  --connect http://localhost:8123 \
  --ch-user default \
  --ch-password secret \
  --explain-estimate

ClickAdvisor выполняет только EXPLAIN ESTIMATE, не запускает пользовательский запрос и не читает result data.

Data Science и ML

DS-часть нужна не для замены rule engine. Её задача — формализовать качество, сравнить подходы, найти ограничения и подготовить triage/prioritization layer.

Expert dataset:

Ключевой факт по источнику меток:

Baseline ladder:

Holdout error analysis для Random Forest:

Вывод: ML полезен для triage, confidence grouping и review queue ordering, но production-рекомендации остаются rule-first.

Подробнее:

• docs/evaluation.md
• docs/experiments/risk_labeling_ds_summary.md
• data/ml/expert_dataset/eda/ds_report.md

Evaluation

Воспроизводимые проверки:

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;
• не читает result data;
• не выполняет ANALYZE;
• не применяет DDL/mutations;
• не делает hidden remote LLM calls.

Подробнее: docs/security-local-first.md.

Документация

• Architecture
• Evaluation
• Workload Analyzer
• MCP
• MCP Deployment
• Security / Local-First
• Rule Catalog