ClickHouse v21.6.4.26-stable 补丁版本 Bug 修复深度解析:从复制队列到 S3 磁盘的 10 项关键修复

原创2026-09-14 15:10:311,967 阅读
文章标签:数据库列式数据库OLAP大数据分布式数据库实时分析数据仓库数据分析SQL

ClickHouse v21.6.4.26-stable 补丁版本 Bug 修复深度解析:从复制队列到 S3 磁盘的 10 项关键修复

本篇文章以 docs/changelogs/archive/v21.6.4.26-stable.md 为基础,逐条剖析 ClickHouse v21.6.4.26-stable 相对 v21.6.3.14-stable 的 Bug 修复内容。这些修复覆盖了 PostgreSQL 协议、S3 磁盘、分布式查询、复制队列、MergeTree 投影、JOIN 别名校验与 Map 函数等多个真实生产场景,读完你将对每个修复背后的触发条件、影响面以及当前仓库中对应的实现逻辑有清晰认识,并能在升级到 21.6 系列版本时准确判断哪些坑已被填平。

版本背景:一次以稳定性为目标的补丁发布

v21.6.4.26-stable 属于 ClickHouse 21.6 系列的一个补丁版本,与前一版本 v21.6.3.14-stable 相比,没有任何新功能,只有 Bug 修复。这一点可以从 changelog 的条目结构直接确认:全部变更被归类在 Bug Fix 下,另有两条被标记为 NOT FOR CHANGELOG / INSIGNIFICANT(内部测试与无关紧要的小修)。

补丁版本的每个修复条目都遵循统一的 Backport 流程——先合入主干,再通过 Backported in 反向引用确认回移,例如第一个条目对应的 PR 为 #24857,其 Backported in 链接指向 #24969。这种 "issue → PR → backport" 的编号链条,正是 ClickHouse 修复质量保证体系的一部分。

分布式查询与复制相关修复

1. 分布式查询的 limit/offset 设置(#24940)

问题:分布式查询(Distributed 表)在执行时,limit/offset 相关设置会被错误地传递到远端节点。

影响:在 ClickHouse 的执行模型中,LIMIT 既可以作为查询级设置下发到每个分片执行(减少网络传输),也可以仅在发起节点聚合后执行。当用户为分布式查询显式配置了 limit/offset 设置时,本应只作用于本地聚合结果的参数被错误地下推,导致远端节点各自执行截断,最终结果集不正确。

修复方式:修复后,limit/offset 设置被标记为"忽略远端节点"(ignore on the remote nodes),即只在发起方生效。这类"仅对协调节点生效"的设置处理逻辑,在 src/Core/Settings.cpp 中以声明宏的方式集中管理,每个设置项附带类型、默认值与文档说明,是 ClickHouse 上千个设置项的统一入口。

2. 复制队列中罕见的 "Tagging already tagged part" 错误(#24961)

问题:在并发执行 ALTER MOVE PARTITION / ALTER REPLACE PARTITION 时,复制队列(replication queue)中可能出现极低概率的错误 Tagging already tagged part,此问题被怀疑与 issue #22142 相关。

机制解读:在 ReplicatedMergeTree 中,每个数据 part 在元数据层面会被"打标签"(tagging)以标记其在某个 ALTER 任务中的归属状态。当两个并发的分区级 ALTER 操作同时作用于同一个 part 时,若缺少正确的加锁与状态检查,就可能出现对已标记 part 的重复标记。这属于典型的**竞态条件(race condition)**问题,影响面极窄("extremely rare"),但一旦触发会阻塞复制队列。

从当前仓库的结构看,ReplicatedMergeTree 的 ALTER 分区逻辑、复制队列管理分布在 src/Storages/MergeTree 目录下,其中 StorageReplicatedMergeTree.cpp 与 ReplicatedMergeTreePartCheckThread.cpp 等文件共同负责 part 状态机与队列条目的生命周期管理,这部分修复的核心就是在状态切换前增加幂等性检查,避免对同一 part 的重复状态写入。

3. 副本克隆后数据一致性测试强化(#24968)

条目 Try fix test_consistent_parts_after_clone_replica 属于内部测试修复。它尝试修复 test_consistent_parts_after_clone_replica 测试——该测试验证的是克隆副本之后各副本上 part 集合是否保持一致,是副本间数据一致性保障的关键回归测试。结合上一条复制队列修复可以理解:当复制队列中出现异常状态时,副本间 part 集合的一致性可能被破坏,该测试正是用来尽早暴露此类问题的看门狗。

MergeTree 表引擎与查询执行修复

4. 聚合投影在空/非空 GROUP BY 间切换的错误结果(#25055)

问题:当表上有聚合投影(aggregate projection)且投影使用非空 GROUP BY 键,而查询使用空 GROUP BY 键(即全局聚合、无 GROUP BY)时,执行结果错误。

机制解读:投影(Projection)是 MergeTree 家族内置的物化加速机制——一个投影相当于表内的"迷你物化视图",预先按投影定义的 GROUP BY 与聚合函数计算好部分聚合结果。查询优化器会把匹配的查询改写为"读投影 + 二次聚合"。

但这里存在一个语义差异:投影按非空键分组后,每个组内已经做过一次聚合;当外部查询要求全局聚合(空键)时,理论上可以基于投影做二次聚合(sum of sums)。此修复针对的是这一改写路径中结果错误的问题,说明当时的二次聚合合并逻辑对"键集合不匹配"的场景处理不完整。

5. 禁止自引用表达式列(#25059)

问题:允许创建自引用列,例如:

CREATE TABLE t (a UInt32 ALIAS a + 1);     -- 列 a 的 ALIAS 表达式引用自身
CREATE TABLE t2 (b UInt32 MATERIALIZED b); -- 列 b 的 MATERIALIZED 表达式引用自身

这会形成无限递归的列表达式,导致读取该表时陷入死循环或栈溢出。此问题同时被 #24910 与 #24292 两个 issue 报告。

修复:在 DDL 解析阶段(CREATE TABLE / ALTER ADD COLUMN)增加对表达式依赖的环检测:若某列的表达式直接或间接引用了它自身,直接拒绝建表。ClickHouse 的列定义解析与默认/别名表达式展开逻辑位于 src/Parsers 与 src/Interpreters 目录,其中对 ASTColumnDeclaration 的处理是拦截此类自引用的关键位置。对于已经存在此类自引用表的用户,修复后读取该表依然可能报错,建议重建表并移除非法列。

6. 投影与 FINAL 的互斥:SELECT ... FINAL 不再使用投影(#25163)

问题:当 SELECT 语句带有 FINAL 修饰符时,优化器仍可能选择使用表上的投影来执行查询。

机制解读:FINAL 修饰符要求读取时在线合并所有数据 part,得到完全合并后的数据视图(通常用于消除 ReplacingMergeTree、CollapsingMergeTree 等引擎中的重复行)。而投影是预先物化的部分聚合结果,两者的语义无法正确叠加——对折叠/去重类引擎,投影中的中间态经过 FINAL 在线合并后结果不可预期。因此在当时,投影 + FINAL 的组合是不被支持的。

修复:当查询包含 FINAL 时,优化器明确禁用投影选择路径,退化为直接读取原始列并执行在线合并。当前仓库的文档与注册代码 src/Storages/MergeTree/registerStorageMergeTree.cpp 中仍然保留着明确说明:

Projections are not supported in the SELECT statements with the FINAL modifier.

这与此修复的语义一脉相承,可作为长期行为准则参考。

7. UUID 分区键在升级到 21.5 后的潜在数据丢失(#25127)

问题:在升级到 21.5 及后续版本时,若表的分区键(partition key)使用了 UUID 列,可能发生 part 丢失。此问题由 #25070 报告。

机制解读:part 的存储路径基于分区键值生成,UUID 的二进制表示含不可打印字符与特殊字节,早期版本在将分区值编码为路径目录时对 UUID 的处理与后续版本不一致,导致升级后新写入的 part 被路由到与旧 part 不同的目录,从旧目录看来如同 part "丢失"。ClickHouse 官方对此的明确建议是:不建议在分区键中使用 UUID(原文:It is not recommended to use UUID in partition key)。

修复:在升级路径中增加对 UUID 分区键场景的兼容处理,避免升级前后 part 目录命名不一致。升级到 21.6 系列的存量用户若使用了 UUID 分区键,应重点检查 system.parts 与各分区目录,确认无孤立 part。

存储层修复:S3 磁盘

8. 允许声明在桶根目录的 S3 磁盘(#24898)

问题:当 S3 磁盘(disk = s3 类型)的路径直接指向桶的根目录时,启动会直接报错:

DB::Exception: Key name is empty in path style S3 URI: (http://172.17.0.2/bucket/) (version 21.6.1.1)
(in query: SELECT policy_name FROM system.storage_policies)

机制解读:ClickHouse 将 S3 对象的 key 解析为 bucket + prefix/key 的组合。当磁盘配置中的路径是 bucket/(根目录,无前缀)时,解析出的 key 为空字符串,底层 S3 客户端(AWS SDK)对空 key 的请求校验失败,进而抛出 "Key name is empty" 异常。这一异常甚至会在执行 SELECT policy_name FROM system.storage_policies 这类元数据查询时出现,因为系统表需要枚举所有存储策略及其磁盘。

修复:在磁盘初始化与 key 解析路径中放行"桶根目录"这一合法场景。当前仓库中 S3 存储层的核心实现位于 src/Disks/DiskObjectStorage/ObjectStorages/S3/S3ObjectStorage.cpp,其中大量操作(如 listObjects、getObjectInfo、deleteFileFromS3)都通过 splitBucketAndKey 等辅助函数把远程路径拆分为桶与 key 两部分,再调用 S3 客户端 API;对根目录场景的特殊处理正是在这类拆分逻辑中加入的边界条件判断。磁盘的解析与注册入口则在 src/Disks/DiskObjectStorage/ObjectStorages/ObjectStorageFactory.cpp 与 src/Disks/getDiskConfigurationFromAST.cpp。

修复后,以下配置(路径为桶根目录)可正常使用:

<storage_configuration>
    <disks>
        <s3_disk>
            <type>s3</type>
            <endpoint>http://172.17.0.2/bucket/</endpoint>
            <access_key_id>your_key</access_key_id>
            <secret_access_key>your_secret</secret_access_key>
        </s3_disk>
    </disks>
    <policies>
        <default>
            <volumes>
                <main>
                    <disk>s3_disk</disk>
                </main>
            </volumes>
        </default>
    </policies>
</storage_configuration>

协议与 JOIN 相关修复

9. PostgreSQL 协议允许 NULL 值(#24857)

问题:通过 ClickHouse 的 PostgreSQL wire protocol 兼容层接入时,返回结果中的 NULL 值处理异常,关闭 issue #22622。

机制解读:ClickHouse 的 PostgreSQL 协议实现位于 src/Server 目录(PostgreSQLHandler 相关文件),它允许 PostgreSQL 生态的客户端(如 psql)直接连接 ClickHouse。协议层面,NULL 值需要在类型描述与数据编码两个环节都正确表达:PostgreSQL 协议在 DataRow 消息中用字段长度为 -1 表示 NULL,而 ClickHouse 内部使用独立的 Nullable 标记位。此修复确保了两者在协议编码与解码侧的严格对齐,避免 NULL 被误编码为默认值或空串。

10. cross join 与 joined_subquery_requires_alias=0 组合下的崩溃(#25082)

问题:当设置 joined_subquery_requires_alias = 0 且查询中包含 cross join 时,ClickHouse 可能直接崩溃。此问题由 #24011 报告。

机制解读:joined_subquery_requires_alias 是一个布尔设置,其默认值与完整说明定义在 src/Core/Settings.cpp:

Force joined subqueries and table functions to have aliases for correct name qualification.

该设置的含义是:强制 JOIN 中的子查询与表函数必须带有别名,以保证列名正确限定(name qualification)。当用户显式关闭该限制(设为 0)后,后续的列名解析逻辑可能拿到一个"无名"表,在 cross join 特有的笛卡尔积展开路径中出现未初始化的列引用,进而崩溃。

该设置的实际校验逻辑位于 src/Interpreters/JoinedTables.cpp:当设置开启且参与 JOIN 的表数量大于 1 时,逐表检查——若某子查询或表函数既没有表名也没有别名,则抛出 ALIAS_REQUIRED 异常并附带提示:

No alias for subquery or table function in JOIN (set joined_subquery_requires_alias=0 to disable restriction).

修复:即使 joined_subquery_requires_alias = 0,后续列名限定与 JOIN 构建路径也必须对"匿名表"保持健壮,不再触发崩溃。对于用户而言,最佳实践依然是始终为 JOIN 中的子查询和表函数显式命名别名,这不仅是规避崩溃的底线,也是可读性与列引用正确性的保证。

函数修复:mapContains 与常量 Map

11. 常量 Map 上的 mapContains 报 "empty column" 错误(#25080)

问题:当 mapContains(map, key) 中的 map 参数为常量表达式时,可能触发错误:

empty column was returned by function mapContains

由 issue #25077 报告。

机制解读:mapContains(map, key) 用于判断 Map 是否包含指定 key,返回 UInt8(1 表示包含,0 表示不包含)。在 src/Functions/array/FunctionsMapMiscellaneous.cpp 的注册代码中可以看到,mapContains 实际上是 mapContainsKey 的大小写敏感别名:

factory.registerAlias("mapContains", "mapContainsKey", FunctionFactory::Case::Sensitive);

函数实现(mapContainsKeyImpl)的底层执行路径依赖一个共享列(shared column)提取 key 集合,当两个参数均为常量时,优化器可能把整个函数折叠为常量求值,但在常量传播与列物化的交互中出现中间列未正确物化的情况,最终返回空列(empty column),被上层校验捕获并报错。

修复:在常量 Map / 常量 key 的求值路径上补齐列物化逻辑。使用 mapContains 的用户若曾遇到此错误,可升级到 21.6.4+ 或后续版本解决;Map 数据类型的完整实现可参考 src/DataTypes/DataTypeMap.cpp。

内部修复与杂项

除上述用户可见修复外,本版本还包含两条标记为 NOT FOR CHANGELOG / INSIGNIFICANT 的内部变更:

  • DictionaryLoader 配置创建修复(#25001):修复了 DictionaryLoader 在加载外部字典时不必要地重复创建字典配置的问题。外部字典(Dictionaries)是 ClickHouse 通过 src/Dictionaries 目录下的框架实现的,DictionaryLoader 负责按配置文件的变更增量加载/重载字典;此修复避免了配置未变化时仍触发重建的无效开销,对大量字典场景下的稳定性与效率均有正向意义。

升级与验证建议

  1. 升级路径:v21.6.4.26-stable 是 21.6 系列的稳定补丁版,修复均为 bug fix,无破坏性变更,21.6 系列用户可直接升级;低版本(如 21.5 及以下)用户在升级前请特别关注第 7 条(UUID 分区键)。
  2. 升级后自查项:
    • 若使用 S3 磁盘,验证 SELECT policy_name FROM system.storage_policies 不再报 "Key name is empty";
    • 检查 system.replication_queue 是否有残留的失败任务(对应第 2 条复制队列竞态);
    • 若使用 PostgreSQL 协议接入 BI 工具,抽查含 NULL 的查询结果;
    • 若使用投影加速,确认 SELECT ... FINAL 查询不再被投影改写(第 6 条)。
  3. 长期规避建议:不要在分区键中使用 UUID 列;始终为 JOIN 子查询与表函数指定别名(即使 joined_subquery_requires_alias=0 可用也不应依赖);建表时避免任何形式的自引用 ALIAS/MATERIALIZED 列。

从这 10 余项修复可以看到,补丁版本的粒度往往聚焦于"边界条件":空 key、空列、空 GROUP BY、匿名子查询、常量参数、自引用——这些都是在正常路径之外最容易暴雷的场景。理解每个修复背后的触发条件,比记住修复本身更有价值,它决定了你在生产环境中何时需要警惕、升级后如何验证。

登录后查看全文
ClickHouse