ClickAdvisor
Open source · Local-first ClickHouse Performance Advisor

Local-first advisor для производительности ClickHouse

ClickAdvisor помогает DBA, data engineers и platform-командам находить рискованные SQL-паттерны до того, как они превратятся в production-инциденты, перерасход CPU/RAM и лишний cloud-cost. Рекомендации выдаёт проверяемый rule engine, а не LLM. AI используется как интерфейс через MCP — не как источник production-советов.

Начать за минутуПодключить MCPGitHub
119 ClickHouse-специфичных правилLocal-first · zero data egressMCP: локальный и remote endpointVersion-aware анализ
chadvisor — analyze
$ chadvisor analyze --sql query.sql --ch-version 25.3

╭─ ClickAdvisor — Query Analysis Report ──────────────────╮
│  ClickHouse: 25.3  │  Rules: 119  │  Engine: deterministic │
╰─────────────────────────────────────────────────────────╯

● HIGH   rule_id=R-001  tier=1A  confidence=high
  Pattern:  COUNT(DISTINCT user_id)
  Fix:      uniqExact(user_id)   (deterministic, semantically equivalent)

● HIGH   rule_id=R-005  tier=1A  confidence=high
  Pattern:  toDate(event_time) = '2024-01-15'
  Impact:   blocks primary key index → full-part scan
  Fix:      event_time >= '2024-01-15' AND event_time < '2024-01-16'

● MED    rule_id=D-003  tier=1B  confidence=medium
  Pattern:  SELECT * on wide MergeTree

Findings: 3   ·  MCP tools: analyze_query · list_rules · detect_ch_version

Почему ClickAdvisor подходит для production и enterprise

Инструмент строится вокруг требований, которые обычно выдвигают DBA и security-команды: локальность, воспроизводимость, прозрачность и контроль над данными.

Local-first

Анализ выполняется на вашей машине. SQL и метаданные не покидают периметр — критично для банков, телекома и enterprise-контуров.

Zero data egress

Нет обязательных внешних вызовов. Работа с ClickHouse — только по указанному вами HTTP endpoint. Внешние LLM необязательны и полностью отключаемы.

Version-aware анализ

Правила учитывают версию ClickHouse: изменение поведения JOIN, projections, аналитических функций — всё это отражается в применимости правил.

Explainable findings

Каждая находка содержит rule_id, severity, tier, confidence, before/after и ссылку на документацию. Легко ревьюить и включать в code review / DBA review.

Безопасная интеграция с AI через MCP

AI-агент (Claude, Cursor и др.) вызывает ClickAdvisor как MCP-инструмент. Ответы формирует детерминированный движок, LLM только оформляет ответ пользователю.

Детерминированный core

Одинаковый SQL и версия CH → одинаковый набор findings. Никаких «сегодня одно, завтра другое» — важное свойство для production и аудита.

Что умеет ClickAdvisor

Три поверхности продукта — single-query, workload, MCP — над общим детерминированным движком правил.

Анализ одного SQL через CLI

chadvisor analyze --sql query.sql — быстрый разбор запроса локально: parsing → normalization → детерминированные правила → отчёт в console / JSON / Markdown.

Workload analyzer по query_log

CSV-экспорт из system.query_log группируется по normalized fingerprint. Считает executions, total/avg/p95 latency, read rows/bytes, memory и формирует очередь для DBA review.

Live workload через HTTP API

Подключение к ClickHouse через --connect: ClickAdvisor сам достаёт query_log, определяет версию сервера и применяет соответствующие правила.

MCP server для Claude / AI-клиентов

4 MCP-инструмента: analyze_query, analyze_query_json, list_rules, detect_ch_version. Работает в Claude Desktop, Cursor, Continue и совместимых MCP-клиентах.

Remote MCP endpoint (демо)

Публичный URL-based MCP-сервер позволяет протестировать ClickAdvisor из AI-клиента за минуту, без клонирования репозитория и локальной установки.

Local retrieval как вспомогательный слой

Поиск релевантных фрагментов документации подкрепляет findings ссылками, но не является источником рекомендаций — правила остаются первичными.

Workload analyzer

Реальная нагрузка, а не один SQL

ClickAdvisor умеет работать с целым query_log: определяет паттерны, которые чаще всего создают нагрузку, и превращает их в приоритизированный список для DBA. Это позволяет чинить не случайный запрос, а те, что реально жгут CPU, RAM и cloud-cost.

CSV из system.query_log

Выгрузите query_log за интересующий интервал и передайте CSV в ClickAdvisor — не нужно давать прямой доступ к кластеру.

Live через HTTP API

Подключитесь по --connect http://…:8123 — ClickAdvisor сам заберёт query_log и определит версию ClickHouse.

Группировка по fingerprint

Похожие запросы схлопываются в один шаблон: executions, total / avg / p95 latency, read rows / bytes, memory usage.

Top-N очередь для DBA review

Итог — понятный список самых «дорогих» шаблонов запросов с findings, готовый как задачник для оптимизации.

chadvisor — workload
$ chadvisor workload \
    --connect http://ch.prod:8123 \
    --hours 24 --top 20

# Fetching query_log · 24h · grouping by fingerprint …
# ClickHouse detected: 25.3
# Fingerprints: 4 812  ·  analyzed: top 20

┌──── rank ── executions ── p95, ms ── read rows ── findings ─┐
 #1     1 284 301      2 940      8.4B      3 high
    fingerprint: SELECT count(distinct user_id) …
 #2       402 118      1 610      2.1B      2 med
    fingerprint: SELECT * FROM events WHERE toDate(…) = ?
 #3       198 044        870       640M      1 med
    fingerprint: SELECT … JOIN … USING (event_date)
…

Queue exported → workload_review.md, workload.json
MCP · Model Context Protocol

Подключите ClickAdvisor к вашему AI-клиенту

Доступно два режима: локальный MCP-сервер для полной изоляции и удалённый публичный endpoint для быстрого демо — без клонирования и установки.

Remote MCP endpoint

Быстрое демо · без установки

Публичный URL-based MCP-сервер. Подходит, чтобы за минуту попробовать 4 инструмента ClickAdvisor из любого MCP-клиента.

https://clickadvisor-mcp-production.up.railway.app/mcp
Claude Desktop / MCP-клиент (URL-based)
json
{
  "mcpServers": {
    "clickadvisor": {
      "url": "https://clickadvisor-mcp-production.up.railway.app/mcp"
    }
  }
}

Локальный MCP-сервер

Полная изоляция · production-режим

Работает как локальный процесс — SQL и метаданные не покидают вашу машину. Правильный выбор для production и enterprise-контуров.

Claude Desktop config
json
{
  "mcpServers": {
    "clickadvisor": {
      "command": "poetry",
      "args": ["run", "chadvisor", "mcp-server"],
      "cwd": "/path/to/clickadvisor"
    }
  }
}

Доступные MCP-инструменты

analyze_query

Анализ SQL, findings в человекочитаемом виде.

analyze_query_json

То же, но результат в структурированном JSON.

list_rules

Список правил с severity, tier, версией CH.

detect_ch_version

Определение версии ClickHouse по подключению.

Как это работает

Единый pipeline: от одного SQL до реальной production-нагрузки и AI-клиента через MCP.

01

Источник данных

Один SQL, CSV-выгрузка из system.query_log или live-подключение к ClickHouse по HTTP API.

02

Parsing + normalization

Запросы разбираются в AST и приводятся к нормализованному fingerprint для дедупликации и группировки.

03

Deterministic rule engine

119 ClickHouse-специфичных правил с фильтрацией по версии CH. Каждое правило описано (severity, tier, confidence).

04

Optional retrieval

К findings прикрепляются релевантные фрагменты документации — как справка, а не как источник рекомендации.

05

Workload grouping & DBA queue

Похожие запросы группируются, считаются агрегаты (executions, p95, memory) и формируется top-N очередь на DBA review.

06

Отчёт: CLI / JSON / Markdown / MCP

Единый отчёт с before/after и метаданными правил — для терминала, CI, документации или AI-агента через MCP.

Начать за минуту

Выберите сценарий: разовый анализ SQL, разбор реального workload или подключение AI-агента через MCP.

Клонируйте репозиторий, установите зависимости и запустите анализ одного SQL. Опциональный флаг --ch-version улучшает выбор правил.

bash
git clone https://github.com/olyannaa/clickadvisor.git
cd clickadvisor
poetry install

# Analyse a single query
poetry run chadvisor analyze --sql query.sql --ch-version 25.3
⭐ Поставить звезду на GitHub

Архитектура

Три пользовательские поверхности над общим детерминированным ядром.

Surface

Single-query advisor

CLI-разбор одного SQL с отчётом в console / JSON / Markdown.

Surface

Workload analyzer

query_log из CSV или через HTTP API → fingerprints → DBA queue.

Surface

MCP interface

Локальный или remote MCP-сервер для AI-клиентов и агентов.

Внутренние слои
L1SQL parsing / normalization
L2Deterministic ClickHouse rule engine (119 rules, version-aware)
L3Optional local retrieval (supporting docs, not source of truth)
L4Reporting surfaces: CLI · JSON · Markdown · MCP

Начните находить проблемы ClickHouse до продакшена

CLI, workload analyzer и MCP — в одном open-source инструменте.

GitHubПодключить MCPПопробовать workload flowДокументация

Open source · Local-first · Zero data egress · MIT