ClickHouse 🏠

对数十亿行数据进行实时分析。亚秒级查询。无需索引。

设置

首次使用时，请阅读 setup.md 了解连接配置。

使用场景

用户需要OLAP分析、日志分析、时序数据或实时仪表盘。智能体负责处理模式设计、查询优化、数据摄入和集群管理。

架构

内存文件位于 ~/clickhouse/。结构请参考 memory-template.md。

~/clickhouse/
├── memory.md # 连接配置 + 查询模式
├── schemas/ # 各数据库的表定义
└── queries/ # 保存的分析查询

快速参考

核心规则

1. 始终指定引擎

sql
-- 时序数据/日志
CREATE TABLE events (
timestamp DateTime,
event_type String,
data String
) ENGINE = MergeTree()
ORDER BY (timestamp, event_type);

-- 聚合指标
CREATE TABLE daily_stats (
date Date,
metric String,
value AggregateFunction(sum, UInt64)
) ENGINE = AggregatingMergeTree()
ORDER BY (date, metric);

2. ORDER BY 就是你的索引

• - 将高基数的过滤列放在前面
• 将范围列（日期、时间戳）放在前面
• 匹配最常见的WHERE模式

sql
-- 好：先按user_id过滤，再按日期范围
ORDER BY (userid, date, eventtype)

-- 差：按user_id过滤时却把date放在前面
ORDER BY (date, userid, eventtype)

3. 使用合适的数据类型

4. 批量插入

bash

好：批量插入

差：循环逐行插入

最小批次：1,000行。最佳批次：10,000-100,000行。

5. 使用FINAL预热查询

sql
-- 可能返回重复/旧版本
SELECT * FROM users WHERE id = 123;

-- 保证返回最新版本
SELECT * FROM users FINAL WHERE id = 123;

FINAL 有性能开销。对于仪表盘，考虑使用物化视图。

6. 使用物化视图提升速度

sql
CREATE MATERIALIZED VIEW hourly_events
ENGINE = SummingMergeTree()
ORDER BY (hour, event_type)
AS SELECT
toStartOfHour(timestamp) AS hour,
event_type,
count() AS events
FROM events
GROUP BY hour, event_type;

7. 优先检查系统表

sql
-- 正在运行的查询
SELECT * FROM system.processes;

-- 最近的查询性能
SELECT query, elapsed, readrows, memoryusage
FROM system.query_log
WHERE type = QueryFinish
ORDER BY event_time DESC
LIMIT 10;

-- 表大小
SELECT database, table, formatReadableSize(total_bytes) as size
FROM system.tables
ORDER BY total_bytes DESC;

常见陷阱

• - 使用String而非LowCardinality → 状态/类型列存储空间增大10倍
• 错误的ORDER BY → 全表扫描而非索引查找
• 逐行插入 → 大量分区碎片，写入缓慢
• 缺少TTL → 表无限增长，磁盘满
• SELECT * → 读取所有列，丧失列式优势
• 到处使用Nullable → 开销 + NULL处理复杂性
• 忘记FINAL → 合并表中出现过期/重复数据

性能检查清单

在执行昂贵查询之前：

1. 1. 检查EXPLAIN：EXPLAIN SELECT ... 显示执行计划
2. 先采样：SELECT ... FROM table SAMPLE 0.01 获取1%样本
3. 限制列数：只SELECT需要的列
4. 使用PREWHERE：在读取所有列之前进行过滤
5. 检查分区：SELECT count() FROM system.parts WHERE table=X

sql
-- PREWHERE优化
SELECT userid, eventtype, data
FROM events
PREWHERE date = today()
WHERE event_type = click;

集群管理

添加TTL进行数据保留

sql
-- 删除旧数据
ALTER TABLE events
MODIFY TTL timestamp + INTERVAL 90 DAY;

-- 移动到冷存储
ALTER TABLE events
MODIFY TTL timestamp + INTERVAL 30 DAY TO VOLUME cold;

监控磁盘使用

sql
SELECT
database,
table,
formatReadableSize(sum(bytesondisk)) as disk_size,
sum(rows) as total_rows,
count() as parts
FROM system.parts
WHERE active
GROUP BY database, table
ORDER BY sum(bytesondisk) DESC;

外部端点

不联系任何外部服务。所有查询都在用户指定的ClickHouse实例上运行。

安全与隐私

本地保存的数据（经用户同意）：

• - 连接配置（主机、端口、数据库）保存在 ~/clickhouse/memory.md
• 查询模式和模式文档
• 认证方式偏好（密码 vs 证书）

重要提示： 如果您提供数据库密码，它们将以明文形式存储在 ~/clickhouse/ 中。建议使用环境变量或由clickhouse-client管理的连接配置。

此技能不会：

• - 在没有用户明确配置的情况下连接到任何ClickHouse
• 将数据发送到外部服务
• 未经询问自动收集或存储凭据

相关技能