Clickhouse Query

Run ClickHouse queries for analytics and metrics with safety guardrails

✨ The solution you've been looking for

Verified

Tested and verified by our team

6981 Stars

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 analytics database query metrics debugging sql data-analysis

Repository

See It In Action

Interactive preview & real-world examples

Live Demo

AI Conversation Simulator

See how users interact with this skill

User Prompt

Show me the top 10 most viewed models in the last 7 days with their view counts

Skill Processing

Analyzing request...

Agent Response

A formatted table showing model IDs, names, and view counts with proper aggregation and time filtering

Quick Start (3 Steps)

Get up and running in minutes

Install

claude-code skill install clickhouse-query

claude-code skill install clickhouse-query

Config

First Trigger

@clickhouse-query help

Commands

Command	Description	Required Args
@clickhouse-query analyze-user-engagement-metrics	Query view events and user activities to understand platform usage patterns	None
@clickhouse-query debug-query-performance	Use explain plans and system tables to identify slow queries and optimize database performance	None
@clickhouse-query monitor-system-health	Query system tables across replica clusters to monitor database health and identify issues	None

Typical Use Cases

Analyze User Engagement Metrics

Query view events and user activities to understand platform usage patterns

Debug Query Performance

Use explain plans and system tables to identify slow queries and optimize database performance

Monitor System Health

Query system tables across replica clusters to monitor database health and identify issues

Overview

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:

1node .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

 1# Count rows in a table
 2node .claude/skills/clickhouse-query/query.mjs "SELECT count() FROM views"
 3
 4# Query with filters
 5node .claude/skills/clickhouse-query/query.mjs "SELECT * FROM modelEvents WHERE modelId = 123 LIMIT 10"
 6
 7# Check query execution plan
 8node .claude/skills/clickhouse-query/query.mjs --explain "SELECT * FROM views WHERE userId = 1"
 9
10# Override default 30s timeout for longer queries
11node .claude/skills/clickhouse-query/query.mjs --timeout 60 "SELECT ... (complex aggregation)"
12
13# Query from file
14node .claude/skills/clickhouse-query/query.mjs -f my-query.sql
15
16# JSON output for processing
17node .claude/skills/clickhouse-query/query.mjs --json "SELECT type, count() FROM modelEvents GROUP BY type"

Safety Features

Read-only by default: Blocks INSERT/ALTER/DROP unless --writable flag is used
30 second timeout: Prevents runaway queries (override with --timeout)
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

1-- WRONG: Only queries the node you're connected to
2SELECT * FROM system.query_log WHERE event_time > now() - INTERVAL 1 HOUR
3
4-- CORRECT: Queries all replicas in the cluster
5SELECT * FROM clusterAllReplicas(default, system.query_log)
6WHERE event_time > now() - INTERVAL 1 HOUR

Common System Table Queries

 1-- Find recent queries across all nodes
 2SELECT
 3    hostname(),
 4    event_time,
 5    query_duration_ms,
 6    formatReadableSize(memory_usage) AS memory,
 7    query
 8FROM clusterAllReplicas(default, system.query_log)
 9WHERE type = 'QueryFinish'
10    AND event_time > now() - INTERVAL 5 MINUTE
11ORDER BY event_time DESC
12LIMIT 20
13
14-- Find expensive queries by memory usage (last 24 hours)
15SELECT
16    count() as query_count,
17    user,
18    sum(memory_usage) AS total_memory,
19    normalized_query_hash
20FROM clusterAllReplicas(default, system.query_log)
21WHERE event_time > now() - INTERVAL 1 DAY
22    AND query_kind = 'Select'
23    AND type = 'QueryFinish'
24GROUP BY normalized_query_hash, user
25ORDER BY total_memory DESC
26LIMIT 10
27
28-- Search query logs by pattern
29SELECT event_time, query_id, query, type
30FROM clusterAllReplicas(default, merge('system', '^query_log*'))
31WHERE query ILIKE '%some_table%'
32    AND event_time > now() - INTERVAL 5 MINUTE
33
34-- Debug a specific query across all nodes
35SELECT hostname(), message
36FROM clusterAllReplicas(default, system.text_log)
37WHERE query_id = 'your-query-id-here'
38ORDER 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

 1-- Use count() not COUNT(*)
 2SELECT count() FROM views
 3
 4-- Date filtering with toDate()
 5SELECT * FROM views WHERE toDate(time) = today()
 6
 7-- Last 7 days
 8SELECT * FROM modelEvents WHERE time > now() - INTERVAL 7 DAY
 9
10-- Aggregations
11SELECT type, count() as cnt FROM modelEvents GROUP BY type ORDER BY cnt DESC

What Users Are Saying

Real feedback from the community

Environment Matrix

Dependencies

Node.js (for query script execution)

ClickHouse client connection

Context Window

Token Usage ~1K-3K tokens for typical queries and results

Security & Privacy

Information

Author: civitai
Updated: 2026-01-30
Category: debugging

Clickhouse Query

See It In Action

AI Conversation Simulator

Quick Start (3 Steps)

Install

Config

First Trigger

Commands

Typical Use Cases

Analyze User Engagement Metrics

Debug Query Performance

Monitor System Health

Overview

ClickHouse Query Testing

Running Queries

Options

Examples

Safety Features

When to Use –writable

Common Tables

Querying Replica Clusters

System Tables on Replica Clusters

Common System Table Queries

When to Use clusterAllReplicas()

ClickHouse SQL Tips

What Users Are Saying

Environment Matrix

Dependencies

Context Window

Security & Privacy

Information

Related Skills

Clickhouse Query

Railway Metrics

Railway Metrics