ClickHouse v25.10 稳定版发布全解读新特性、不兼容变更与性能优化实战指南【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本篇技术指南基于 ClickHouse 官方变更日志 docs/changelogs/v25.10.1.3832-stable.md系统梳理 v25.10 稳定版在兼容性、SQL 能力、函数库、表引擎、查询优化与稳定性方面的全部关键变化。读完本文你将完整掌握 25.10 的升级风险点尤其是 6 项不兼容变更的应对方案、可以直接上手的新 SQL 语法与函数如LIMIT BY ALL、conv、naiveBayesClassifier以及本次版本在索引、JOIN、文件系统缓存等热点路径上的性能优化细节。版本概览v25.10.1.3832-stable提交 f95c1af632a是 ClickHouse 2025 年的稳定版本之一与其上一版本v25.10.1.1-new提交 5b1dfb14925相比本次发布涵盖6 项 Backward Incompatible Change向后不兼容变更升级前必须评估20 项 New Feature新特性覆盖 SQL 语法、函数、表引擎、系统表与运维命令2 项 Experimental Feature实验特性涉及近似向量检索22 项 Performance Improvement性能改进80 项左右 Improvement改进110 项左右 Bug FixBug 修复聚焦稳定版中用户可见的行为错误若干 Build/Testing/Packaging 改进一、向后不兼容变更升级前必读1.1 schema 推断默认行为变化尊重列的可空性元数据默认设置schema_inference_make_columns_nullable的行为被修改现在会尊重 Parquet / ORC / Arrow 元数据中列本身的Nullable信息而不是一律把所有列推断为 Nullable。文本格式如 CSV、TSV的行为不受影响。这直接改变了依赖推断列一律可空假设的 ETL 逻辑若你的下游代码假设某列一定可空或一定不可空升级后需要显式检查推断结果。1.2 查询结果缓存不再受log_comment影响此前只要查询的log_comment设置变化就会导致查询结果缓存query result cachemiss。本次修改后仅改变log_comment不再强制缓存失效。如果你曾经刻意用log_comment对缓存做分段隔离此行为已改变因此被标记为不兼容。官方建议改用专门的设置query_cache_tag来实现缓存分段。1.3 格式化行为的修正操作符不再被当作表函数格式化旧版本中与操作符实现函数同名的表函数在格式化时存在不一致。本次修复后EXPLAIN SYNTAX不再把操作符格式化出来更准确地反映解释语法的目的clickhouse-format、formatQuery等格式化工具在查询中以函数形式书写操作符时不再将其改写为操作符形态。1.4 JOIN 键禁止使用 Dynamic 类型禁止在 JOIN key 中使用 Dynamic 类型。原因是 Dynamic 与非 Dynamic 类型比较时可能产生意外结果。正确做法是先通过CAST把 Dynamic 列转换为目标类型再参与 JOIN。该限制的源码实现逻辑可在 ClickHouse 的 Analyzer/查询分析阶段找到对应校验相关类型处理见 src/Analyzer 目录。1.5 对象存储元数据写入默认开启回滚有版本限制storage_metadata_write_full_object_key服务端选项现在默认开启且无法关闭。虽然此变更本身向后兼容但它只与 25.x 系列前向兼容这意味着如果升级后需要回滚只能回滚到任意 25.x 版本不能回滚到 24.x 及更早。生产环境务必在升级前确认回滚路径。1.6 复制去重窗口从 1 周缩短为 1 小时replicated_deduplication_window_seconds默认值从 1 周604800 秒缩减为1 小时3600 秒目的是在插入速率较低时减少 ZooKeeper 上的 znode 存储量。该设置的清理逻辑实现在 src/Storages/MergeTree/ReplicatedMergeTreeCleanupThread.cpp其含义是Replicated 表插入去重只在最近 1 小时内有效超过该窗口的重复插入将不再被自动去重。如果业务存在超过 1 小时的重复插入场景需要显式调大此设置。1.7 其他不兼容调整设置query_plan_use_new_logical_join_step更名为query_plan_use_logical_join_step分词器参数语法变得更具表达力影响文本索引的 tokenizer 配置写法函数searchAny/searchAll更名为hasAnyTokens/hasAllTokens与既有hasToken命名体系保持一致另提供单数别名hasAnyToken/hasAllToken移除文件系统缓存中的cache_hits_threshold参数——该特性诞生于 SLRU 缓存策略之前如今已有 SLRU 策略不再需要同时维护两者min_free_disk_ratio_to_perform_insert与min_free_disk_bytes_to_perform_insert两处行为调整① 改用unreserved未预留字节而非 available 字节判断是否拒绝插入当后台 merge/mutation 预留远小于阈值时影响不大但语义更正确②不再应用于系统表确保query_log等系统表在磁盘紧张时仍能持续写入极大方便问题排查Keeper 内部复制默认启用异步模式。若从 23.9 之前的版本升级需要先升级到 23.9 再升级到 25.10也可以在升级前通过keeper_server.coordination_settings.async_replication 0关闭升级完成后再开启。二、新特性SQL 能力与函数扩展2.1 SQL 语法LIMIT BY ALL与负数LIMIT/OFFSET新增LIMIT BY ALL语法与既有的GROUP BY ALL、ORDER BY ALL对齐自动将 SELECT 子句中所有非聚合表达式展开为LIMIT BY的 key。例如-- 等价于 SELECT id, name, count(*) FROM table GROUP BY id LIMIT 1 BY id, name SELECT id, name, count(*) FROM table GROUP BY id LIMIT 1 BY ALL当你想按所有选中的非聚合列做限流而无需逐一列举列名时该语法能显著简化查询。其解析与语义构建逻辑位于 src/Analyzer/QueryTreeBuilder.cpp 等查询分析代码中。同时支持负数LIMIT与负数OFFSET关闭 issue #28913为分页和取数逻辑提供了更大的灵活性。2.2 新函数函数说明源码位置conv(number, from_base, to_base)在 2~36 进制之间转换数字src/Functions/conv.cppnaiveBayesClassifier基于 n-gram 的朴素贝叶斯文本分类src/Functions/FunctionNaiveBayesClassifier.cpp、FunctionNaiveBayesNgrams.cppstudentTTestOneSample单样本 Students T 检验聚合函数src/AggregateFunctions/AggregateFunctionStudentTTestOneSample.cppquantilePrometheusHistogram输入直方图桶上界与累计值在分位数所在桶上下界间线性插值行为类似 PromQL 经典直方图的histogram_quantile()src/AggregateFunctions/AggregateFunctionQuantilePrometheusHistogram.cppstartsWithCaseInsensitive/endsWithCaseInsensitive大小写不敏感的startsWith/endsWith—startsWithCaseInsensitiveUTF8/endsWithCaseInsensitiveUTF8UTF-8 感知的大小写不敏感变体—conv函数实现于独立的 conv.cpp支持2-36进制naiveBayesClassifier的核心在于 n-gram 特征提取与贝叶斯概率计算可在FunctionNaiveBayesNgrams.cpp中看到其 n-gram 构造实现。2.3 表引擎与存储Alias引擎、min_level_for_wide_partAlias表引擎创建到另一张表的代理所有读写操作都转发到目标表别名本身不存储数据仅维护对目标表的引用。相关引擎实现在 src/Storages 下本次同时修复了EXCHANGE TABLES在 Alias 表上的支持引擎改为存储目标表的库名表名而非固定 storage id。新表设置min_level_for_wide_part指定 part 被创建为 wide part 所需的最小 levelpart 层级定义于 src/Storages/MergeTree/MergeTreeSettings.cpp。通过控制 part 何时从 compact 形态转为 wide 形态可在小表场景下减少文件数量开销。ALTER TABLE ... REWRITE PARTS从头重写表的所有 parts使所有新设置如use_const_adaptive_granularity等只对新 part 生效的设置得到应用——适合在调整表级设置后强制生效的场景。2.4 统计与索引自动创建统计信息、Sparse_gram 布隆过滤器MergeTree 自动统计信息新增表级设置auto_statistics_types用逗号分隔要自动创建的统计类型例如auto_statistics_types minmax, uniq, countmin实现在 src/Storages/MergeTree/MergeTreeSettings.cpp。开启后系统会对 MergeTree 表中所有合适的列自动创建统计。Sparse_gram 布隆过滤器索引实验性/新索引类型面向文本检索场景的稀疏 gram bloom filter 索引。2.5 数据湖与外部系统集成Apache Paimon 查询支持ClickHouse 可直接查询 Paimon 数据湖存储Delta Lake 元数据文件系统表新增系统表用于查看 Delta Lake 元数据文件Datalakes catalog 数据库支持以目录catalog方式管理数据湖元数据面向分布式处理场景相关实现见 src/Databases 与数据湖相关存储目录。2.6 运维与配置能力SYSTEM RECONNECT ZOOKEEPER强制 ZooKeeper 断开并重连便于故障演练与连接修复命名集合Named Collection上限通过设置max_named_collection_num_to_warn和max_named_collection_num_to_throw限制命名集合数量新增指标NamedCollection与错误TOO_MANY_NAMED_COLLECTIONSSQL 定义 WORKLOAD/RESOURCE可在服务端配置resources_and_workloads段中通过 SQL 提供 WORKLOAD 和 RESOURCE 定义--semicolons_inlineclickhouse-format新增选项分号放在最后一行而非另起一行--login访问 ClickHouse Cloud支持使用 Cloud 凭据登录Keeper 客户端递归命令新增cp/cpr、mv/mvr递归变体。2.7 系统表与可观测性新增keeper_hosts设置暴露 ClickHouse 可连接的 [Zoo]Keeper 主机列表system.zookeeper_connection_log默认开启可直接获取 Keeper 会话信息同时修复了首次配置重载后连接日志追加的问题新增指标ZooKeeperSessionExpired过期全局 ZooKeeper 会话数、KeeperRequestRejectedDueToSoftMemoryLimitCountsystem.tables支持按uuid过滤时避免全表扫描src/Storages/System当只持有 UUID 或 ZooKeeper 路径时可快速定位表。三、实验特性近似向量检索QBit数据类型以 bit-sliced位切片格式存储向量实现在 src/Columns/ColumnQBit.cpp 与 ColumnQBit.hL2DistanceTransposed函数支持近似向量搜索精度与速度的权衡由参数控制配套的优化 PassDistanceTransposedPartialReadsPass在 src/Analyzer/Passes/DistanceTransposedPartialReadsPass.cpp负责处理部分QBit读取本版本还修复了当p为 Nullable 时错误移除返回类型Nullable的LOGICAL_ERROR。searchAll/searchAny支持非文本列当输入不是文本列时这两个函数改用默认 tokenizer 工作。四、性能改进查询、索引与存储的全链路优化4.1 查询条件缓存QCC与索引分析重构通过重构 Query Condition CacheQCC与索引分析的顺序和集成方式大幅提升查询性能QCC 过滤现在先于主键与跳数索引skip index分析执行减少不必要的索引计算索引分析扩展到支持多个范围过滤器且过滤结果会写回 QCC对索引分析占主导的查询尤其依赖向量/倒排等跳数索引的场景提速显著PR #82380。4.2 字符串与子列String 列新增可选.size子列序列化MergeTree 顶层 String 列提升压缩率并支持高效子列访问同时引入序列化版本控制与空字符串表达式优化的新 MergeTree 设置#82850并修复了 compact part 中 Sparse.size子列读取的上下文缺失问题。大小写敏感字符串搜索如WHERE URL LIKE %google%改用StringZilla库在可用时利用 SIMD 指令加速#84161。LIKE前缀/后缀场景默认开启optimize_rewrite_like_perfect_affix重写优化#85920。4.3 JOIN 与聚合JOIN 谓词析取下推将析取OR形式的 JOIN 条件拆解为各表独立的局部过滤例如 TPC-H Q7 中(n1.n_nameFRANCE AND n2.n_nameGERMANY) OR (n1.n_nameGERMANY AND n2.n_nameFRANCE)会被拆分为 n1 与 n2 各自的 OR 过滤#84735JOIN 运行时布隆过滤在运行时从右子树构建布隆过滤器并传给左子树扫描优化多表 JOIN 查询#84772joined_block_split_single_row设置哈希 JOIN 中单左行匹配海量右行时允许分块物化显著降低峰值内存可能增加 CPU 使用#87913聚合MergeoverDistributed的两级聚合修复、ReplacingMergeTreeFINALis_deleted的并行化改进单 part 分区跳过 FINAL、分区内 intersecting/non-intersecting 拆分JOIN 优化阶段跳过运行时哈希表统计重算新增JoinOptimizeMicroseconds与QueryPlanOptimizeMicrosecondsprofile eventsJOIN/ARRAY JOIN 中惰性列复制避免将 Sparse、Replicated 等特殊列表示转换为全量列减少不必要的内存拷贝#88752。4.4 网络协议与传输原生协议中压缩日志与 profile events在 100 副本的集群上未压缩的 profile events 可达 1..10 MB/s慢速网络下进度条会卡顿压缩后显著改善#83586X-ClickHouse-100-Continue: defer配合Expect: 100-continue时服务端在配额校验通过前不发送100 Continue避免传输注定被丢弃的请求体浪费带宽#84304enable_http_compression默认开启客户端接受 HTTP 压缩时服务端将启用压缩但注意客户端可请求bzip2等重压缩方法增加服务端资源消耗。4.5 存储与文件系统缓存MergeTreeLazy 读取器启用 cache 中的 marks 保存并避免 direct IO#87989文件系统缓存中复用缓存优先级迭代器减少多线程并发预留缓存空间的竞争#87914修复大量字符串/数字列分组时大序列化 key 导致的性能退化#85924temporary_files_buffer_size设置控制临时文件写缓冲大小并优化LowCardinality列的scatter内存消耗#88237文本索引构建在文档多数 token 不频繁时提速#87546文本索引支持直接读取object storage与并行副本直读#88262system.tables按uuid过滤避免全表扫描#88379。4.6 其他微观优化大量小查询微优化#83096、DB::SharedMutex改进、Field析构加速、fail points 关闭时的开销降低、tokens/hasAllTokens/hasAnyTokens函数性能提升、Iceberg 顺序读取#88454、SimpleAggregateFunction(anyLast)聚合查询减少内存分配与拷贝#84428。五、改进Improvement精选5.1 Keeper 相关配置被覆盖时可配置服务端级限流#74066新增keeper_server.tcp_nodelay参数可关闭 Keeper 的TCP_NODELAY#87363新增keeper_server.coordination_settings.check_node_acl_on_remove开启后删除节点前同时校验节点自身与父节点的 ACL否则只校验父节点#88513新增max_request_size对应 ZooKeeper 的jute.maxbuffer默认关闭以保持向后兼容#87952Keeper 写事务期间可检查任意节点的 stat辅助 ABA 问题检测#87282clickhouse-keeper支持连接 TLS 端口flag 命名与clickhouse-client保持一致。5.2 客户端与工具链客户端自动补全改用system.completions更快且更一致#84694clickhouse-client文件如查询历史遵循XDG Base Directories规范存放若已存在~/.clickhouse-client-history则继续使用clickhouse-benchmarkCLI flag 中可用-替代_、支持--connection复用 client 的connections_credentials配置、支持--accept-invalid-certificate、错误消息默认不再包含堆栈另有--proto-caps选项clickhouse-local可从clickhouse-server目录启动直接操作服务端数据库此前报Cannot parse UUID: .#88383新设置inject_random_order_for_select_without_order_by为顶层无ORDER BY的 SELECT 注入ORDER BY rand()。5.3 查询语义与函数完整支持操作符IS NOT DISTINCT FROM#88155mannWhitneyUTest在两样本均为相同值时不再抛异常返回与 SciPy 一致的有效结果hasToken对空 token 返回零匹配此前抛异常函数lag大小写不敏感兼容 MySQL#88322generateSerialID新增可选start_value参数且系列名支持非常量参数JSON列在Vertical格式下美化打印#88524EXCHANGE TABLES支持 Alias 引擎表#88233Replicated数据库允许无参数创建#88044跳数索引在 FINAL 查询中位于主键列时跳过跨 part 的主键交集检查#88368。5.4 文本索引新增dictionary_block_frontcoding_compression文本索引参数控制字典压缩默认启用 front-coding 压缩#87175文本索引支持Array与MapmapKeys/mapValues值支持mapContainsKey与has函数#87602hasAnyTokens/hasAllTokens新增接受字符串输入的 overload#88679。5.5 物化视图与合并物化视图插入前按min_insert_block_size_rows_for_materialized_views/min_insert_block_size_bytes_for_materialized_views跨线程合并数据避免parallel_view_processing下产生过多 parts#87280合并选择器先执行to_remove_small_parts_at_right启发式再计算合并范围分数修复宽合并选择问题#88736新增 session 设置exclude_materialize_skip_indexes_on_insert与表设置exclude_materialize_skip_indexes_on_merge排除指定跳数索引的物化。5.6 安全与可观测性使用 Backup 引擎配合 S3 存储时日志中掩码 S3 凭据#85336system.crash_log刷新改为信号处理中同步执行#87253PrometheusMetricsWriter新增直方图与维度指标#87521全局采样 profiler 默认开启每 10 秒收集所有线程的 CPU 与实时堆栈#88209新增 profile event 统计后台 merge 因内存限制被拒绝的次数#88084约束违反时的异常消息长度受限避免超长字符串写入 query_log#88801。六、Bug 修复精选官方稳定版用户可见问题6.1 日期时间修复 pre-epoch 日期带小数秒处理错误此前parseDateTime64BestEffort(1969-01-01 00:00:00.468)返回1968-12-31 23:59:59.532亚秒部分被错误减去现正确返回1969-01-01 00:00:00.468#85396toDate与toDate32对所有数值类型行为对齐修复 int16 转换时的 Date32 下溢检查#87176修复使用session_timezone时基于 datetime 键的 granule/分区剪枝错误#87987修复date_time_overflow_behavior saturate下 DateTime64 转 Date 在时区场景的越界错误#88737。6.2 查询执行与优化器修复 CTE 中计算函数结果非确定性问题#86967修复OUTER JOINoptimize_functions_to_subcolumns下可空列IS NULL行为错误#87058修复并行副本下多 JOIN尤其 RIGHT JOIN 位于 LEFT/INNER JOIN 之后的逻辑错误#87178修复新分析器中SELECT * REPLACE在 WHERE 子句过滤被替换列的错误#87630修复MergeoverDistributed的两级聚合#87687修复GLOBAL IN导致的内存泄漏#88617修复ARRAY JOIN COLUMNS()在新分析器中无匹配列时的逻辑错误#88091修复相关性子查询在对象存储上的工作问题#88290。6.3 存储与复制修复 MergeTree 表 set 列 TTL 可能导致的数据损坏#88095修复_row_number虚拟列与 iceberg positioned deletes 的逻辑错误#87220修复复制数据库在恢复后长时间卡在Failed to marked query-... as finished的问题#88671修复 Replicated 数据库恢复/清理、DDL worker 清理过期副本主机以减少 ZooKeeper 元数据#88154修复 DatabaseReplicated 未尊重interserver_http_host配置#88378ON CLUSTER查询在集群存在非活跃副本时耗时更短#88153修复从文本索引读取并启用查询条件缓存use_skip_indexes_on_data_readuse_query_condition_cache时的读取问题#88660。6.4 格式与外部系统修复 GeoParquet 导致客户端协议错误#84020修复 CSV 反序列化时类型顺序错误导致LOGICAL_ERROR#87622修复 ArrowStream 文件字典不唯一时的崩溃#87863修复 PostgreSQL 接口布尔值写入#87762、返回受影响行数#87990修复 Glue 中timestamp/timestamptz列处理#87733修复 EmbeddedRocksDB 升级问题#87392。6.5 函数与类型修复mortonEncode/hilbertEncode空 tuple 参数崩溃#88110修复countMatches二次复杂度问题#88401修复reverseUTF8错误反转 4 字节 UTF-8 码点字节序#88914修复 base32/base58 编解码缓冲区大小计算#89133修复top_k单参数时未尊重 threshold 参数#88867修复approx_top_k与finalizeAggregation的致命错误#87892修复L2DistanceTransposed的 Nullable 返回类型LOGICAL_ERROR#88974。6.6 运维与可观测性修复异步日志导致的内存泄漏10 小时约 100 GiB 漂移text_log 类似#87584修复 async logging 失败导致程序 abort#88814修复无 cgroups 环境运行 ClickHouse 时异步指标要求 cgroups 的意外问题#88164修复ColumnLowCardinality的is_shared标志传播导致的 GROUP BY 错误结果#88213。七、构建 / 测试 / 打包改进增加全文搜索索引的性能测试用例#87577测试用 PostgreSQL 升级到 18.0#87647FreeBSD 启用 ICU#87891动态分派到 sse4.2 时使用 sse4.2 而非 sse4 编译选项#88029当ENABLE_LIBFIUOFF构建时 failpoint 相关函数成为 no-opSYSTEM ENABLE/DISABLE FAILPOINT返回SUPPORT_IS_DISABLED错误#88184修复 wide_integer 在缺少std::make_pair环境下的编译错误#88498clickhouse-keeperpostinstall 脚本新增开机自启步骤#88746发布版构建默认禁用调试符号#88585。八、升级建议与运维要点综合上述变更升级到 v25.10 时应重点关注回滚策略storage_metadata_write_full_object_key强制开启回滚仅限 25.x 系列建议升级前记录当前版本并验证 25.x 回滚链路复制去重窗口replicated_deduplication_window_seconds默认 1 小时如业务有跨小时重复插入场景需显式调大在 src/Storages/MergeTree/MergeTreeSettings.cpp 中定义Keeper 升级路径若从 23.9 之前升级先升级到 23.9 再升级到 25.10或分两步切换async_replicationschema 推断Parquet/ORC/Arrow 的列可空性推断遵循元数据需回归测试依赖推断行为的任务函数重命名searchAny/searchAll更名检查代码与 SQL 中的引用缓存分段结果缓存不再因log_comment变化失效改用query_cache_tagDynamic JOIN keyJOIN 键中的 Dynamic 列需显式 CAST。九、延伸阅读本版本源码中的关键实现位置src/Functions/conv.cpp、src/Functions/FunctionNaiveBayesClassifier.cpp、src/AggregateFunctions/AggregateFunctionStudentTTestOneSample.cpp、src/AggregateFunctions/AggregateFunctionQuantilePrometheusHistogram.cpp、src/Columns/ColumnQBit.cpp、src/Storages/MergeTree/MergeTreeSettings.cpp、src/Storages/MergeTree/ReplicatedMergeTreeCleanupThread.cpp测试与验证tests/queriesstateless 查询测试、tests/integration集成测试以及 src/Functions/tests/gtest_functions_stress.cpp函数压力测试中均可找到对应特性的覆盖用例【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/17 15:49:55 · 阅读 1.2k ClickHouse v25.10 稳定版发布全解读：新特性、不兼容变更与性能优化实战指南
ClickHouse v25.10 稳定版发布全解读新特性、不兼容变更与性能优化实战指南【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本篇技术指南基于 ClickHouse 官方变更日志 docs/changelogs/v25.10.1.3832-stable.md系统梳理 v25.10 稳定版在兼容性、SQL 能力、函数库、表引擎、查询优化与稳定性方面的全部关键变化。读完本文你将完整掌握 25.10 的升级风险点尤其是 6 项不兼容变更的应对方案、可以直接上手的新 SQL 语法与函数如LIMIT BY ALL、conv、naiveBayesClassifier以及本次版本在索引、JOIN、文件系统缓存等热点路径上的性能优化细节。版本概览v25.10.1.3832-stable提交 f95c1af632a是 ClickHouse 2025 年的稳定版本之一与其上一版本v25.10.1.1-new提交 5b1dfb14925相比本次发布涵盖6 项 Backward Incompatible Change向后不兼容变更升级前必须评估20 项 New Feature新特性覆盖 SQL 语法、函数、表引擎、系统表与运维命令2 项 Experimental Feature实验特性涉及近似向量检索22 项 Performance Improvement性能改进80 项左右 Improvement改进110 项左右 Bug FixBug 修复聚焦稳定版中用户可见的行为错误若干 Build/Testing/Packaging 改进一、向后不兼容变更升级前必读1.1 schema 推断默认行为变化尊重列的可空性元数据默认设置schema_inference_make_columns_nullable的行为被修改现在会尊重 Parquet / ORC / Arrow 元数据中列本身的Nullable信息而不是一律把所有列推断为 Nullable。文本格式如 CSV、TSV的行为不受影响。这直接改变了依赖推断列一律可空假设的 ETL 逻辑若你的下游代码假设某列一定可空或一定不可空升级后需要显式检查推断结果。1.2 查询结果缓存不再受log_comment影响此前只要查询的log_comment设置变化就会导致查询结果缓存query result cachemiss。本次修改后仅改变log_comment不再强制缓存失效。如果你曾经刻意用log_comment对缓存做分段隔离此行为已改变因此被标记为不兼容。官方建议改用专门的设置query_cache_tag来实现缓存分段。1.3 格式化行为的修正操作符不再被当作表函数格式化旧版本中与操作符实现函数同名的表函数在格式化时存在不一致。本次修复后EXPLAIN SYNTAX不再把操作符格式化出来更准确地反映解释语法的目的clickhouse-format、formatQuery等格式化工具在查询中以函数形式书写操作符时不再将其改写为操作符形态。1.4 JOIN 键禁止使用 Dynamic 类型禁止在 JOIN key 中使用 Dynamic 类型。原因是 Dynamic 与非 Dynamic 类型比较时可能产生意外结果。正确做法是先通过CAST把 Dynamic 列转换为目标类型再参与 JOIN。该限制的源码实现逻辑可在 ClickHouse 的 Analyzer/查询分析阶段找到对应校验相关类型处理见 src/Analyzer 目录。1.5 对象存储元数据写入默认开启回滚有版本限制storage_metadata_write_full_object_key服务端选项现在默认开启且无法关闭。虽然此变更本身向后兼容但它只与 25.x 系列前向兼容这意味着如果升级后需要回滚只能回滚到任意 25.x 版本不能回滚到 24.x 及更早。生产环境务必在升级前确认回滚路径。1.6 复制去重窗口从 1 周缩短为 1 小时replicated_deduplication_window_seconds默认值从 1 周604800 秒缩减为1 小时3600 秒目的是在插入速率较低时减少 ZooKeeper 上的 znode 存储量。该设置的清理逻辑实现在 src/Storages/MergeTree/ReplicatedMergeTreeCleanupThread.cpp其含义是Replicated 表插入去重只在最近 1 小时内有效超过该窗口的重复插入将不再被自动去重。如果业务存在超过 1 小时的重复插入场景需要显式调大此设置。1.7 其他不兼容调整设置query_plan_use_new_logical_join_step更名为query_plan_use_logical_join_step分词器参数语法变得更具表达力影响文本索引的 tokenizer 配置写法函数searchAny/searchAll更名为hasAnyTokens/hasAllTokens与既有hasToken命名体系保持一致另提供单数别名hasAnyToken/hasAllToken移除文件系统缓存中的cache_hits_threshold参数——该特性诞生于 SLRU 缓存策略之前如今已有 SLRU 策略不再需要同时维护两者min_free_disk_ratio_to_perform_insert与min_free_disk_bytes_to_perform_insert两处行为调整① 改用unreserved未预留字节而非 available 字节判断是否拒绝插入当后台 merge/mutation 预留远小于阈值时影响不大但语义更正确②不再应用于系统表确保query_log等系统表在磁盘紧张时仍能持续写入极大方便问题排查Keeper 内部复制默认启用异步模式。若从 23.9 之前的版本升级需要先升级到 23.9 再升级到 25.10也可以在升级前通过keeper_server.coordination_settings.async_replication 0关闭升级完成后再开启。二、新特性SQL 能力与函数扩展2.1 SQL 语法LIMIT BY ALL与负数LIMIT/OFFSET新增LIMIT BY ALL语法与既有的GROUP BY ALL、ORDER BY ALL对齐自动将 SELECT 子句中所有非聚合表达式展开为LIMIT BY的 key。例如-- 等价于 SELECT id, name, count(*) FROM table GROUP BY id LIMIT 1 BY id, name SELECT id, name, count(*) FROM table GROUP BY id LIMIT 1 BY ALL当你想按所有选中的非聚合列做限流而无需逐一列举列名时该语法能显著简化查询。其解析与语义构建逻辑位于 src/Analyzer/QueryTreeBuilder.cpp 等查询分析代码中。同时支持负数LIMIT与负数OFFSET关闭 issue #28913为分页和取数逻辑提供了更大的灵活性。2.2 新函数函数说明源码位置conv(number, from_base, to_base)在 2~36 进制之间转换数字src/Functions/conv.cppnaiveBayesClassifier基于 n-gram 的朴素贝叶斯文本分类src/Functions/FunctionNaiveBayesClassifier.cpp、FunctionNaiveBayesNgrams.cppstudentTTestOneSample单样本 Students T 检验聚合函数src/AggregateFunctions/AggregateFunctionStudentTTestOneSample.cppquantilePrometheusHistogram输入直方图桶上界与累计值在分位数所在桶上下界间线性插值行为类似 PromQL 经典直方图的histogram_quantile()src/AggregateFunctions/AggregateFunctionQuantilePrometheusHistogram.cppstartsWithCaseInsensitive/endsWithCaseInsensitive大小写不敏感的startsWith/endsWith—startsWithCaseInsensitiveUTF8/endsWithCaseInsensitiveUTF8UTF-8 感知的大小写不敏感变体—conv函数实现于独立的 conv.cpp支持2-36进制naiveBayesClassifier的核心在于 n-gram 特征提取与贝叶斯概率计算可在FunctionNaiveBayesNgrams.cpp中看到其 n-gram 构造实现。2.3 表引擎与存储Alias引擎、min_level_for_wide_partAlias表引擎创建到另一张表的代理所有读写操作都转发到目标表别名本身不存储数据仅维护对目标表的引用。相关引擎实现在 src/Storages 下本次同时修复了EXCHANGE TABLES在 Alias 表上的支持引擎改为存储目标表的库名表名而非固定 storage id。新表设置min_level_for_wide_part指定 part 被创建为 wide part 所需的最小 levelpart 层级定义于 src/Storages/MergeTree/MergeTreeSettings.cpp。通过控制 part 何时从 compact 形态转为 wide 形态可在小表场景下减少文件数量开销。ALTER TABLE ... REWRITE PARTS从头重写表的所有 parts使所有新设置如use_const_adaptive_granularity等只对新 part 生效的设置得到应用——适合在调整表级设置后强制生效的场景。2.4 统计与索引自动创建统计信息、Sparse_gram 布隆过滤器MergeTree 自动统计信息新增表级设置auto_statistics_types用逗号分隔要自动创建的统计类型例如auto_statistics_types minmax, uniq, countmin实现在 src/Storages/MergeTree/MergeTreeSettings.cpp。开启后系统会对 MergeTree 表中所有合适的列自动创建统计。Sparse_gram 布隆过滤器索引实验性/新索引类型面向文本检索场景的稀疏 gram bloom filter 索引。2.5 数据湖与外部系统集成Apache Paimon 查询支持ClickHouse 可直接查询 Paimon 数据湖存储Delta Lake 元数据文件系统表新增系统表用于查看 Delta Lake 元数据文件Datalakes catalog 数据库支持以目录catalog方式管理数据湖元数据面向分布式处理场景相关实现见 src/Databases 与数据湖相关存储目录。2.6 运维与配置能力SYSTEM RECONNECT ZOOKEEPER强制 ZooKeeper 断开并重连便于故障演练与连接修复命名集合Named Collection上限通过设置max_named_collection_num_to_warn和max_named_collection_num_to_throw限制命名集合数量新增指标NamedCollection与错误TOO_MANY_NAMED_COLLECTIONSSQL 定义 WORKLOAD/RESOURCE可在服务端配置resources_and_workloads段中通过 SQL 提供 WORKLOAD 和 RESOURCE 定义--semicolons_inlineclickhouse-format新增选项分号放在最后一行而非另起一行--login访问 ClickHouse Cloud支持使用 Cloud 凭据登录Keeper 客户端递归命令新增cp/cpr、mv/mvr递归变体。2.7 系统表与可观测性新增keeper_hosts设置暴露 ClickHouse 可连接的 [Zoo]Keeper 主机列表system.zookeeper_connection_log默认开启可直接获取 Keeper 会话信息同时修复了首次配置重载后连接日志追加的问题新增指标ZooKeeperSessionExpired过期全局 ZooKeeper 会话数、KeeperRequestRejectedDueToSoftMemoryLimitCountsystem.tables支持按uuid过滤时避免全表扫描src/Storages/System当只持有 UUID 或 ZooKeeper 路径时可快速定位表。三、实验特性近似向量检索QBit数据类型以 bit-sliced位切片格式存储向量实现在 src/Columns/ColumnQBit.cpp 与 ColumnQBit.hL2DistanceTransposed函数支持近似向量搜索精度与速度的权衡由参数控制配套的优化 PassDistanceTransposedPartialReadsPass在 src/Analyzer/Passes/DistanceTransposedPartialReadsPass.cpp负责处理部分QBit读取本版本还修复了当p为 Nullable 时错误移除返回类型Nullable的LOGICAL_ERROR。searchAll/searchAny支持非文本列当输入不是文本列时这两个函数改用默认 tokenizer 工作。四、性能改进查询、索引与存储的全链路优化4.1 查询条件缓存QCC与索引分析重构通过重构 Query Condition CacheQCC与索引分析的顺序和集成方式大幅提升查询性能QCC 过滤现在先于主键与跳数索引skip index分析执行减少不必要的索引计算索引分析扩展到支持多个范围过滤器且过滤结果会写回 QCC对索引分析占主导的查询尤其依赖向量/倒排等跳数索引的场景提速显著PR #82380。4.2 字符串与子列String 列新增可选.size子列序列化MergeTree 顶层 String 列提升压缩率并支持高效子列访问同时引入序列化版本控制与空字符串表达式优化的新 MergeTree 设置#82850并修复了 compact part 中 Sparse.size子列读取的上下文缺失问题。大小写敏感字符串搜索如WHERE URL LIKE %google%改用StringZilla库在可用时利用 SIMD 指令加速#84161。LIKE前缀/后缀场景默认开启optimize_rewrite_like_perfect_affix重写优化#85920。4.3 JOIN 与聚合JOIN 谓词析取下推将析取OR形式的 JOIN 条件拆解为各表独立的局部过滤例如 TPC-H Q7 中(n1.n_nameFRANCE AND n2.n_nameGERMANY) OR (n1.n_nameGERMANY AND n2.n_nameFRANCE)会被拆分为 n1 与 n2 各自的 OR 过滤#84735JOIN 运行时布隆过滤在运行时从右子树构建布隆过滤器并传给左子树扫描优化多表 JOIN 查询#84772joined_block_split_single_row设置哈希 JOIN 中单左行匹配海量右行时允许分块物化显著降低峰值内存可能增加 CPU 使用#87913聚合MergeoverDistributed的两级聚合修复、ReplacingMergeTreeFINALis_deleted的并行化改进单 part 分区跳过 FINAL、分区内 intersecting/non-intersecting 拆分JOIN 优化阶段跳过运行时哈希表统计重算新增JoinOptimizeMicroseconds与QueryPlanOptimizeMicrosecondsprofile eventsJOIN/ARRAY JOIN 中惰性列复制避免将 Sparse、Replicated 等特殊列表示转换为全量列减少不必要的内存拷贝#88752。4.4 网络协议与传输原生协议中压缩日志与 profile events在 100 副本的集群上未压缩的 profile events 可达 1..10 MB/s慢速网络下进度条会卡顿压缩后显著改善#83586X-ClickHouse-100-Continue: defer配合Expect: 100-continue时服务端在配额校验通过前不发送100 Continue避免传输注定被丢弃的请求体浪费带宽#84304enable_http_compression默认开启客户端接受 HTTP 压缩时服务端将启用压缩但注意客户端可请求bzip2等重压缩方法增加服务端资源消耗。4.5 存储与文件系统缓存MergeTreeLazy 读取器启用 cache 中的 marks 保存并避免 direct IO#87989文件系统缓存中复用缓存优先级迭代器减少多线程并发预留缓存空间的竞争#87914修复大量字符串/数字列分组时大序列化 key 导致的性能退化#85924temporary_files_buffer_size设置控制临时文件写缓冲大小并优化LowCardinality列的scatter内存消耗#88237文本索引构建在文档多数 token 不频繁时提速#87546文本索引支持直接读取object storage与并行副本直读#88262system.tables按uuid过滤避免全表扫描#88379。4.6 其他微观优化大量小查询微优化#83096、DB::SharedMutex改进、Field析构加速、fail points 关闭时的开销降低、tokens/hasAllTokens/hasAnyTokens函数性能提升、Iceberg 顺序读取#88454、SimpleAggregateFunction(anyLast)聚合查询减少内存分配与拷贝#84428。五、改进Improvement精选5.1 Keeper 相关配置被覆盖时可配置服务端级限流#74066新增keeper_server.tcp_nodelay参数可关闭 Keeper 的TCP_NODELAY#87363新增keeper_server.coordination_settings.check_node_acl_on_remove开启后删除节点前同时校验节点自身与父节点的 ACL否则只校验父节点#88513新增max_request_size对应 ZooKeeper 的jute.maxbuffer默认关闭以保持向后兼容#87952Keeper 写事务期间可检查任意节点的 stat辅助 ABA 问题检测#87282clickhouse-keeper支持连接 TLS 端口flag 命名与clickhouse-client保持一致。5.2 客户端与工具链客户端自动补全改用system.completions更快且更一致#84694clickhouse-client文件如查询历史遵循XDG Base Directories规范存放若已存在~/.clickhouse-client-history则继续使用clickhouse-benchmarkCLI flag 中可用-替代_、支持--connection复用 client 的connections_credentials配置、支持--accept-invalid-certificate、错误消息默认不再包含堆栈另有--proto-caps选项clickhouse-local可从clickhouse-server目录启动直接操作服务端数据库此前报Cannot parse UUID: .#88383新设置inject_random_order_for_select_without_order_by为顶层无ORDER BY的 SELECT 注入ORDER BY rand()。5.3 查询语义与函数完整支持操作符IS NOT DISTINCT FROM#88155mannWhitneyUTest在两样本均为相同值时不再抛异常返回与 SciPy 一致的有效结果hasToken对空 token 返回零匹配此前抛异常函数lag大小写不敏感兼容 MySQL#88322generateSerialID新增可选start_value参数且系列名支持非常量参数JSON列在Vertical格式下美化打印#88524EXCHANGE TABLES支持 Alias 引擎表#88233Replicated数据库允许无参数创建#88044跳数索引在 FINAL 查询中位于主键列时跳过跨 part 的主键交集检查#88368。5.4 文本索引新增dictionary_block_frontcoding_compression文本索引参数控制字典压缩默认启用 front-coding 压缩#87175文本索引支持Array与MapmapKeys/mapValues值支持mapContainsKey与has函数#87602hasAnyTokens/hasAllTokens新增接受字符串输入的 overload#88679。5.5 物化视图与合并物化视图插入前按min_insert_block_size_rows_for_materialized_views/min_insert_block_size_bytes_for_materialized_views跨线程合并数据避免parallel_view_processing下产生过多 parts#87280合并选择器先执行to_remove_small_parts_at_right启发式再计算合并范围分数修复宽合并选择问题#88736新增 session 设置exclude_materialize_skip_indexes_on_insert与表设置exclude_materialize_skip_indexes_on_merge排除指定跳数索引的物化。5.6 安全与可观测性使用 Backup 引擎配合 S3 存储时日志中掩码 S3 凭据#85336system.crash_log刷新改为信号处理中同步执行#87253PrometheusMetricsWriter新增直方图与维度指标#87521全局采样 profiler 默认开启每 10 秒收集所有线程的 CPU 与实时堆栈#88209新增 profile event 统计后台 merge 因内存限制被拒绝的次数#88084约束违反时的异常消息长度受限避免超长字符串写入 query_log#88801。六、Bug 修复精选官方稳定版用户可见问题6.1 日期时间修复 pre-epoch 日期带小数秒处理错误此前parseDateTime64BestEffort(1969-01-01 00:00:00.468)返回1968-12-31 23:59:59.532亚秒部分被错误减去现正确返回1969-01-01 00:00:00.468#85396toDate与toDate32对所有数值类型行为对齐修复 int16 转换时的 Date32 下溢检查#87176修复使用session_timezone时基于 datetime 键的 granule/分区剪枝错误#87987修复date_time_overflow_behavior saturate下 DateTime64 转 Date 在时区场景的越界错误#88737。6.2 查询执行与优化器修复 CTE 中计算函数结果非确定性问题#86967修复OUTER JOINoptimize_functions_to_subcolumns下可空列IS NULL行为错误#87058修复并行副本下多 JOIN尤其 RIGHT JOIN 位于 LEFT/INNER JOIN 之后的逻辑错误#87178修复新分析器中SELECT * REPLACE在 WHERE 子句过滤被替换列的错误#87630修复MergeoverDistributed的两级聚合#87687修复GLOBAL IN导致的内存泄漏#88617修复ARRAY JOIN COLUMNS()在新分析器中无匹配列时的逻辑错误#88091修复相关性子查询在对象存储上的工作问题#88290。6.3 存储与复制修复 MergeTree 表 set 列 TTL 可能导致的数据损坏#88095修复_row_number虚拟列与 iceberg positioned deletes 的逻辑错误#87220修复复制数据库在恢复后长时间卡在Failed to marked query-... as finished的问题#88671修复 Replicated 数据库恢复/清理、DDL worker 清理过期副本主机以减少 ZooKeeper 元数据#88154修复 DatabaseReplicated 未尊重interserver_http_host配置#88378ON CLUSTER查询在集群存在非活跃副本时耗时更短#88153修复从文本索引读取并启用查询条件缓存use_skip_indexes_on_data_readuse_query_condition_cache时的读取问题#88660。6.4 格式与外部系统修复 GeoParquet 导致客户端协议错误#84020修复 CSV 反序列化时类型顺序错误导致LOGICAL_ERROR#87622修复 ArrowStream 文件字典不唯一时的崩溃#87863修复 PostgreSQL 接口布尔值写入#87762、返回受影响行数#87990修复 Glue 中timestamp/timestamptz列处理#87733修复 EmbeddedRocksDB 升级问题#87392。6.5 函数与类型修复mortonEncode/hilbertEncode空 tuple 参数崩溃#88110修复countMatches二次复杂度问题#88401修复reverseUTF8错误反转 4 字节 UTF-8 码点字节序#88914修复 base32/base58 编解码缓冲区大小计算#89133修复top_k单参数时未尊重 threshold 参数#88867修复approx_top_k与finalizeAggregation的致命错误#87892修复L2DistanceTransposed的 Nullable 返回类型LOGICAL_ERROR#88974。6.6 运维与可观测性修复异步日志导致的内存泄漏10 小时约 100 GiB 漂移text_log 类似#87584修复 async logging 失败导致程序 abort#88814修复无 cgroups 环境运行 ClickHouse 时异步指标要求 cgroups 的意外问题#88164修复ColumnLowCardinality的is_shared标志传播导致的 GROUP BY 错误结果#88213。七、构建 / 测试 / 打包改进增加全文搜索索引的性能测试用例#87577测试用 PostgreSQL 升级到 18.0#87647FreeBSD 启用 ICU#87891动态分派到 sse4.2 时使用 sse4.2 而非 sse4 编译选项#88029当ENABLE_LIBFIUOFF构建时 failpoint 相关函数成为 no-opSYSTEM ENABLE/DISABLE FAILPOINT返回SUPPORT_IS_DISABLED错误#88184修复 wide_integer 在缺少std::make_pair环境下的编译错误#88498clickhouse-keeperpostinstall 脚本新增开机自启步骤#88746发布版构建默认禁用调试符号#88585。八、升级建议与运维要点综合上述变更升级到 v25.10 时应重点关注回滚策略storage_metadata_write_full_object_key强制开启回滚仅限 25.x 系列建议升级前记录当前版本并验证 25.x 回滚链路复制去重窗口replicated_deduplication_window_seconds默认 1 小时如业务有跨小时重复插入场景需显式调大在 src/Storages/MergeTree/MergeTreeSettings.cpp 中定义Keeper 升级路径若从 23.9 之前升级先升级到 23.9 再升级到 25.10或分两步切换async_replicationschema 推断Parquet/ORC/Arrow 的列可空性推断遵循元数据需回归测试依赖推断行为的任务函数重命名searchAny/searchAll更名检查代码与 SQL 中的引用缓存分段结果缓存不再因log_comment变化失效改用query_cache_tagDynamic JOIN keyJOIN 键中的 Dynamic 列需显式 CAST。九、延伸阅读本版本源码中的关键实现位置src/Functions/conv.cpp、src/Functions/FunctionNaiveBayesClassifier.cpp、src/AggregateFunctions/AggregateFunctionStudentTTestOneSample.cpp、src/AggregateFunctions/AggregateFunctionQuantilePrometheusHistogram.cpp、src/Columns/ColumnQBit.cpp、src/Storages/MergeTree/MergeTreeSettings.cpp、src/Storages/MergeTree/ReplicatedMergeTreeCleanupThread.cpp测试与验证tests/queriesstateless 查询测试、tests/integration集成测试以及 src/Functions/tests/gtest_functions_stress.cpp函数压力测试中均可找到对应特性的覆盖用例【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考