clickhouse-query

ClickHouse 查询测试

使用此技能运行临时 ClickHouse 查询，用于分析、指标分析和调试。

运行查询

使用附带的查询脚本：

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

选项

标志	说明
--explain	显示查询执行计划
--writable	允许写入操作（需要用户许可）
--timeout <s>, -t	查询超时时间，单位为秒（默认值：30）
--file, -f	从文件读取查询
--json	以 JSON 格式输出结果
--quiet, -q	精简输出，仅显示结果

示例

# 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"

安全功能

1. 默认只读：除非使用 --writable 标志，否则会阻止 INSERT/ALTER/DROP
2. 30 秒超时：防止查询长时间运行（可通过 --timeout 覆盖）
3. 需要明确许可：使用 --writable 之前，必须征得用户许可

何时使用 --writable

仅在以下情况下使用 --writable 标志：

• 用户明确请求写入权限
• 需要插入测试数据
• 正在运行维护操作

重要：使用 --writable 运行之前，务必征得用户许可。

常见表

表	说明
views	页面/实体查看事件
modelEvents	模型创建/发布/更新事件
modelVersionEvents	模型版本事件，包括下载
userActivities	用户注册、登录、订阅事件
images	图片上传/删除事件
reactions	点赞/点踩事件
reports	内容举报事件
entityMetricEvents	聚合指标事件

查询副本集群

重要：生产环境使用 ClickHouse 副本集群。查询系统表（日志、指标等）时，必须使用 clusterAllReplicas() 获取所有节点的数据。

副本集群上的系统表

-- 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

常见系统表查询

-- 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

何时使用 clusterAllReplicas()

使用场景	函数
系统表（query_log、text_log 等）	clusterAllReplicas(default, system.table_name)
应用表（views、modelEvents 等）	直接查询（已分布）
搜索多个系统表	clusterAllReplicas(default, merge('system', '^pattern*'))

ClickHouse 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