ClickHouse v21.1.7.1-stable 补丁版本深度解析:七个关键 Bug 修复的源码级解读

原创2026-09-09 20:37:451,640 阅读
文章标签:数据库列式数据库OLAP大数据分布式数据库实时分析数据仓库数据分析SQL

ClickHouse v21.1.7.1-stable 补丁版本深度解析:七个关键 Bug 修复的源码级解读

导读

本文围绕 ClickHouse 补丁分支 v21.1.7.1-stable(相对 v21.1.6.13-stable)集中合入的 7 项 Bug 修复展开,覆盖 Replicated(*)MergeTree 引擎参数默认值、Tuple→Map 类型转换、mutation 引擎约束、EXPLAIN ... UNION 崩溃、ZooKeeper 会话管理、ALTER MODIFY COLUMN 联动刷新以及 LowCardinality 列插入等高频痛点。读者将了解每条修复的触发场景、影响范围,以及当前仓库源码中的实现依据,从而在升级评估与日常排障中快速定位问题。


一、修复总览

本次补丁版本的全部修复均属于 Bug Fix 类别,统一标注为 "Backported in"(即从主分支向后移植到稳定分支)。下表给出完整清单:

序号 修复主题 关联 Issue / PR 主要影响面
1 default_replica_path / default_replica_name 默认值在部分参数指定场景下失效 #21060 复制表引擎参数解析
2 CAST Tuple 转 Map 时出现错误 #21029 / #21120 类型转换执行路径
3 mutation 仅允许在支持的引擎上执行 #21168 / #21183 ALTER ... UPDATE/DELETE 约束
4 EXPLAIN 含 UNION 查询时崩溃 #20876、#21170 / #21246 查询分析器
5 ZooKeeper 冗余重连与双会话问题 #14678 / #21264 复制表与 Keeper 交互
6 ALTER MODIFY COLUMN 未能联动更新分区键、跳数索引、TTL #13675 / #21334 ALTER 命令元数据刷新
7 向含 LowCardinality 列的表以 Values 格式插入报 Bad cast #21140 / #21357 插入管线与列存储

下文按引擎参数、类型转换、DDL/DML、查询分析、分布式协调、列存储六条主线逐一解读。


二、修复一:Replicated(*)MergeTree 引擎参数的默认值失效

2.1 问题现象

创建复制表时,若引擎在 ZooKeeper 路径与副本名之外还需要指定其他参数(例如 ReplicatedSummingMergeTree 的 summable 列清单、ReplicatedReplacingMergeTree 的版本列等),此前版本中 default_replica_path 与 default_replica_name 两个服务端默认值可能不被采用,导致建表行为与预期不符。

2.2 源码依据

在 src/Storages/MergeTree/registerStorageMergeTree.cpp 中,extractZooKeeperPathAndReplicaNameFromEngineArgs 负责从引擎参数中解析 ZooKeeper 路径与副本名:

  • 当引擎参数前两个参数是合法字符串字面量时,直接采用(对应 has_valid_arguments 分支);
  • 当采用扩展存储定义语法(新语法)且参数未给出时,代码会先把引擎参数清空并插入两个空的 ASTLiteral,再以服务端配置的默认值展开宏,随后将 engine_args 重新组装回去:
/// Modify query, so default values will be written to metadata
ASTs old_args;
std::swap(engine_args, old_args);
auto path_arg = make_intrusive<ASTLiteral>("");
auto name_arg = make_intrusive<ASTLiteral>("");
...
auto res = expand_macro(ast_zk_path, ast_replica_name,
                        server_settings[ServerSetting::default_replica_path],
                        server_settings[ServerSetting::default_replica_name]);
engine_args.emplace_back(std::move(path_arg));
engine_args.emplace_back(std::move(name_arg));

expand_macro 内部会调用 TableZnodeInfo::resolve,执行 {database}、{table}、{uuid}、{shard}、{replica} 等宏的两阶段展开(第一段展开写入 metadata 的路径,第二段展开实际运行路径),并把展开结果回写到 AST 参数中。若"除路径和副本名外还需指定其他引擎参数"这一场景下的参数计数与默认值填充逻辑存在偏差,就会触发本 Bug——具体表现为默认值没有被正确应用。该修复同时保证了默认值会被写入表元数据,使 ATTACH 与跨副本元数据拷贝行为一致。

2.3 配置默认值

两个服务端配置项的默认值定义在 src/Core/ServerSettings.cpp:

<!-- The path to the table in ZooKeeper -->
<default_replica_path>/clickhouse/tables/{uuid}/{shard}</default_replica_path>

<!-- The replica name in ZooKeeper -->
<default_replica_name>{replica}</default_replica_name>

在实际建表时可省略前两个参数,例如:

CREATE TABLE events ON CLUSTER cluster
(
    event_date Date,
    event_type String,
    value UInt64
)
ENGINE = ReplicatedSummingMergeTree('', '', event_date, (event_date, event_type), 8192, (value))
ORDER BY (event_date, event_type);

{uuid} 宏要求使用 ON CLUSTER 查询或显式 UUID(ATTACH 场景),这一点在 TableZnodeInfo::resolve 中以 allow_uuid_macro 变量做了约束(src/Storages/TableZnodeInfo.cpp)。


三、修复二:CAST Tuple 转 Map 的类型转换错误

3.1 问题现象

执行 CAST(tuple_expr AS Map(...)) 类查询时可能抛出类型转换相关错误(原 Issue #21029),属于类型转换执行路径上的缺陷。

3.2 源码依据

ClickHouse 的类型转换入口集中在 src/Functions/FunctionsConversion.h 与 src/Functions/FunctionsConversion.cpp 中。CAST 会先构造目标类型的 IDataType,再通过 executeCast 系列函数执行转换;Tuple→Map 这类结构化转换需要同时处理嵌套类型推导与逐元素值转换,若内部某个嵌套分支对 Tuple 元素个数、键值类型组合处理不当,就会出现运行时异常。本修复校准了该转换路径,保证 CAST((key, value) AS Map(...)) 形式的表达式在 SELECT 与写入场景下均能正确执行。

作为排障参考,Map 类型相关的构造与访问函数(map()、mapKeys、mapValues 等)定义在 src/Functions 目录下的 Map 相关实现中,实际使用中建议优先用显式 CAST 或 map 构造函数,避免依赖隐式 Tuple→Map 转换的边界行为。


四、修复三:mutation 仅允许在支持的引擎上执行

4.1 问题现象

此前对不支持 mutation 的表引擎执行 ALTER TABLE ... UPDATE/DELETE(或 ALTER ... DELETE WHERE)时,报错信息不够清晰,甚至可能走到未定义路径。修复后,mutation 被明确限制在支持它的引擎集合内:MergeTree 家族、Memory、MaterializedView,其他引擎会得到更明确的报错。

4.2 源码依据

在 src/Storages/IStorage.cpp 中,IStorage::supportsMutation() 的基类默认实现直接抛出明确错误:

throw Exception(ErrorCodes::NOT_IMPLEMENTED, "Table engine {} doesn't support mutations", getName());

这意味着每个存储引擎必须显式覆写 supportsMutation() 才能接受 mutation 命令。仓库中可以看到各引擎的差异化实现,例如:

本次修复统一了校验入口,让不支持 mutation 的引擎(如部分非 MergeTree 系引擎)在 DDL 阶段即被拦截,而不是在执行阶段暴露晦涩错误。对于运维而言,遇到 Table engine X doesn't support mutations 时应优先考虑改写为重建表 + 重放数据的方式,或改用支持该能力的引擎(如 MergeTree 家族)。


五、修复四:EXPLAIN 含 UNION 查询时崩溃

5.1 问题现象

对包含 UNION 的查询执行 EXPLAIN(例如 EXPLAIN AST、EXPLAIN PIPELINE、EXPLAIN PLAN 等)时可能发生服务端崩溃,涉及 Issue #20876、#21170。

5.2 源码依据

EXPLAIN 的执行入口在 src/Interpreters/InterpreterExplainQuery.cpp,其通过 executeQuery 相关的查询分析流程(src/Interpreters/executeQuery.cpp)对子查询做分析。含 UNION 的查询会被拆分为多个 SELECT 分支后合并,当 EXPLAIN 对合并后的查询结构做递归遍历时,若对 UNION 产生的中间查询节点缺少空指针或类型判空保护,就会触发崩溃。本修复在对应的遍历路径上补齐了保护逻辑,使 EXPLAIN 对含 UNION 的查询能正常输出分析结果。

补充说明:升级后如需验证,可对形如 EXPLAIN SELECT 1 UNION ALL SELECT 2 的语句做回归测试,确认不再崩溃且返回各分支的计划信息。


六、修复五:ZooKeeper 冗余重连与双活动会话

6.1 问题现象

单个 clickhouse-server 实例此前可能出现对 ZooKeeper 的冗余重连,极端情况下甚至为同一实例建立两个活动会话。该问题由更早的改动(#14678)引入,会破坏复制表基于会话的协调逻辑,导致 ReplicatedMergeTree 队列处理异常。

6.2 影响与定位

复制表(Replicated*MergeTree)依赖 ZooKeeper/Keeper 上的会话与临时节点(如 /replicas/<replica_name> 下的活跃标记)做协调。两个活动会话意味着同一副本可能同时持有两套临时节点,使其他副本的 Leader 选举、队列拉取、GET_PART 等操作产生歧义。本次修复收紧了会话复用逻辑,保证单实例始终只维护一个活动 ZooKeeper 会话,并避免不必要的重复建连。

ZooKeeper 客户端封装位于 src/Common/ZooKeeper(含 ZooKeeperCommon.h、ZooKeeperRetries.h 等),连接参数(zookeeper.session_timeout_ms、zookeeper.session_timeout_ms 与重试退避相关设置)在服务端配置中可调。出现异常重连时可结合服务端日志中的 Session established/Session expired 记录判断是否由网络抖动或会话超时引发。


七、修复六:ALTER MODIFY COLUMN 未联动更新分区键、跳数索引与 TTL

7.1 问题现象

执行 ALTER TABLE ... MODIFY COLUMN ... 修改列类型或默认值后,若该列同时参与分区键(PARTITION BY)、跳数索引(INDEX ... TYPE)、TTL 表达式,这些附属元数据此前不会被同步刷新(Issue #13675),导致后续查询使用过期定义。

7.2 源码依据

在 src/Interpreters/InterpreterAlterQuery.cpp 中,MODIFY_COLUMN 被归类为需要 ALTER_MODIFY_COLUMN 权限的变更命令:

case ASTAlterCommand::MODIFY_COLUMN:
    required_access.emplace_back(AccessType::ALTER_MODIFY_COLUMN, database, table, column_name_from_col_decl());

本次修复保证在修改列后,重新解析并持久化与之相关的 partition key、skip indices、TTL 等表达式元数据,使列定义变更在整张表的元数据体系中保持一致。升级后建议在发布流程中加入回归用例:对同时出现在 PARTITION BY / INDEX / TTL 中的列执行 MODIFY COLUMN,随后 DESCRIBE 与实际查询验证。


八、修复七:向 LowCardinality 列以 Values 格式插入报 Bad cast

8.1 问题现象

使用 INSERT INTO t FORMAT Values (...) 向含 LowCardinality(...) 列的表写入数据时,可能抛出 Bad cast from type ... to DB::ColumnLowCardinality(Issue #21140)。这类错误通常意味着插入路径中某一环节把列当成了全列(Full Column)处理,而实际列是字典编码的 ColumnLowCardinality。

8.2 源码依据

ColumnLowCardinality 的实现位于 src/Columns/ColumnLowCardinality.h,其数据由 字典(Dictionary) 与 索引(Indexes) 两部分组成:

class ColumnLowCardinality final : public COWHelper<IColumnHelper<ColumnLowCardinality>, ColumnLowCardinality>

插入时若写入方拿到的是全列引用,而目标列容器是 ColumnLowCardinality,两者在 IBlockInputFormat/Block 的列装配阶段类型不匹配,就会触发 Bad cast。本修复在 Values 格式的插入路径上补齐了列类型的适配(必要时把输入转换为字典编码列,或统一以全列形式写入后再由列容器处理),从根本上消除了该类型不匹配。

运维建议:涉及 LowCardinality 列的表在升级本版本后,可对 Values、CSV、JSONEachRow 等常见格式分别做一次插入回归,确认编码/解码路径一致。


九、升级与验证建议

  1. 升级路径:v21.1.7.1-stable 为 v21.1 系列的补丁版本,相对 v21.1.6.13-stable 增量合入上述 7 项修复,建议在测试环境先行验证后灰度升级。
  2. 回归清单:按上文各小节给出的验证点(复制表建表参数、Tuple→Map 转换、不支持引擎的 mutation 报错、EXPLAIN + UNION、Keeper 会话日志、MODIFY COLUMN 联动元数据、LowCardinality 插入)逐一执行。
  3. 关注配置:default_replica_path、default_replica_name 属于服务端配置项(src/Core/ServerSettings.cpp),修改后需重启生效,且集群内各节点应保持一致。

十、小结

v21.1.7.1-stable 的七项修复覆盖了从存储引擎参数解析、类型系统、DDL/DML 校验、查询分析到分布式协调与列存储的多个核心链路。理解每条修复背后的源码逻辑,不仅能帮助评估升级风险,也能在同类问题再次出现时快速定位到对应模块(registerStorageMergeTree、IStorage::supportsMutation、InterpreterAlterQuery、ColumnLowCardinality 等)。本文引用的实现文件均可在当前仓库对应路径下进一步查阅细节。

登录后查看全文
ClickHouse