查询裁剪：主键索引、分区裁剪与数据跳过索引

裁剪三件套：
□ 主键索引：跳过不命中的 granule
□ 分区裁剪：跳过不命中的分区目录
□ 跳数索引：跳过块级不满足条件的整块

裁剪粒度：分区 → Part → granule → 行
衡量指标：read_rows、SelectedGranules 越小越成功

-- 用系统日志对比「裁剪前后」的扫描量
SELECT query, read_rows,
       ProfileEvents['SelectedGranules'] AS granules
FROM system.query_log
WHERE query_start_time > now() - INTERVAL 1 DAY
ORDER BY query_start_time DESC LIMIT 10;

稀疏索引结构：
□ 每个 granule = 8192 行，落盘为一个列块
□ 每 granule 对应索引文件里一个 mark（主键值+偏移）

原理：主键有序 → 范围条件二分定位
□ 只读中间命中的 granule，跳过两侧
□ 稀疏 = 8192 行一条，索引可全放内存

关键约束：
□ 主键依赖 ORDER BY（而非唯一约束）
□ 只能加速「匹配主键前缀」的条件

-- ORDER BY 即主键
CREATE TABLE events (
    event_time DateTime, user_id UInt64,
    event_type String, value UInt32
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(event_time)
ORDER BY (event_time, user_id);

-- event_time 是主键前缀，能命中稀疏索引
EXPLAIN indexes = 1
SELECT count() FROM events
WHERE event_time >= '2026-09-01' AND event_time < '2026-09-02';

前缀匹配规则：
□ 单列主键 (a)：where a=.. → 生效
□ 复合主键 (a,b)：where a=.. and b=.. → 生效
□ 复合主键 (a,b)：where b=.. → 失效（跳过 a）

主键选择原则：
□ 过滤最频繁的等值条件放最左
□ 时间范围放前面利于分区+裁剪
□ 主键不用加唯一性，索引仅用于裁剪

陷阱：
□ 主键过多列 → 索引行变宽，内存上升
□ 函数包裹列 → 需要物化列配合

-- 左：条件完全匹配前缀，裁剪充分
SELECT count() FROM events
WHERE event_time = '2026-09-01' AND user_id = 123;

-- 右：只按 user_id 过滤，前缀断裂，稀疏索引失效
SELECT count() FROM events WHERE user_id = 123;

-- 补救：加物化列，不打断 event_time 前缀
CREATE TABLE events_v2 (
    event_time DateTime, user_id UInt64,
    user_id_str String MATERIALIZED toString(user_id)
) ENGINE = MergeTree() ORDER BY (event_time, user_id);

分区裁剪原理：
□ 数据 → 分区表达式求值 → 目录
□ 查询时按分区键求值条件
□ 不匹配目录直接丢弃
□ 比主键索引更粗粒度、更早生效

分区键设计：
□ 时间分区用 toYYYYMM → 月度
□ 分区粒度 = 写入/合并的原子单元
□ 分区过细 → parts 膨胀 → 合并压力大

验证：
□ EXPLAIN indexes=1 的 SelectedParts
□ 命中 → SelectedParts 远小于总 part 数

-- 月度分区：where 只给一个月 → 只读一个目录
CREATE TABLE events
PARTITION BY toYYYYMM(event_time)
ORDER BY event_time;

EXPLAIN indexes = 1
SELECT count() FROM events WHERE event_time >= '2026-09-01';

-- 反例：条件不含分区键 → 所有分区都要读
EXPLAIN indexes = 1
SELECT count() FROM events WHERE user_id = 123;

跳数索引类型：
□ minmax：块内最小/最大值 → 范围条件
□ set：块内去重值集合（限低基数）→ 等值
□ bloom_filter：布隆（误判率默认 0.025）→ 等值/IN
□ ngrambf / tokenbf：子串/分词布隆 → LIKE

工作方式：对每个 granule 判断「一定不匹配？」
□ 一定不匹配 → 跳过整块
□ 可能匹配 → 读块再逐行过滤

代价：每个索引列额外写索引文件

-- 给非主键列加跳数索引
CREATE TABLE events (
    event_time DateTime, user_id UInt64,
    event_type String, status_code UInt16, message String
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(event_time)
ORDER BY (event_time, user_id)
INDEX idx_status minmax GRANULARITY 4
INDEX idx_type set(1000) GRANULARITY 4
INDEX idx_msg bloom_filter(0.025) GRANULARITY 4;

-- status 不在主键前缀，命中跳数索引
EXPLAIN indexes = 1
SELECT count() FROM events WHERE status_code = 500;

文本索引家族：
□ tokenbf_v1：按空格分词建布隆 → 整词匹配
□ ngrambf_v1(N, size, hash, seed)：按 N-gram
  → N=3 表示 3 字符滑动窗口，支持子串

原理：每个 granule 收集该块的 token/ngram 集合
□ 布隆回答「这块有没有这个词」
□ 没有 → 跳过整块；有（或误判）→ 读块过滤

适用：日志 message LIKE '%timeout%'、内容检索

注意：N 越小越灵敏但索引越大；子串短于 N 会退化

-- ngrambf：3-gram，256 字节，2 个哈希
INDEX idx_msg ngrambf_v1(3, 256, 2, 0) GRANULARITY 1;

-- tokenbf：按词匹配，适合英文分词
INDEX idx_tokens tokenbf_v1(1024, 3, 0) GRANULARITY 1;

-- 查询命中文本索引
EXPLAIN indexes = 1
SELECT count() FROM logs
WHERE message LIKE '%connection refused%';

物化跳跃关键：
□ 索引统计在写入时物化到索引文件
□ 查询时零计算，直接读统计判断

数据布局影响：
□ 值聚在一起（时间/分类排序）→ 好裁剪
□ 值均匀散布 → 每块都可能命中 → 无法跳过

改善数据布局：
□ 把高过滤字段排进 ORDER BY（天然聚合）
□ 低基数字段排进主键后缀
□ 保持全局有序写入

校验：EXPLAIN indexes=1 看索引被读、SelectedGranules 下降

-- 检查某列是否有跳过索引可用
SELECT name, type, expr
FROM system.data_skipping_indices
WHERE table = 'events';

-- 验证裁剪效果
SELECT read_rows,
       ProfileEvents['SelectedGranules'] AS selected_g
FROM system.query_log
WHERE query ILIKE '%status_code%'
ORDER BY query_start_time DESC LIMIT 5;

EXPLAIN indexes = 1 输出：
□ SelectedParts → 分区裁剪是否生效
□ SelectedGranules → 主键索引是否生效
□ SelectedMarks → 跳数索引是否生效
□ 数值越小 → 裁剪越彻底

EXPLAIN PIPELINE 输出：
□ ParallelReadingFromParts：读哪些 part
□ FilterTransform：WHERE 过滤位置

-- 单条查询的完整裁剪体检
EXPLAIN indexes = 1
SELECT count() FROM events
WHERE event_time >= '2026-09-01'
  AND event_time < '2026-09-02'
  AND status_code = 500;

-- 物理执行管道里看并行读取的来源
EXPLAIN PIPELINE
SELECT count() FROM events WHERE status_code = 500;

失效原因清单：
□ 条件不含分区键 → 分区裁剪失效
□ 条件不在主键前缀 → 稀疏索引失效
□ 过滤列没有索引 → 全扫 → 加跳过索引
□ 类型不匹配 → 隐式转换 → 索引失效
□ 函数包裹列 → 索引失效
□ 数据分布均匀 → 索引有但跳不动

排查流程：EXPLAIN indexes=1 看数字 → 对比全量 → 定位失效层 → 对症下药

-- 反例：函数包裹导致索引失效
SELECT count() FROM events
WHERE toYYYYMM(event_time) = 202609;

-- 正例：改写成范围，索引与分区裁剪都生效
SELECT count() FROM events
WHERE event_time >= '2026-09-01' AND event_time < '2026-10-01';

-- 类型不一致：UInt16 列与 String '500' 比较会隐式转换
EXPLAIN indexes = 1
SELECT count() FROM events WHERE status_code = 500;

裁剪三层与验证：
□ 分区裁剪 → SelectedParts（目录级）
□ 稀疏索引 → SelectedGranules（granule 级）
□ 跳数索引 → SelectedMarks（mark 级）

索引选择：
□ 范围条件 → minmax
□ 低基数等值 → set
□ 高基数等值/IN → bloom_filter
□ 文本 LIKE/子串 → ngrambf / tokenbf

设计口诀：
□ ORDER BY 排前缀，高频字段靠左
□ 分区键对齐查询粒度
□ 非前缀过滤列补跳数索引
□ 列裸露、类型对齐、别包函数

一句记忆：裁剪 = 先划掉不读，再读最少

-- 一张「索引体检」的标准模板
EXPLAIN indexes = 1
SELECT count() FROM events
WHERE <条件列> = <值> OR <条件列> BETWEEN .. AND ..;