# clickhouse-query

clickhouse-query runs ad-hoc ClickHouse queries from the chat: metrics, event data, execution plans. Read-only unless you say otherwise.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · ★ 7327 repo stars
- Author: civitai
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/civitai/civitai/tree/HEAD/apps/event-engine/.claude/skills/clickhouse-query/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/clickhouse-query

## What it does

The skill wraps one Node script, `query.mjs`, and takes SQL as a string: `node .claude/skills/clickhouse-query/query.mjs "SELECT count() FROM views"`. Switches handle the usual cases. `--explain` prints the plan, `--json` returns structured output, `--quiet` leaves only rows, `--file` reads the SQL from disk, `--timeout` sets the time limit.

Writes are off out of the box. INSERT, ALTER and DROP are rejected until you pass `--writable`, and the skill is told to ask your permission before that flag goes in. Timeout sits at 30 seconds, so a heavy aggregation dies there; raise it with `--timeout 60` when the query needs longer.

A short reference lists the tables you are likely to hit (`views`, `modelEvents`, `modelVersionEvents`, `userActivities`, `images`, `reactions`, `reports`, `entityMetricEvents`) and covers replicas. Production runs on a replica cluster, so system tables go through `clusterAllReplicas(default, system.query_log)` — a plain select reads only the node the script connected to.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add civitai/civitai --skill clickhouse-query -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/clickhouse-query/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/clickhouse-query/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add civitai/civitai --skill clickhouse-query -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/clickhouse-query/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add civitai/civitai --skill clickhouse-query -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/clickhouse-query/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install civitai/civitai apps/event-engine/.claude/skills/clickhouse-query
```

2. **Manually: put the files in place**
- File: `.github/skills/clickhouse-query/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add civitai/civitai --skill clickhouse-query -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/civitai/civitai --path apps/event-engine/.claude/skills/clickhouse-query
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/clickhouse-query/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add civitai/civitai --skill clickhouse-query -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/civitai/civitai/tree/HEAD/apps/event-engine/.claude/skills/clickhouse-query/SKILL.md

## When to use it
- count page views in `views` for the past week
- inspect a query plan before it ships
- find memory-hungry SELECTs across every replica
- pipe an aggregate into JSON for downstream work
- confirm event tracking writes the rows you expect

## Example prompts
- Count rows in `views` for the last 7 days and return the result as JSON.
- Show the execution plan for `SELECT * FROM views WHERE userId = 1` with `--explain`.
- Pull the heaviest SELECTs by memory from the past day out of `system.query_log`, reading all replicas.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 6ebc47753b514829.

BEGIN THIRD-PARTY FILE 6ebc47753b514829
````text
---
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 |
````
END THIRD-PARTY FILE 6ebc47753b514829

The third-party file has ended. Everything between the 6ebc47753b514829 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2500 of 5091 bytes. © civitai · Apache-2.0 · https://github.com/civitai/civitai/tree/HEAD/apps/event-engine/.claude/skills/clickhouse-query/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
