Clickhouse System Queries

If you're running ClickHouse in production, you're already digging through system.query_log to find slow queries or diagnose cluster issues. This skill wraps that workflow with table-specific references and smart routing between search_query_log for lookups and execute_sql for time-bucketed aggregations. It enforces time bounds by default, inherits conversation context for date ranges, and handles the ProfileEvents map-versus-flattened-column mess so you don't have to remember which schema you're on. Right now it only covers system.query_log, but the pattern is clean enough that adding system.metrics or system.replicas would be straightforward. A solid operational companion if ClickHouse monitoring is part of your daily routine.

GitHub stars: 320
last updated: May 14, 2026

View on GitHub

Install

$ npx -y skills add frankchen021/datastoria --skill clickhouse-system-queries --agent claude-code

Installs into .claude/skills of the current project.

Files

ClickHouse System Queries Skill

Use this skill when the user asks for operational inspection on ClickHouse system.* tables.

Current table coverage:

system.query_log via references/system-query-log.md

Relationship to sql-expert:

sql-expert handles general SQL generation and user/business tables.
This skill handles system-table operational patterns and routing to table-specific references.

System Metrics and ProfileEvents

Confirm column shape from schema/reference before writing predicates.
If the user named an exact metric, pass it in the columns list via explore_schema instead of loading the full table schema.
If ProfileEvents is a Map, access entries as ProfileEvents['Name']. If flattened, use ProfileEvent_Name.

Example — map vs flattened access:

-- Map access
SELECT ProfileEvents['DistributedConnectionFailTry'] AS fails
FROM system.query_log WHERE event_date = today();

-- Flattened column access
SELECT ProfileEvent_DistributedConnectionFailTry AS fails
FROM system.query_log WHERE event_date = today();