企业官网建设流程全解析

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关键字表示该键允许在引用处被覆盖（override），NOT OVERRIDABLE则禁止覆盖，用于保护固定配置。

执行链源码印证

CREATE NAMED COLLECTION的执行入口是 InterpreterCreateNamedCollectionQuery.cpp，其执行流程值得关注：

1. 权限检查：调用checkAccess(AccessType::CREATE_NAMED_COLLECTION, query.collection_name)，即需要CREATE NAMED COLLECTION权限；
2. 数量限制：读取服务端配置max_named_collection_num_to_throw，若当前命名集合数量达到上限，则抛出TOO_MANY_NAMED_COLLECTIONS错误；
3. 集群支持：当语句带有ON CLUSTER时，通过executeDDLQueryOnCluster在集群所有节点上执行；
4. 落库创建：最终调用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->getAnyOrDefault<String>({"host", "hostname"}, "localhost"); const auto user = named_collection->getAnyOrDefault<String>({"user", "username"}, "default"); const auto password = named_collection->getOrDefault<String>("password", ""); const auto db = named_collection->getAnyOrDefault<String>({"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_type=1但allow_experimental_object_type=0时，不再创建Object类型（PR #69150），避免两种 JSON 语义别名互相干扰。这两项设置在源码中的定义可见于 Settings.cpp：

MAKE_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.cpp："Use 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 replica（PR #69146）。

底层原理

并行副本机制将一次查询切分到多个副本并行执行，各副本通过「公告（announcement）」协议向协调者上报自身就绪或分片信息。该错误抛出点位于 ParallelReplicasReadingCoordinator.cpp：

throw 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 构建环境）：

1. 禁用内存（memory）测试（PR #69193）：在启用 Sanitizer 的构建中，内存压力类测试可能产生非确定性结果，因此被禁用；
2. 禁用 perf-like 测试（PR #69194）：同理，性能模拟类测试在 Sanitizer 环境下不具备代表性，一并关闭。

这两项变更的目的从代码库 CI 脚本的组织方式可以推断：ClickHouse 的常规测试矩阵（见 tests 与 ci）会区分 Sanitizer 构建与常规构建，Sanitizer 构建侧重正确性检测（ASan/UBSan/TSan），而性能与内存指标由常规构建与专门的 performance 测试负责，二者分工明确。

总结与升级建议

v24.8.4.13-lts 作为 24.8 LTS 系列的补丁版本，核心价值可概括为三点：

对于运行 24.8 LTS 分支的集群，建议：

1. 字典用户：升级后优先验证所有依赖 XML 配置命名集合的字典仍正常工作，再逐步迁移到CREATE NAMED COLLECTIONDDL 管理；
2. JSON 类型用户：对含null与缺失字段的样本数据做解析回归，确认默认值回退行为符合预期；
3. 并行副本用户：回归含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