ClickHouse v21.3.13.9-lts 版本发布解析：核心改进与关键 Bug 修复全景解读

ClickHouse v21.3.13.9-lts 版本发布解析核心改进与关键 Bug 修复全景解读【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse导读本文以 ClickHouse 当前仓库 docs/changelogs/archive/v21.3.13.9-lts.md 中记录的 v21.3.13.9-lts 版本相对 v21.3.12.2-lts 的补丁版为骨架逐一拆解该补丁版本引入的 1 项改进与 33 项 Bug 修复并结合仓库源码src/Core/Settings.cpp、src/Functions/DateTimeTransforms.h、src/Functions/FunctionJoinGet.cpp等深挖每类修复背后的底层原理。读完本文你将理解 ClickHouse 21.3 LTS 分支常见故障的成因与修复方式掌握 Kafka 多格式消费、hedged 请求、复制表 ZooKeeper 协调、S3 磁盘等机制的实现细节并学会如何在生产环境用 CHANGELOG 定位与规避同类问题。一、版本定位21.3 LTS 分支的补丁节奏1.1 版本基线本次发布对象为v21.3.13.9-lts比较基线是v21.3.12.2-lts属于 21.3 LTS 分支的维护补丁版本。该 CHANGELOG 被归档在 docs/changelogs/archive/v21.3.13.9-lts.md 中文档头部以sidebar_position: 1、sidebar_label: 2022标记说明它被归入 2022 年的归档序列。从变更结构看该版本延续 ClickHouse 发布说明的三段式组织Improvement改进仅 1 项聚焦标量子查询错误可见性Bug FixBug 修复33 项覆盖查询执行、复制协调、IO/格式、函数、DDL、安全等多个子系统NO CL ENTRY / NOT FOR CHANGELOG记录反向回退与测试/内部修复供开发者追踪历史。1.2 补丁的 Backport 机制CHANGELOG 中大量条目带有 Backported in #xxxxx 标记。这说明 21.3 LTS 的修复来自 master 分支先修复、再由维护者挑选backport到 LTS 分支的机制。例如 ZooKeeper 客户端挂起修复原 PR 为 #24721而 v21.3 分支的回退记录在 NO CL ENTRY 小节中Revert Backport #24721 to 21.3: Remove endlesswaitfrom ZooKeeper client说明该修复曾在分支上反复试验最终以重新回退告终——这正是 LTS 分支审慎合入高风险改动的一个实例。二、Improvement让标量子查询的错误不再被吞掉唯一一项改进针对标量子查询scalar subquery的错误处理避免隐藏类似Limit for rows or bytes to read exceeded读取的行数或字节数超过限制的错误。PR #24545。标量子查询要求结果恰好为一行其执行路径与普通查询不同当外部查询已经取得所需数据后子查询的管道可能被提前取消或静默处理导致max_result_rows、max_result_bytes等限制触发的错误信息丢失用户只看到查询失败而不知道根因。修复后这类错误会被显式上抛到客户端。该行为与 ClickHouse 查询限制体系直接相关。max_result_rows、max_result_bytes等设置在 src/Core/Settings.cpp 中集中声明是控制查询资源消耗的常见手段对涉及子查询的复杂 SQL升级到该版本后更易获得可诊断的报错信息而不是笼统的失败提示。三、Kafka 引擎增强Parquet 消息消费支持修复条目Kafka 存储可以支持 Parquet 格式的消息PR #23412。ClickHouse 的 Kafka 表引擎Kafka负责把消息反序列化为行数据其format参数决定消息的解析格式。此前虽然已支持 JSONEachRow、CSV、Avro、Protobuf 等常见格式但 Parquet列式存储格式消息在 Kafka 消费链路上会失败。该补丁为 Kafka 引擎补齐了 Parquet 消息的反序列化支持使 Kafka → ClickHouse 的列式数据流转成为可能。配置示例Kafka 表结合 Parquet 格式CREATE TABLE kafka_messages ( id UInt64, name String ) ENGINE Kafka() SETTINGS kafka_broker_list localhost:9092, kafka_topic_list topic_parquet, kafka_group_name ch_group, kafka_format Parquet, kafka_num_consumers 4;需要说明的是Parquet 消息内部必须包含与表结构兼容的列消息 schema 与表 schema 不一致时仍会报类型或列缺失错误。四、查询执行引擎修复hedged 请求、过滤下推与 JOIN本版本集中修复了一批影响查询正确性与稳定性的引擎级缺陷。4.1GLOBAL IN/JOIN与 hedged 请求的管道冲突修复条目修复在GLOBAL IN/JOIN与use_hedged_requests同时启用时抛出Cant initialize pipeline with empty pipe的问题PR #23805。Hedged 请求是 ClickHouse 针对分布式查询的容错机制其设置定义在 src/Core/Settings.cppuse_hedged_requests true默认开启 Enables hedged requests logic for remote queries. It allows to establish many connections with different replicas for query.该机制允许查询同时向多个副本建立连接若在hedged_connection_timeout_ms默认 50ms内连接未建立或receive_data_timeout_ms默认 2000ms内未收到首个数据包就开启新连接查询采用第一个发送非空进度包或首个数据包的连接其余连接被取消。同时相关设置allow_changing_replica_until_first_data_packet默认 false控制是否在收到首个数据包前允许切换副本。而GLOBAL IN/JOIN需要先在发起方节点物化子查询结果再广播给所有分片这一初始化阶段与 hedged 请求多路连接并存时管道可能尚未产生任何数据源从而触发 empty pipe 初始化错误。修复后两条特性可以安全组合使用。4.2 过滤条件下推丢失 WHERE 条件修复条目修复查询计划表达式下推优化query_plan_filter_push_down 1默认开启丢失WHERE条件的问题PR #25370。该开关同样在 src/Core/Settings.cpp 中声明query_plan_filter_push_down true Toggles a query-plan-level optimization which moves filters down in the execution plan. Only takes effect if setting query_plan_enable_optimizations is 1.过滤条件下推属于查询计划层的优化把WHERE中的谓词尽可能下推到更早的执行步骤例如表扫描阶段以减少中间结果量。此前的实现存在缺陷部分场景下条件在优化过程中被错误丢弃导致结果集扩大甚至语义错误。该版本修复了下推路径上 WHERE 条件丢失的问题同时文档明确标注这是一个面向开发者调试的专家级开关普通生产环境建议保持默认开启。4.3 跨 JOIN 崩溃与别名校验两条相关修复修复joined_subquery_requires_alias 0时跨连接cross join查询崩溃的问题PR #25082修复REPLACE列变换器在 DDL 中的引号格式问题PR #25391。joined_subquery_requires_alias默认 true见 src/Core/Settings.cpp要求 JOIN 子查询必须显式命名别名便于后续列引用关闭该校验后匿名子查询在 cross join 计划生成阶段会触发空列访问崩溃修复后该组合不再崩溃。4.4LowCardinality相关修复本版本包含三条与LowCardinality相关的修复修复LowCardinality参数用于IN时抛Bad cast from type DB::ColumnLowCardinality to DB::ColumnVectorchar8_t的问题PR #25290该 bug 自 21.6 引入支持SimpleAggregateFunction(LowCardinality)用于SummingMergeTreePR #25300修复joinGetOrNull与不可空列组合的问题PR #25288。joinGet/joinGetOrNull的实现位于 src/Functions/FunctionJoinGet.cpp两者都基于storage_join-joinGet(...)完成 JOIN 字典式点查区别在于effective_or_null标志决定命中失败时返回NULL还是抛出异常。此前当目标列为非Nullable类型时joinGetOrNull的 NULL 返回路径会发生类型不匹配错误修复后保证了两种函数的类型安全。五、时间与聚合函数修复5.1toWeek单调性误判引发的分区裁剪错误修复条目修复toWeek函数错误的单调性monotonicity判断PR #24446该问题由更智能的分区裁剪器partition pruner暴露追溯到早期 PR #5212 引入的缺陷。ClickHouse 在分区裁剪时会利用函数的单调性信息把范围谓词如WHERE toWeek(date) 5转换为等价的最小/最大分区范围从而跳过无关分区。toWeek的实现位于 src/Functions/DateTimeTransforms.h其核心是time_zone.toYearWeek(...)返回YearWeek并取出周序号。关键点在源码注释中写得很明确/// toWeek() is not monotonic because week numbers can wrap at year boundaries /// (e.g. ISO week 52 - week 1 in late December), depending on the week_mode. static constexpr bool hasMonotonicity() { return false; }由于一年末尾的周号会回绕如 ISO 周 52 → 次年周 1toWeek在全年范围内并不单调。早期版本误将hasMonotonicity()返回true导致分区裁剪器基于错误的单调假设裁剪掉本应包含结果的分区从而产生漏行。修复将单调性声明改为false分区裁剪回归保守路径数据不再丢失。对生产用户而言此修复尤其影响“按周聚合 分区裁剪”类的查询升级后请验证相关 SQL 结果一致性。5.2quantileDeterministic系列的非确定性行为修复条目修复quantileDeterministic及类似函数可能的非确定性行为PR #25313。quantileDeterministic以用户提供的确定性权重如某个 ID 列替代随机数选择样本理论上应保证结果可复现。修复前的实现在某些并发/分片场景下引入了不确定性导致同一查询重复执行得到不同分位数。该修复保证了这类“确定性分位数”聚合函数在相同输入下的可复现性。5.3mapContains常量 Map 处理修复条目修复常量 Map 上mapContains抛empty column was returned by function mapContains的问题PR #25080。当mapContains的参数是编译期常量 Map例如字面量构造的 Map时实现会走入空列返回路径修复后常量场景正常返回结果。六、复制表与 ZooKeeper 协调本版本修复重灾区21.3 LTS 复制表ReplicatedMergeTree依赖 ZooKeeper 协调元数据本版本有 6 项相关修复足见该分支在此处的稳定性投入。6.1 ZooKeeper 客户端挂起与无限等待修复可能导致 clickhouse-server 内 ZooKeeper 客户端挂起的问题PR #24721。但该修复随后在 v21.3 分支被回退见 NO CL ENTRY 小节说明其在 LTS 分支引入了新的回归修复 ZooKeeper 连接丢失后ReplicatedMergeTree会无限等待后台操作完成再重连的问题PR #25306修复后后台操作被强制停止连接恢复更快。6.2 复制队列陈旧条目与相交虚拟分区修复条目PR #24777解决两个问题ZooKeeper 连接丢失后副本被克隆clone恢复复制队列中可能残留过期条目复制队列出现相交虚拟分区intersecting virtual parts时直接终止进程现在改为打印错误日志。这种“从致命崩溃改为日志告警”的修复策略说明该问题属于罕见的元数据不一致场景致命退出会放大故障影响面。6.3SYSTEM RESTART REPLICA/SYSTEM SYNC REPLICA无限执行修复条目修复低内存服务器上SYSTEM RESTART REPLICA或SYSTEM SYNC REPLICA被无限处理的问题PR #24457。内存极度紧张时副本状态初始化可能迟迟无法推进导致管理命令卡死修复后命令可正常完成。6.4 Mutation 与并发 DDL 相关修复 mutation 尚未加载进内存时wait操作向客户端抛Mutation was killed的问题PR #24809修复低内存服务器上偶发无法执行 merge合并直至重启的问题PR #24872修复并发ALTER MOVE/REPLACE PARTITION时复制队列抛Tagging already tagged part的极罕见错误PR #24961修复带相交 fake parts 的DROP PARTITIONPR #24321——极少数情况下分区的 mutation 版本号会大于当前 block 号导致分区删除逻辑错乱。七、IO、格式与序列化修复7.1 分布式表子列读取修复条目为分布式表Distributed tables启用子列subcolumns读取PR #24472。分布式表查询此前在需要null、size0等子列时无法正确下推修复后子列语义在分布式场景下与本地表保持一致。7.2 HTTP 层修复允许空 HTTP 请求头PR #24285修复通过 HTTP 插入数据触发异常导致服务器故障的问题PR #23643修复multipart/form-data消息中边界boundary前 CRLF 的解析CRLF 应作为 boundary 的一部分处理PR #24399此前错误的解析会导致带多部分的 HTTP 插入请求解析失败。7.3 格式序列化修复 Protobuf 格式拆分嵌套消息splitted nested messages的序列化问题PR #25000修复 Arrow 格式中可能的堆缓冲区溢出heap-buffer-overflowPR #24922。7.4 远程 JDBC 桥接超时修复条目修复远程 JDBC 桥JDBC bridge的连接超时问题PR #24588。使用jdbc表函数/引擎访问外部数据库时桥接连接建立的超时处理此前存在缺陷会导致查询在桥接恢复前长时间挂起。八、存储、S3 磁盘与 DDL 校验8.1 S3 磁盘声明在桶根目录修复条目修复将 S3 磁盘声明在桶bucket根目录时报错Key name is empty in path style S3 URI的问题PR #24898。此前若配置http://host/bucket/不带 key 前缀作为磁盘根路径system.storage_policies查询会因 key 为空而报错。修复后支持将整个桶作为磁盘根目录。相关配置形如storage_configuration disks s3_disk types3/type endpointhttp://minio:9000/bucket//endpoint access_key_idkey/access_key_id secret_access_keysecret/secret_access_key /s3_disk /disks policies s3_policy volumes main disks3_disk/disk /main /volumes /s3_policy /policies /storage_configuration8.2 自引用列的 DDL 校验修复条目修复允许创建列引用自身如a UInt32 ALIAS a 1、b UInt32 MATERIALIZED b的问题PR #25059。此前这种 DDL 能成功建表但查询时会产生无限递归表达式求值修复后在 DDL 解析阶段即拒绝自引用列。8.3 安装脚本与 Copier修复安装脚本中的 TOCTOUtime-of-check to time-of-use竞态问题PR #25277修复 copier 任务配置缺失sharding_key时触发段错误的问题PR #25419。九、LDAP 与NO CL ENTRY记录修复条目修复 LDAP 组映射到不存在的本地角色时LDAP 角色重新映射可能发生的死锁PR #24431NO CL ENTRY小节记录了 ZooKeeper 客户端修复在 21.3 分支的回退PR #24799以及两个内部修复test_consistent_parts_after_clone_replica测试修复PR #24968、DictionaryLoader不必要的字典配置创建修复PR #25001。十、升级与排查建议结合本版本修复面给出 21.3 LTS 用户的升级与验证建议复制表与 ZooKeeper 场景若生产中遇到过SYSTEM RESTART REPLICA卡死、复制队列陈旧条目、mutation 被误报 killed 等问题本版本包含对应修复升级后建议观察system.replicas、system.replication_queue指标确认复制健康度。查询结果一致性toWeek单调性修复意味着此前依赖分区裁剪的“按周”查询可能改变裁剪路径请回归验证周聚合 SQL 的结果quantileDeterministic修复后确定性分位数查询应可稳定复现。Kafka 与格式链路如需消费 Parquet 消息确认 Kafka 表kafka_format Parquet并核对消息 schemaHTTP 多部分上传场景验证空头与 boundary 解析行为。专家级开关query_plan_filter_push_down、use_hedged_requests等均默认开启其中 hedged 请求在云端默认关闭见 src/Core/Settings.cpp 中的Cloud default value: 0说明除非调试需要不建议手动关闭。结语v21.3.13.9-lts 是一个典型的 LTS 维护补丁单点改进聚焦错误可诊断性33 项修复均匀分布在查询引擎、复制协调、存储与格式链路体现了 ClickHouse 在 LTS 分支上“以稳定为先、谨慎合入”的维护策略。通过 CHANGELOG 对照源码开发者可以快速定位每个修复的生效范围为自己的升级决策与故障排查提供依据。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考