К основному содержанию
скилл CX Codex

clickhouse-query — скилл для Claude Code: запросы к ClickHouse

Скилл clickhouse-query гоняет ad-hoc запросы к ClickHouse прямо из чата с агентом: метрики, события, план выполнения. По умолчанию только чтение.

Apache-2.0 ★ 7 327 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add civitai/civitai --skill clickhouse-query -a claude-code
Открыть на GitHub

Что делает clickhouse-query

Скилл даёт агенту один скрипт query.mjs, которому SQL передают строкой: node .claude/skills/clickhouse-query/query.mjs "SELECT count() FROM views". Флаги закрывают обычные нужды: --explain показывает план, --json отдаёт результат структурой, --quiet оставляет только строки, --file читает запрос из файла, --timeout меняет лимит времени.

Запись выключена: INSERT, ALTER и DROP отклоняются, пока не добавишь --writable, а перед этим скилл требует спросить разрешение у пользователя. Таймаут по умолчанию 30 секунд — тяжёлая агрегация на нём и обрывается, поэтому такие запросы запускай с --timeout 60 или больше.

Внутри есть памятка по таблицам (views, modelEvents, modelVersionEvents, userActivities, images, reactions, reports, entityMetricEvents) и по репликам: прод живёт на реплика-кластере, поэтому системные таблицы вроде system.query_log читаются через clusterAllReplicas(default, system.query_log). Обычный SELECT вернёт только тот узел, к которому подключён скрипт.

Какие задачи решает

  • посчитать просмотры и события в views за последнюю неделю
  • посмотреть план выполнения до того, как запрос уедет в прод
  • найти самые дорогие по памяти SELECT за сутки по всем репликам
  • выгрузить агрегат в JSON и отдать его в обработку
  • проверить, что трекинг событий пишет нужные строки

Примеры запросов агенту

  • Посчитай строки в views за последние 7 дней и верни результат в JSON.
  • Покажи план запроса SELECT * FROM views WHERE userId = 1 через --explain.
  • Достань из system.query_log самые тяжёлые по памяти SELECT за сутки, читая все реплики.

Как установить clickhouse-query

1Через Skills CLI (Vercel)

npx skills add civitai/civitai --skill clickhouse-query -a claude-code

2Вручную: положить файлы

~/.claude/skills/clickhouse-query/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/clickhouse-query/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о clickhouse-query

Как установить clickhouse-query в Claude Code?

Выполни npx skills add civitai/civitai --skill clickhouse-query -a claude-code. Скилл окажется в ~/.claude/skills/clickhouse-query/SKILL.md.

Что делает clickhouse-query?

Запускает произвольные запросы к ClickHouse через скрипт query.mjs: считает метрики, разбирает события, показывает план выполнения и переключает вывод на JSON.

Может ли скилл писать в базу?

По умолчанию нет: INSERT, ALTER и DROP блокируются. Флаг --writable снимает запрет, но скилл обязан сначала получить разрешение пользователя.

Исходный текст

SKILL.md · Apache-2.0
---
name: clickhouse-query
description: Run ClickHouse queries for analytics, metrics analysis, and event data exploration. Use when you need to query ClickHouse directly, analyze metrics, check event tracking data, or test query performance. Read-only by default.
---

# ClickHouse Query Testing

Use this skill to run ad-hoc ClickHouse queries for analytics, metrics analysis, and debugging.

## Running Queries

Use the included query script:

```bash
node .claude/skills/clickhouse-query/query.mjs "SELECT count() FROM views"
```

### Options

| Flag | Description |
|------|-------------|
| `--explain` | Show query execution plan |
| `--writable` | Allow write operations (requires user permission) |
| `--timeout <s>`, `-t` | Query timeout in seconds (default: 30) |
| `--file`, `-f` | Read query from a file |
| `--json` | Output results as JSON |
| `--quiet`, `-q` | Minimal output, only results |

### Examples

```bash
# Count rows in a table
node .claude/skills/clickhouse-query/query.mjs "SELECT count() FROM views"

# Query with filters
node .claude/skills/clickhouse-query/query.mjs "SELECT * FROM modelEvents WHERE modelId = 123 LIMIT 10"

# Check query execution plan
node .claude/skills/clickhouse-query/query.mjs --explain "SELECT * FROM views WHERE userId = 1"

# Override default 30s timeout for longer queries
node .claude/skills/clickhouse-query/query.mjs --timeout 60 "SELECT ... (complex aggregation)"

# Query from file
node .claude/skills/clickhouse-query/query.mjs -f my-query.sql

# JSON output for processing
node .claude/skills/clickhouse-query/query.mjs --json "SELECT type, count() FROM modelEvents GROUP BY type"
```

## Safety Features

1. **Read-only by default**: Blocks INSERT/ALTER/DROP unless `--writable` flag is used
2. **30 second timeout**: Prevents runaway queries (override with `--timeout`)
3. **Explicit permission required**: Before using `--writable`, you MUST ask the user for permission

## When to Use --writable

Only use the `--writable` flag when:
- The user explicitly requests write access
- You need to insert test data
- You're running maintenance operations

**IMPORTANT**: Always ask the user for permission before running with `--writable`.

## Common Tables

| Table | Description |
|-------|-------------|
| `views` | Page/entity view events |
| `modelEvents` | Model create/publish/update events |
| `modelVersionEvents` | Model version events including downloads |
| `userActivities` | User registration, login, subscription events |
| `images` | Image upload/delete events |
| `reactions` | Like/dislike events |
| `reports` | Content report events |
| `entityMetricEvents` | Aggregated metric events |

## Querying Replica Clusters

**IMPORTANT**: Production uses a ClickHouse replica cluster. When querying system tables (logs, metrics, etc.), you must use `clusterAllReplicas()` to get data from all nodes.

### System Tables on Replica Clusters

```sql
-- WRONG: Only queries the node you're connected to
SELECT * FROM system.query_log WHERE event_time > now() - INTERVAL 1 HOUR

-- CORRECT: Queries all replicas in the cluster
SELECT * FROM clusterAllReplicas(default, system.query_log)
WHERE event_time > now() - INTERVAL 1 HOUR
```

### Common System Table Queries

```sql
-- Find recent queries across all nodes
SELECT
    hostname(),
    event_time,
    query_duration_ms,
    formatReadableSize(memory_usage) AS memory,
    query
FROM clusterAllReplicas(default, system.query_log)
WHERE type = 'QueryFinish'
    AND event_time > now() - INTERVAL 5 MINUTE
ORDER BY event_time DESC
LIMIT 20

-- Find expensive queries by memory usage (last 24 hours)
SELECT
    count() as query_count,
    user,
    sum(memory_usage) AS total_memory,
    normalized_query_hash
FROM clusterAllReplicas(default, system.query_log)
WHERE event_time > now() - INTERVAL 1 DAY
    AND query_kind = 'Select'
    AND type = 'QueryFinish'
GROUP BY normalized_query_hash, user
ORDER BY total_memory DESC
LIMIT 10

-- Search query logs by pattern
SELECT event_time, query_id, query, type
FROM clusterAllReplicas(default, merge('system', '^query_log*'))
WHERE query ILIKE '%some_table%'
    AND event_time > now() - INTERVAL 5 MINUTE

-- Debug a specific query across all nodes
SELECT hostname(), message
FROM clusterAllReplicas(default, system.text_log)
WHERE query_id = 'your-query-id-here'
ORDER BY event_time_microseconds ASC
```

### When to Use clusterAllReplicas()

| Use Case | Function |
|----------|----------|
| System tables (query_log, text_log, etc.) | `clusterAllReplicas(default, system.table_name)` |
| Application tables (views, modelEvents, etc.) | Direct query (already distributed) |
| Search multiple system tables | `clusterAllReplicas(default, merge('system', '^pattern*'))` |

## ClickHouse SQL Tips

```sql
-- Use count() not COUNT(*)
SELECT count() FROM views

-- Date filtering with toDate()
SELECT * FROM views WHERE toDate(time) = today()

-- Last 7 days
SELECT * FROM modelEvents WHERE time > now() - INTERVAL 7 DAY

-- Aggregations
SELECT type, count() as cnt FROM modelEvents GROUP BY type ORDER BY cnt DESC
```

© civitai · Apache-2.0 · civitai/civitai

Похожие скиллы

Все скиллы по теме «Данные и базы» →
clickhouse-best-practices ClickHouse Inc Скилл clickhouse-best-practices для Claude Code проверяет схемы таблиц, SQL-запросы, полнотекстовый поиск и вставку данных в ClickHouse по набору из 36 правил. CX Codex +1 23 400установок clickhouse-js-node-coding ClickHouse Скилл clickhouse-js-node-coding помогает агенту писать код с пакетом @clickhouse/client: подключение, вставка строк, выборки, параметры запросов. CX Codex +1 7 300установок clickhouse-architect terrylica Скилл clickhouse-architect проектирует схемы ClickHouse v24.4+, подбирает кодеки сжатия и настраивает ключи сортировки под облачные и серверные развёртывания. CX Codex +1 157установок clickhouse-cloud-management terrylica Скилл clickhouse-cloud-management помогает управлять пользователями и правами доступа в ClickHouse Cloud через SQL-запросы по HTTPS. CX Codex +1 126установок hypequery ClickHouse hypequery MCP-сервер hypequery ClickHouse для Claude Code открывает агенту доступ к аналитике ClickHouse через размеченные датасеты и метрики. Прямой SQL блокируется, а реквизиты базы остаются скрытыми. CX Codex +1 ★ 106звёзд репо clickhouse-io affaan-m Скилл clickhouse-io для Claude Code помогает проектировать таблицы на движках MergeTree и ускорять медленные аналитические запросы. CX Codex +1 6 200установок

Из того же набора11

Весь набор →
quick-mockups Скилл quick-mockups для Claude Code: генерирует от 3 до 5 параллельных вариантов интерфейса в HTML для сравнения разных сеток и подачи новой фичи. CX Codex +1 1 700установок meilisearch-admin Скилл meilisearch-admin для мониторинга Meilisearch: проверяет индексы, задачи, здоровье сервера и настройки поиска. Помогает отловить ошибки в индексировании и понять, что происходит с поиском. CX Codex +1 132установок postgres-query Скилл postgres-query для Claude Code выполняет запросы к PostgreSQL при отладке и профилировании базы данных. Запускает команды через скрипт с обязательным указанием контура --prod или --dev. CX Codex +1 105установок agent-review Скилл agent-review для Claude Code отправляет код на проверку внешнему AI-агенту. Выполняет ревью, помогает оценить архитектурные решения и получить второе мнение. CX Codex +1 3установок discord Отправляет сообщения, анонсы и эмбеды в каналы Discord через REST API. Передаёт уведомления о релизах и командную переписку из консоли. CX Codex +1 ★ 7 327звёзд репо redis-inspect Скилл redis-inspect для Claude Code проверяет ключи, значения и TTL в основном и системном инстансах Redis. Показывает, что сейчас хранится в кэше. CX Codex +1 ★ 7 327звёзд репо postgres-query Скилл postgres-query выполняет SQL-запросы к PostgreSQL, запускает EXPLAIN ANALYZE и проверяет индексы через агент в безопасном режиме чтения. CX Codex +1 ★ 7 327звёзд репо browser-automation Скилл browser-automation для Claude Code запускает браузер через HTTP-сервер, сохраняет авторизацию и поддерживает несколько сессий. Проверяет пользовательские потоки и повторяемые сценарии. CX Codex +1 ★ 7 327звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой