clickhouse-performance-tuning

用途：诊断并修复 ClickHouse 查询性能问题，采用先测量、再应用最高收益改动、后复测确认的自上而下流程。

主要能力：

1. 慢查询诊断——按 query_duration_ms 对近 24 小时 system.query_log 排序，用 EXPLAIN PLAN / EXPLAIN PIPELINE 检查可疑查询。
2. ORDER BY 键优化——核心手段；按 ORDER BY 前缀过滤可跳过整个 granule，键不匹配会导致全表扫描。
3. 数据跳过索引——高基数列用 bloom_filter，低基数列用 set，非键列范围过滤用 minmax。
4. 投影（Projections）——查询形状匹配时 ClickHouse 自动选用预聚合结果。
5. 服务器设置——max_threads、外部排序/分组溢出、async_insert 等，可按查询或会话设置。
6. 物化视图——写入时预聚合到 AggregatingMergeTree，加快看板读取。
7. 查询写法——PREWHERE、LIMIT BY，避免 FINAL。

使用方式：需要存在含数据的 ClickHouse 表，并能访问 system.query_log 与 system.parts。完整 SQL 见 references/implementation.md，示例见 references/examples.md。首次排查慢查询可执行：SELECT event_time, query_duration_ms, read_rows, read_bytes, substring(query, 1, 300) AS query_preview FROM system.query_log WHERE type = 'QueryFinish' AND event_time >= now() - INTERVAL 24 HOUR AND query_duration_ms > 1000 ORDER BY query_duration_ms DESC LIMIT 20; 调优后复测：SELECT query_duration_ms, read_rows, formatReadableSize(read_bytes) AS read_size, formatReadableSize(memory_usage) AS memory FROM system.query_log WHERE query_id = currentQueryId() AND type = 'QueryFinish';

适用场景：查询变慢、全表扫描、GROUP BY 慢、内存超限（Error 241）、合并积压（Parts > 300）等。

限制：需具备系统表访问权限；不替代建表与写入流程（可参考 clickhouse-core-workflow-a）；成本优化另见 clickhouse-cost-tuning。