ClickHouse v25.11.4.19-stable 变更详解投影位置参数、聚合溢写内存检测与关键 Bug 修复【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本文基于 docs/changelogs/v25.11.4.19-stable.md 编写系统梳理 ClickHouse 25.11 系列第 4 个 stable 补丁版本2c64eff7334相对基线v25.11.3.54-stable引入的 1 项向后不兼容变更、1 项功能改进、12 项用户可见 Bug 修复与若干构建/测试改进。读者可据此评估升级影响、理解新设置enable_positional_arguments_for_projections的集群升级作用并快速定位每个修复对应的源码与测试位置。版本概览与升级建议v25.11.4.19-stable是一个典型的补丁patch版本不含新功能开发聚焦于修复 25.11 系列先前版本暴露的稳定性问题并引入一项刻意设计为向后不兼容的变更——投影Projection定义中的位置参数positional arguments被正式禁用同时新增逃生舱设置enable_positional_arguments_for_projections帮助存在旧投影的用户平滑升级集群。升级建议若集群投影定义中从未使用GROUP BY 1、ORDER BY 2这类位置引用可直接升级若投影中存在位置参数需先开启enable_positional_arguments_for_projections再升级避免兼容性报错该补丁修复了聚合溢写、countDistinct优化、数据跳过索引、ALTER TABLE ... REWRITE PARTS等多处可能引发崩溃或错误结果的问题建议生产环境尽快跟进。向后不兼容变更投影中的位置参数与enable_positional_arguments_for_projections这是本版本唯一标记为Backward Incompatible Change的条目。该变更是对上游 PR #88380 的后续follow-up旧实现允许在PROJECTION定义中通过列序号引用列即位置参数但这种写法依赖固定的列顺序与别名解析规则在多表联查、物化列变化的场景下结果不可靠。新设置说明版本为此引入了新的专家级设置enable_positional_arguments_for_projections其定义位于 src/Core/Settings.cpp-- 全局/会话级启用 SET enable_positional_arguments_for_projections 1;类型Bool默认值0不支持位置参数取值0— 投影定义中不支持位置参数1— 支持位置参数可用列序号代替列名适用场景官方文档明确标注这是专家级设置仅当投影中已存在位置参数、需要在集群升级期间保证兼容时才应开启Settings.cpp 中的 Note 原文。该设置与既有的enable_positional_arguments普通查询中允许位置参数默认true见 Settings.cpp相互独立前者仅作用于投影定义解析上下文。源码级原理投影解析如何联动该设置在 src/Storages/ProjectionsDescription.cpp 中可以看到该设置的底层作用路径当 ClickHouse 在构建投影数据ProjectionDataSink内部查询上下文时auto mut_context Context::createCopy(context); ... const bool positional_arguments_for_projections context-getSettingsRef()[Setting::enable_positional_arguments_for_projections]; ... /// Setting enable_positional_arguments_for_projections may enable /// positional arguments for projections. It is needed for compatibility /// with existing projections that use positional arguments to allow /// successful cluster upgrade. mut_context-setSetting(enable_positional_arguments, positional_arguments_for_projections);也就是说投影的物化/写入路径在默认情况下会强制关闭enable_positional_arguments因为位置引用依赖的列序在此内部上下文中既不保证也不合理只有当用户显式开启enable_positional_arguments_for_projections时内部上下文才重新放开位置参数支持。这正是该设置的用途它是给“带旧投影升级集群”的场景准备的兼容开关。在设置历史src/Core/SettingsChangesHistory.cpp中该设置被记录为 25.11 版本的新增项随本补丁一并归入 25.11 的设置历史见 changelog 的 NOT FOR CHANGELOG 条目“Move enable_positional_arguments_for_projections into 25.11 in settings history”。功能改进聚合与排序溢写磁盘时的内存检测更健壮相关 PR#92500本版本对聚合aggregation与排序sorting过程中检测是否应溢写spill到磁盘的内存用量判断进行了健壮性改进。此前在某些边界条件下内存使用量的探测可能失真导致过晚触发溢写造成MEMORY_LIMIT_EXCEEDED或过早溢写白白损失吞吐。改进后的逻辑让max_bytes_before_external_group_by、max_bytes_before_external_sort等溢写阈值在判断时更贴近真实内存消耗。这项改进与同版本“聚合函数在MEMORY_LIMIT_EXCEEDED后可能崩溃”的修复见下文 Bug Fix形成互补共同提升了内存受限环境下的稳定性。Bug 修复详解本版本共修复 12 项用户可见问题均为官方 stable 版本中可复现的异常行为。按影响面分类如下查询错误结果类not match(...)在 WHERE 中导致数据跳过索引误判#92726关闭 #92492 修复了数据跳过逻辑data skipping在使用not match(...)时可能错误跳过数据块、返回不完整结果的严重问题。使用match/not match与跳过索引组合的查询用户应重点关注。count_distinct_optimization对窗口函数与多参数的重写错误#92376count_distinct_optimization默认falseSettings.cpp会把countDistinct/uniqExact重写为“子查询 GROUP BY count”。修复前该优化在涉及窗口函数或多参数的查询上会产生错误结果。从实现看该优化由 src/Analyzer/Passes/CountDistinctPass.cpp 中的CountDistinctVisitor驱动重写前会做一系列严格前置检查查询只能含 SELECT 子句不得有 WHERE/GROUP BY/HAVING/WINDOW/ORDER BY/LIMIT 等、只能作用于单表、投影只能有一个节点、函数必须是countDistinct或uniqExact且不带窗口function_node-hasWindow()返回 true 时直接跳过见 CountDistinctPass.cpp。本补丁正是在此基础上补齐了窗口函数与多参数场景的边界处理。MergeTree 变更mutation后序列化信息未继承导致查询结果错误#92419 修复了数据类型序列化方式变化后对已变更mutatedpart 的查询可能得到错误结果的问题——现在 mutation 会继承源 part 的序列化信息设置。崩溃与逻辑错误类Log 引擎读取子列时可能触发 logical error#91711关闭 #91710 修复Log表引擎在子列subcolumns如Map的 key/value 子列、Tuple的命名子列等读取路径上的逻辑错误断言。聚合函数在MEMORY_LIMIT_EXCEEDED之后可能崩溃#92390 修复聚合执行中内存超限异常传播路径上的空指针/状态不一致问题与上文溢写检测改进协同生效。tokens()第二参数为 NULL 时崩溃#92586 修复字符串分词函数tokens(s, delimiter)在 delimiter 传入NULL时的崩溃。ALTER TABLE ... REWRITE PARTS报 Cannot add action to empty ExpressionActionsChain#92754 修复 v2 版本的ALTER TABLE ... REWRITE PARTS在构造表达式动作链为空时报错的问题。该命令用于按当前表设置重写 part如应用新压缩编码、TTL 表达式等。数据一致性与生命周期类共享数据中 JSON 重复路径的修复机制#91886 针对此前 PR #90816 修复的缺陷可能遗留“shared data 与动态路径中出现重复 JSON 路径”的脏数据本补丁增加了修复机制来清理这类异常状态。glob 模式建表时仅缓存推断来源文件的结构#92006关闭 #91745 修复了SELECT * FROM file(dir/*.parquet)等 glob 场景下schema 推断缓存被错误地应用到目录中所有文件而非仅推断时使用的那个文件的问题。read-only 磁盘上的 MergeTree 启动时不再尝试删除临时目录#92748 避免在只读磁盘上建表的 MergeTree 于启动阶段执行无意义的临时目录清理删除操作会失败并产生噪音。连接与并发类INSERT INTO ... SELECT未释放请求流导致 HTTP 连接被关闭#92175 修复 HTTP 接口下执行INSERT INTO ... SELECT时请求流request stream未及时释放导致连接无法复用甚至被提前关闭的问题。Backup 数据库SHOW CREATE DATABASE死锁#92541 修复对BACKUP类型的数据库执行SHOW CREATE DATABASE时的死锁。构建 / 测试 / 打包改进Rust 编译缓存适配#92404 目录。非用户可见的内部修复NOT FOR CHANGELOGPolaris 目录Catalog嵌套命名空间编码修复#92079修复 Polaris catalog 中嵌套命名空间的编码问题。日志级别调整#92810降低某条日志的级别以减少噪音。设置历史归位#92841将enable_positional_arguments_for_projections归入 25.11 的设置历史记录。结语与验证建议v25.11.4.19-stable是一个“小而关键”的补丁多数修复面向错误结果与崩溃其中投影位置参数禁用与data skipping修复直接关系查询正确性。升级后可重点验证以下场景含Projection且定义中带列序号的表确认是否需要开启enable_positional_arguments_for_projections使用count_distinct_optimization或uniqExact的查询涉及窗口函数/多参数大内存聚合、排序任务观察溢写触发与内存超限表现match/not match与跳过索引组合的查询结果完整性。如需查看完整变更条目与原始 PR/Issue 链接可直接阅读 docs/changelogs/v25.11.4.19-stable.md相关设置的默认值与详细说明可在 src/Core/Settings.cpp 中检索enable_positional_arguments_for_projections与count_distinct_optimization的DECLARE条目确认。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考