【列存引擎内核】Merge 与 Mutation

Insert 只 追加 Part；后台 merge 把多个小 Part 归并为更大 Part——列存的「心脏手术」，类比 LSM Compaction。Mutation 则异步重写 Part 实现 UPDATE/DELETE，堆积会拖垮集群。

一、为何需要 Merge

flowchart LR
  P1[Part 小] --> M[Merge]
  P2[Part 小] --> M
  M --> P3[Part 大]

二、Merge 触发与 selector

MergeTreeBackgroundExecutor 调度任务；selector 根据 Part 大小、level、分区挑选可 merge 组合（SimpleMergeSelector 等）。

Settings：max_bytes_to_merge_at_max_space_in_pool、merge_max_block_size、number_of_free_entries_in_pool_to_execute_merge。

观察（本机）：

SELECT * FROM system.merges;
SELECT database, table, sum(1) FROM system.parts WHERE active GROUP BY database, table;

不伪造 system.merges 行。

三、Merge 做什么

对同分区、排序键兼容的 Part 多路归并（与 LSM 归并相似）：

• 输出新 Part，旧 Part Outdated
• 重新压缩、可应用新 CODEC
• Replacing/Summing 等引擎在归并时应用语义

源码：MergeTreeDataMergerMutator.cpp。

四、ReplacingMergeTree

CREATE TABLE r (
  id UInt64,
  v String,
  ver UInt64
) ENGINE = ReplacingMergeTree(ver)
ORDER BY id;

Merge 同 id 保留 ver 最大行。查询可能见重复，除非 FINAL（有性能成本）。

五、CollapsingMergeTree

Sign Int8：+1 插入，-1 撤销；merge 折叠。适合变更流。

六、Mutation

ALTER TABLE UPDATE v = ... WHERE ... → 队列 → 读旧 Part 写新 Part。

危害：

• 与 merge 争线程
• 磁盘写放大
• system.mutations 堆积

生产尽量避免大范围 mutation；用 Replacing 或重建表替代。

stateDiagram-v2
  [*] --> Queued: ALTER UPDATE
  Queued --> Executing: background
  Executing --> Done: 新 Part 替换
  Executing --> Failed: 磁盘/超时

七、TTL

TTL 规则在 merge 时删除/移动过期 granule，依赖 merge 运行。

八、小结

Merge = 归并 Part、控制读放大、实现引擎语义；Mutation = 重写 Part、应慎用。

上一篇：查询读取路径

下一篇：索引与跳数索引

附录、扩展阅读与工程注记

Merge selector

SimpleMergeSelector / TTLMergeSelector 等根据 Part 大小、年龄、分区挑选 merge 任务；目标减少 Part 数且控制写放大。

ReplacingMergeTree

replace 版本列默认 is_deleted 或显式 version；merge 同排序键保留 version 最大。查询仍可能见重复行，除非 FINAL 或应用层去重。

CollapsingMergeTree

Sign 列 +1/-1 表示插入与撤销；merge 折叠成 net 行。适合变更流而非物理 DELETE。

Mutation 路径

ALTER TABLE UPDATE/DELETE → MutationCommands 队列 → 后台读 Part 重写新 Part → 原子替换。堆积时 system.mutations 可见；与 merge 争用 BackgroundSchedulePool。 ### index_granularity

两个 Mark 之间最大行数；影响稀疏索引粒度与单次读 granule 行数上限。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：8192。

index_granularity_bytes

自适应 granule：限制 granule 预估字节大小，宽行表避免单 granule 过大。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：10485760 (10 MiB)。

enable_mixed_granularity_parts

是否启用 index_granularity_bytes 与 index_granularity 混合控制。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：1。

min_bytes_for_wide_part

Part 体积超过阈值时使用 Wide 布局（列独立文件）。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：10485760。

min_rows_for_wide_part

行数超过阈值转 Wide。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：0。

parts_to_throw_insert

活跃 Part 数超过阈值拒绝 insert。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：3000。

parts_to_delay_insert

超过阈值开始延迟 insert。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：1000。

merge_max_block_size

单次 merge 输出块大小上限。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：8192。

max_bytes_to_merge_at_max_space_in_pool

merge 池有空闲时单任务最大字节。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：161061273600。

number_of_free_entries_in_pool_to_execute_mutation

mutation 与 merge 共享池时的调度参数。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：见文档。

compress_marks

是否压缩 Mark 文件。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：1。

compress_primary_key

是否压缩 primary.idx 落盘（内存仍解压使用）。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：1。

S3 磁盘与冷存

S3 作 disk 时 Part 对象化；读延迟高于本地 SSD。merge 仍发生，网络带宽成为瓶颈。

Replicated 与 S3

零拷贝 replication 到 S3 磁盘配置见官方；副本 fetch 可走对象存储。与第 8 篇 queue 类型相关。

数据倾斜与 PARTITION BY

单分区过大 merge 慢；过多分区 metadata 膨胀。按天/租户合理切分；避免 PARTITION BY rand()。

PRIMARY KEY 长度

PK 列过多/long String 增大 primary.idx 与内存。仅前缀必要列；其余放 ORDER BY 后缀或跳数索引。

跳数索引 GRANULARITY 选择

GRANULARITY 过大索引粗；过小索引体积接近逐 granule。默认 1–4 需按列选择性实验（第 7 篇）。

bloom_filter 假阳性

Bloom 仅跳过 granule；假阳性多读 granule 仍正确。无 false negative。

minmax 索引失效场景

列值在 granule 内分布宽但谓词窄，minmax 无法跳过——需更细 ORDER BY 或 bloom。

set 索引大小上限

set 索引 granule 内 distinct 超上限则退化；高基数列不适用 set。

向量索引（边界）

向量相似搜索非 MergeTree 经典跳数索引范畴；24.x 实验特性不在此系列承诺。

Pipeline EXPLAIN 用法

EXPLAIN PIPELINE 展示 Processor 图；与 EXPLAIN indexes=1 互补。本环境无实例不贴输出。

QueryPlan 阶段

Analyzer 产出 QueryPlan，再转 Pipeline。PREWHERE 下推在此阶段决定；SQL 写法影响是否自动 PREWHERE。

Constant 折叠与 primary key

常量谓词与 PK 范围交集在优化期计算；参数化查询仍受益 prepared 边界。

FINAL 与 dedup

ReplacingMergeTree 的 FINAL 在查询期归并；替代方案 MV 去重或应用层 argMax。

Lightweight DELETE（版本边界）

较新版本 lightweight delete 标记删除 granule；与 mutation 路径不同。以 24.x 文档为准是否 GA。

Transaction 语义边界

单 insert block 原子；跨 Part 无 MVCC 快照隔离。勿与 PG MVCC 类比。

chDB / clickhouse-local

嵌入式 clickhouse-local 适合 Part 格式实验（第 2 篇）；与 server 共用 MergeTree 代码路径。

版本升级与 Part 兼容

大版本升级前查 release notes Part 格式变更；通常向后读旧 Part，merge 逐步重写。

checksum 算法

checksums.txt 使用 CityHash128 等；损坏 Part 拒绝加载保护下游。

Serialization 与类型变更

ALTER MODIFY COLUMN 可能触发 mutation 重写；类型不兼容需中间列。

Dictionary 与外部维表

字典非 MergeTree Part；JOIN 字典与 MergeTree scan 是不同 IO 路径。

Global IN 代价预告

Distributed 上 GLOBAL IN 广播维表（第 9 篇）；本地 MergeTree 无此问题。

测试数据 hits 样本

官方 hits 数据集适合验证读路径；下载与导入步骤见 clickhouse.com/docs getting started。

benchmark 伦理

引用外部 benchmark 必须标注来源；自测需 3 轮中位数与环境表（WRITING_GUIDE）。

源码阅读顺序建议

MergeTree：StorageMergeTree → IMergeTreeDataPart → MergeTreeReaderWide → MergeTreeDataMergerMutator。执行：PipelineExecutor → IProcessor。

社区与 LTS

24.x LTS 安全/backport 周期见官网；生产锚定 LTS 而非 latest。

system.parts 字段解读

运维读 Part 状态时常用列：database、table、name（目录名）、part_type（Wide/Compact）、rows、bytes_on_disk、bytes_on_disk_uncompressed、primary_key_bytes_in_memory、marks_bytes_on_disk、level、data_version、is_frozen。active=0 表示已被 merge 替换但未物理删除。与 LSM SST 层数 类似，应监控每表 active part 数趋势。

system.merges 与 merge 进度

system.merges 展示当前运行中的 merge：database、table、elapsed、progress（0–1）、num_parts、result_part_name、total_size_bytes_uncompressed。长时间 progress 不动可能磁盘 IO 饱和或单 Part 过大。merge_max_block_size 影响单次归并行数。

system.query_log 读路径指标

启用 query_log 后，read_rows、read_bytes、result_rows 对比可验证索引剪枝是否生效。PREWHERE 优化通常降低 read_bytes 而 read_rows 仍含 granule 内过滤前行数。本系列不在此环境给出样本数值。

MergeTreeWriteSettings 与 insert

除表级 merge_tree settings 外，insert 受 max_insert_block_size、min_insert_block_size_rows、async_insert（24.x 异步 insert 特性以文档为准）影响。小 block 直接对应小 Part——平台侧应强制 batch 或 Buffer 引擎。

StoragePolicy 与多磁盘

TTL MOVE 与 storage_policy 可将 Part 移至慢盘/对象存储。merge 与 fetch 路径需保证目标卷有足够空间；system.disks 与 system.storage_policies 描述卷与策略。

Projection 与读优化（边界）

24.x 支持 projection 预聚合/排序副本。属于高级 DDL，本系列主路径不展开；知晓其存在可避免与跳数索引职责混淆——projection 是额外 Part 子集，非跳数索引。

Sample By 与近似查询

SAMPLE BY 与 SAMPLE 子句依赖排序键哈希；与主键剪枝独立。日志采样分析常用，但不替代正确 ORDER BY 设计。

Nullable 与 Default 列存储

Nullable 列额外 .null.bin（视版本/序列化而定）；默认值列可能仅 .default 文件。读路径需合并 null map；宽表 Nullable 多会增加文件数。

UUID / IPv6 类型

固定长度类型序列化紧凑；仍受 granule 与 codec 影响。随机 UUID 作 ORDER BY 前缀会导致稀疏索引几乎无效——工程上避免。

DateTime64 与时区

DateTime64 排序键常用 DoubleDelta；插入时区 session_timezone 与显示无关存储。跨时区报表在 SQL 层转换，不在 Part 内改。

Enum 与 LowCardinality

Enum 存整数标签；LowCardinality 字典适合低基数。高基数 String 强行 LowCardinality 字典膨胀，压缩与查询均变差。

Nested 与 JSON 类型

Nested 在磁盘展开为多个子列 Array；JSON 类型（若启用）路径提取有独立序列化。宽 Nested 增加 Part 文件数，merge 成本上升。

Materialized Column

物化列随 insert 计算持久化，占独立 .bin。适合重复表达式，但增加写放大与存储；与 MV 目标表不同。

TTL DELETE vs DROP PARTITION

TTL DELETE 在 merge 时删 granule；ALTER DROP PARTITION 整分区移除 Part。后者运维更干净；前者适合行级过期。

Freeze / UNFREEZE 备份

FREEZE 硬链 Part 到 shadow/ 目录做一致性快照；与副本 fetch 互补。恢复需 ATTACH PART 流程，见官方 Backup 文档。

detach / attach part

手动 DETACH PART 将目录移入 detached/，不参与查询与 merge。排障错误 Part 或迁移数据时使用；attach 前需校验 checksums。

并发 insert 与 block 边界

多客户端 insert 各自形成 Part；无跨客户端单 block 合并。高并发小 insert 是 parts 爆炸主因——应用侧 batch 或 async_insert 缓冲。

OPTIMIZE TABLE FINAL

强制 merge 至单 Part（分区内）并应用 Replacing 等语义。生产大表慎用：IO 峰值、长时间锁表语义以文档为准。更适合维护窗口。

system.parts_columns

逐列 data_compressed_bytes、data_uncompressed_bytes、compression_codec——压缩实验应用此表而非猜。见第 3 篇 benchmark 框架。

Mark Cache 与 Primary Index Cache

频繁查询受益 mark_cache、primary_index_cache（配置与 metric 见文档）。冷查询首次读盘仍取决于 Mark/PK 大小。

ReadInOrder 优化

若查询 ORDER BY 与表排序键一致且无大幅改写，优化器可走 ReadInOrder 减少全量排序内存。与 merge 物理排序强相关。

分布式 DDL 边界

ReplicatedMergeTree 上 ON CLUSTER DDL 通过 distributed DDL queue；与 Part 级复制不同层。第 8 篇聚焦 Part 同步。

Keeper 与 ZooKeeper 差异

24.x 推荐 Keeper（Raft）；ZK 路径约定兼容。新集群优先 Keeper，减少 JVM 依赖与 tail latency。

Quorum insert

insert_quorum 要求 N 副本确认 Part；与 async insert 策略互斥需谨慎。金融场景可能启用，吞吐下降。

Recovery 线程

副本 system.replication_queue 中 GET_PART 失败会重试；Broken Part 需人工 SYSTEM DROP REPLICA / 重新同步。监控 last_exception。

与 PG 外表对比

PostgreSQL 作源时，MaterializedPostgreSQL 或 CDC 工具写入 MergeTree；PG 仍行存 MVCC，CH 侧 append Part。一致性窗口由复制协议决定。

与 observability ingest

日志写入 CH 常用 Kafka 引擎 + MV（第 10 篇规划）。ingest 侧 batch 大小直接决定 Part 尺寸——与 可观测性系列 管道设计联动。

CPU vs IO bound 判定

高压缩率 + 宽 granule 可能 CPU bound（解压）；NVMe 上低压缩可能 IO bound。system.events 中 OSIOWait* vs UserTime 辅助判断，需本机 profile。

max_threads 与 cores

max_threads 默认与 CPU 核相关；过大线程增加 Part 并行读开销与内存。HTAP 混部应限制 CH 查询线程池。

内存跟踪

system.metrics 的 MemoryTracking、MergesMutationsMemoryTracking；OOM 前常见 merge 与 big aggregation 同抢内存。

Part 命名与 mutation

mutation 产生 xxx_mutyyy 中间 Part；完成后旧 Part outdated。system.mutations 的 parts_to_do 反映剩余工作量。

Collapsing 与 VersionedCollapsing

VersionedCollapsing 用 (Sign, Version) 对消；比纯 Collapsing 更适合乱序变更。merge 前查询仍需应用层理解 sign。

SummingMergeTree 列和

仅数值列默认 sum；非键列需显式指定 summing 列。非 sum 列取任意值（merge 确定性规则见文档）。

AggregatingMergeTree 状态

存 AggregateFunction 状态；查询需 -Merge 组合器。适合预聚合管道，schema 设计门槛高。

GraphiteMergeTree rollup

按时间精度 rollup 规则在 config 定义；监控迁移场景专用。与普通 Summing 不同。

S3 磁盘与冷存

S3 作 disk 时 Part 对象化；读延迟高于本地 SSD。merge 仍发生，网络带宽成为瓶颈。

Replicated 与 S3

零拷贝 replication 到 S3 磁盘配置见官方；副本 fetch 可走对象存储。与第 8 篇 queue 类型相关。

数据倾斜与 PARTITION BY

单分区过大 merge 慢；过多分区 metadata 膨胀。按天/租户合理切分；避免 PARTITION BY rand()。

PRIMARY KEY 长度

PK 列过多/long String 增大 primary.idx 与内存。仅前缀必要列；其余放 ORDER BY 后缀或跳数索引。

跳数索引 GRANULARITY 选择

GRANULARITY 过大索引粗；过小索引体积接近逐 granule。默认 1–4 需按列选择性实验（第 7 篇）。

bloom_filter 假阳性

Bloom 仅跳过 granule；假阳性多读 granule 仍正确。无 false negative。

minmax 索引失效场景

列值在 granule 内分布宽但谓词窄，minmax 无法跳过——需更细 ORDER BY 或 bloom。

set 索引大小上限

set 索引 granule 内 distinct 超上限则退化；高基数列不适用 set。

向量索引（边界）

向量相似搜索非 MergeTree 经典跳数索引范畴；24.x 实验特性不在此系列承诺。

Pipeline EXPLAIN 用法

EXPLAIN PIPELINE 展示 Processor 图；与 EXPLAIN indexes=1 互补。本环境无实例不贴输出。

QueryPlan 阶段

Analyzer 产出 QueryPlan，再转 Pipeline。PREWHERE 下推在此阶段决定；SQL 写法影响是否自动 PREWHERE。

Constant 折叠与 primary key

常量谓词与 PK 范围交集在优化期计算；参数化查询仍受益 prepared 边界。

FINAL 与 dedup

ReplacingMergeTree 的 FINAL 在查询期归并；替代方案 MV 去重或应用层 argMax。

Lightweight DELETE（版本边界）

较新版本 lightweight delete 标记删除 granule；与 mutation 路径不同。以 24.x 文档为准是否 GA。

Transaction 语义边界

单 insert block 原子；跨 Part 无 MVCC 快照隔离。勿与 PG MVCC 类比。

chDB / clickhouse-local

嵌入式 clickhouse-local 适合 Part 格式实验（第 2 篇）；与 server 共用 MergeTree 代码路径。

版本升级与 Part 兼容

大版本升级前查 release notes Part 格式变更；通常向后读旧 Part，merge 逐步重写。

checksum 算法

checksums.txt 使用 CityHash128 等；损坏 Part 拒绝加载保护下游。

Serialization 与类型变更

ALTER MODIFY COLUMN 可能触发 mutation 重写；类型不兼容需中间列。

Dictionary 与外部维表

字典非 MergeTree Part；JOIN 字典与 MergeTree scan 是不同 IO 路径。

Global IN 代价预告

Distributed 上 GLOBAL IN 广播维表（第 9 篇）；本地 MergeTree 无此问题。

测试数据 hits 样本

官方 hits 数据集适合验证读路径；下载与导入步骤见 clickhouse.com/docs getting started。

benchmark 伦理

引用外部 benchmark 必须标注来源；自测需 3 轮中位数与环境表（WRITING_GUIDE）。

源码阅读顺序建议

MergeTree：StorageMergeTree → IMergeTreeDataPart → MergeTreeReaderWide → MergeTreeDataMergerMutator。执行：PipelineExecutor → IProcessor。

社区与 LTS

24.x LTS 安全/backport 周期见官网；生产锚定 LTS 而非 latest。

system.parts 字段解读

运维读 Part 状态时常用列：database、table、name（目录名）、part_type（Wide/Compact）、rows、bytes_on_disk、bytes_on_disk_uncompressed、primary_key_bytes_in_memory、marks_bytes_on_disk、level、data_version、is_frozen。active=0 表示已被 merge 替换但未物理删除。与 LSM SST 层数 类似，应监控每表 active part 数趋势。

system.merges 与 merge 进度

system.merges 展示当前运行中的 merge：database、table、elapsed、progress（0–1）、num_parts、result_part_name、total_size_bytes_uncompressed。长时间 progress 不动可能磁盘 IO 饱和或单 Part 过大。merge_max_block_size 影响单次归并行数。

system.query_log 读路径指标

启用 query_log 后，read_rows、read_bytes、result_rows 对比可验证索引剪枝是否生效。PREWHERE 优化通常降低 read_bytes 而 read_rows 仍含 granule 内过滤前行数。本系列不在此环境给出样本数值。

参考资料

1. ClickHouse Documentation, ReplacingMergeTree, CollapsingMergeTree, Mutations
2. ClickHouse Source, MergeTreeDataMergerMutator.cpp, MergeTreeBackgroundExecutor.cpp
3. LSM 系列, Compaction

Merge selector

SimpleMergeSelector / TTLMergeSelector 等根据 Part 大小、年龄、分区挑选 merge 任务；目标减少 Part 数且控制写放大。

ReplacingMergeTree

replace 版本列默认 is_deleted 或显式 version；merge 同排序键保留 version 最大。查询仍可能见重复行，除非 FINAL 或应用层去重。

CollapsingMergeTree

Sign 列 +1/-1 表示插入与撤销；merge 折叠成 net 行。适合变更流而非物理 DELETE。

Mutation 路径

ALTER TABLE UPDATE/DELETE → MutationCommands 队列 → 后台读 Part 重写新 Part → 原子替换。堆积时 system.mutations 可见；与 merge 争用 BackgroundSchedulePool。 ### index_granularity

两个 Mark 之间最大行数；影响稀疏索引粒度与单次读 granule 行数上限。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：8192。

index_granularity_bytes

自适应 granule：限制 granule 预估字节大小，宽行表避免单 granule 过大。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：10485760 (10 MiB)。

enable_mixed_granularity_parts

是否启用 index_granularity_bytes 与 index_granularity 混合控制。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：1。

min_bytes_for_wide_part

Part 体积超过阈值时使用 Wide 布局（列独立文件）。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：10485760。

min_rows_for_wide_part

行数超过阈值转 Wide。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：0。

parts_to_throw_insert

活跃 Part 数超过阈值拒绝 insert。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：3000。

parts_to_delay_insert

超过阈值开始延迟 insert。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：1000。

merge_max_block_size

单次 merge 输出块大小上限。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：8192。

max_bytes_to_merge_at_max_space_in_pool

merge 池有空闲时单任务最大字节。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：161061273600。

number_of_free_entries_in_pool_to_execute_mutation

mutation 与 merge 共享池时的调度参数。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：见文档。

compress_marks

是否压缩 Mark 文件。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：1。

compress_primary_key

是否压缩 primary.idx 落盘（内存仍解压使用）。

官方文档默认值（24.x，以实例 system.merge_tree_settings 为准）：1。