ClickHouse v24.8.4.13-lts 补丁版本解析字典命名集合、JSON 类型解析与并行副本 UNION 的关键修复【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse导读本文基于官方发布的 v24.8.4.13-lts 变更日志深入剖析 24.8 LTS 系列这一补丁版本中包含的 1 项功能性改进与 2 项用户可见的 Bug 修复并结合 ClickHouse 源码验证其底层实现包括字典Dictionary全面改用 DDL 创建的命名集合Named Collections、JSON 类型解析中null默认值插入问题、以及并行副本Parallel Replicas场景下子查询UNION引发LOGICAL_ERROR的修复。读完本文你将清楚了解这些变更的触发条件、影响范围以及如何在配置与源码层面印证修复逻辑。版本概览v24.8.4.13-lts 在 LTS 系列中的定位v24.8.4.13-lts 是基于 v24.8.3.59-lts 的下一个补丁版本build commit53195bc189b延续 24.8 LTS长期支持分支。该版本遵循 ClickHouse 的「补丁即修复」惯例不引入破坏性变更而是聚焦于1 项Improvement改进字典中命名集合的旧代码迁移2 项Bug Fix用户可见的稳定版行为缺陷修复JSON 解析与并行副本查询若干NOT FOR CHANGELOG / INSIGNIFICANT的内部与测试基建调整。下文逐项展开每一节都会给出对应的源码证据路径便于你在仓库中复核。改进字典全面支持 DDL 创建的命名集合变更内容本次版本最核心的改进对应 PR #68412是删除字典中命名集合named collections的旧代码并将其替换为新实现从而允许使用 DDL 创建的命名集合在字典中直接使用。该变更同时收尾了 #60936 与 #36890 两个历史遗留问题——此前通过CREATE NAMED COLLECTION语句创建的命名集合无法被字典源Dictionary Source引用只能依赖服务端配置文件中的声明。命名集合是什么命名集合是一组可复用的键值配置如连接外部系统的 host、port、user、password 等用于字典、表函数、外部表等场景避免在多个 DDL 中重复书写敏感连接参数。其 DDL 语法定义在 ParserCreateQuery.cpp 的语句注册表中CREATE NAMED COLLECTION [IF NOT EXISTS] name [ON CLUSTER cluster] AS key_name1 some value [[NOT] OVERRIDABLE], key_name2 some value [[NOT] OVERRIDABLE], ...例如CREATE NAMED COLLECTION foobar AS a 1, b 2 OVERRIDABLE;其中OVERRIDABLE关键字表示该键允许在引用处被覆盖overrideNOT OVERRIDABLE则禁止覆盖用于保护固定配置。执行链源码印证CREATE NAMED COLLECTION的执行入口是 InterpreterCreateNamedCollectionQuery.cpp其执行流程值得关注权限检查调用checkAccess(AccessType::CREATE_NAMED_COLLECTION, query.collection_name)即需要CREATE NAMED COLLECTION权限数量限制读取服务端配置max_named_collection_num_to_throw若当前命名集合数量达到上限则抛出TOO_MANY_NAMED_COLLECTIONS错误集群支持当语句带有ON CLUSTER时通过executeDDLQueryOnCluster在集群所有节点上执行落库创建最终调用NamedCollectionFactory::instance().createFromSQL(query)将集合持久化到元数据存储相关实现见 NamedCollectionsFactory.cpp 与 NamedCollectionsMetadataStorage.cpp。字典中的新路径以 ClickHouse 字典源为例字典源对新命名集合的消费逻辑集中在 ClickHouseDictionarySource.cpp。其核心模式是当字典由 DDL 创建created_from_ddl true时先通过tryGetNamedCollectionWithOverrides(config, settings_config_prefix, global_context)获取命名集合命中后调用validateNamedCollection校验合法键名集合然后逐一用getOrDefault/getAnyOrDefault读取配置并支持别名与默认值const auto secure named_collection-getOrDefault(secure, false); const auto host named_collection-getAnyOrDefaultString({host, hostname}, localhost); const auto user named_collection-getAnyOrDefaultString({user, username}, default); const auto password named_collection-getOrDefaultString(password, ); const auto db named_collection-getAnyOrDefaultString({db, database}, default_database);值得注意的细节键别名机制如{host, hostname}表示二者等价{user, username}、{db, database}同理兼容不同使用习惯覆盖语义tryGetNamedCollectionWithOverrides会合并 DDL 中声明的OVERRIDABLE覆盖项同类改造范围该模式在本次版本中同步覆盖多个字典源除 ClickHouse 外还包括 MongoDBDictionarySource.cpp、PostgreSQLDictionarySource.cpp、MySQLDictionarySource.cpp、HTTPDictionarySource.cpp 与 YTsaurusDictionarySource.cpp。实战建议升级到该版本后若你的字典此前只能通过服务端 XML 配置声明命名集合现在可以改用CREATE NAMED COLLECTION ... AS ...以 DDL 方式管理并通过CREATE DICTIONARY ...(SOURCE(CLICKHOUSE(NAME collection_name)))引用实现配置的版本化与可迁移。注意 DDL 命名集合在部分 ClickHouse Cloud 服务上需联系 Support 确认可用性参见 ParserCreateQuery.cpp 中的说明。Bug 修复一JSON 类型解析中 null 的默认值插入问题现象在部分场景下当解析 JSON 类型数据时遇到null应当回退为类型的默认值但旧实现会产生解析错误。修复PR #68955确保 JSON 解析器在字段值为null且目标类型允许默认值时正确插入默认值而非报错。触发场景该问题主要出现在使用新JSON类型而非旧Object(json)类型存储半结构化数据数据中同一字段在不同行呈现「有值 / null / 缺失」混合状态字段声明带默认值语义。与相关设置的联动本补丁中还包含一项配套内部变更当use_json_alias_for_old_object_type1但allow_experimental_object_type0时不再创建Object类型PR #69150避免两种 JSON 语义别名互相干扰。这两项设置在源码中的定义可见于 Settings.cppMAKE_OBSOLETE(M, Bool, use_json_alias_for_old_object_type, false) \ MAKE_OBSOLETE(M, Bool, allow_experimental_object_type, false) \其中use_json_alias_for_old_object_type的历史语义记录在 SettingsChangesHistory.cppUse JSON type alias to create new JSON type。从MAKE_OBSOLETE宏可以推断在 24.8 LTS 分支中这些设置已逐步标记为废弃并收敛为统一的JSON类型行为——即JSON别名默认指向新的JSON类型实现。实战提示如果你依赖旧Object(json)行为升级后建议在测试环境验证JSON类型在null/缺失字段场景下的表现若出现兼容性问题可通过显式设置use_json_alias_for_old_object_type与allow_experimental_object_type的取值观察差异但需知晓它们已进入废弃流程。Bug 修复二并行副本查询中子查询 UNION 引发的 LOGICAL_ERROR问题现象当查询开启**并行副本Parallel Replicas**机制且子查询中包含UNION子句时旧实现处理不当会触发日志级错误LOGICAL_ERROR: Duplicate announcement received for replicaPR #69146。底层原理并行副本机制将一次查询切分到多个副本并行执行各副本通过「公告announcement」协议向协调者上报自身就绪或分片信息。该错误抛出点位于 ParallelReplicasReadingCoordinator.cppthrow Exception(ErrorCodes::LOGICAL_ERROR, Duplicate announcement received for replica number {}, announcement.replica_num);从源码结构可以推断协调者为每个replica_num只允许接收一次公告而UNION子查询会让同一副本的处理路径被重复触发导致协调者收到重复公告并判定为内部状态不一致。修复通过调整子查询UNION在并行副本执行计划中的处理方式确保每个副本仅发送一次公告从而消除该LOGICAL_ERROR。影响与规避受影响范围使用parallel_replicas相关设置如parallel_replicas_count等相关实现遍布 src/Client 与 src/Analyzer/Resolve/QueryAnalyzer.cpp且在子查询中使用UNION的查询修复前规避手段在升级前可将子查询中的UNION改写为UNION ALL或拆分为多个独立查询再合并以绕过公告重复路径修复后无需规避但建议仍对含UNION的并行副本查询做一次回归验证确认不再出现该LOGICAL_ERROR且结果正确。内部变更与测试基建调整NOT FOR CHANGELOG该补丁还包含两项不影响用户可见行为但值得注意的 CI/测试调整均针对 Sanitizer 构建环境禁用内存memory测试PR #69193在启用 Sanitizer 的构建中内存压力类测试可能产生非确定性结果因此被禁用禁用 perf-like 测试PR #69194同理性能模拟类测试在 Sanitizer 环境下不具备代表性一并关闭。这两项变更的目的从代码库 CI 脚本的组织方式可以推断ClickHouse 的常规测试矩阵见 tests 与 ci会区分 Sanitizer 构建与常规构建Sanitizer 构建侧重正确性检测ASan/UBSan/TSan而性能与内存指标由常规构建与专门的 performance 测试负责二者分工明确。总结与升级建议v24.8.4.13-lts 作为 24.8 LTS 系列的补丁版本核心价值可概括为三点变更类型内容源码印证改进字典全面支持 DDL 创建的命名集合废弃旧代码ClickHouseDictionarySource.cpp、InterpreterCreateNamedCollectionQuery.cppBug 修复JSON 类型解析中null正确回退默认值Settings.cppBug 修复并行副本子查询UNION不再触发公告重复LOGICAL_ERRORParallelReplicasReadingCoordinator.cpp对于运行 24.8 LTS 分支的集群建议字典用户升级后优先验证所有依赖 XML 配置命名集合的字典仍正常工作再逐步迁移到CREATE NAMED COLLECTIONDDL 管理JSON 类型用户对含null与缺失字段的样本数据做解析回归确认默认值回退行为符合预期并行副本用户回归含UNION子查询的复杂查询确认Duplicate announcement received for replica不再出现。完整变更条目可查阅 docs/changelogs/v24.8.4.13-lts.md。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考