ClickHouse v25.1.1.4165-stable 版本变更深度解读新特性、不兼容变更与性能优化全览【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本文基于仓库中的 v25.1.1.4165-stable 发布说明 编写系统梳理该稳定版相对 v25.1.1.1-new 的全部关键变更。读完后你将掌握本次升级中所有需要适配的不兼容行为、可直接启用的新函数与新语法如generateSerialID、PARALLEL WITH、apply_mutations_on_fly以及一批值得关注的性能优化与缺陷修复并能在升级 25.1 分支前完成影响评估与回滚开关配置。一、版本定位25.1 稳定分支的点发布该发布说明的标题为ClickHouse release v25.1.1.4165-stable (8629bc54796) FIXME as compared to v25.1.1.1-new (204fd5b5431)说明它是 25.1 稳定线上的一次点发布point release基线为 25.1.1.1构建提交为8629bc54796。发布说明按 ClickHouse 惯例分为以下几大类本文按此脉络逐类展开Backward Incompatible Change不兼容变更——升级前必须评估的行为变化New Feature新特性——可直接使用的新能力Performance Improvement性能优化——无行为变化但执行更快Improvement改进——功能增强、参数语义调整、输出格式美化等Bug Fix——用户可见的行为错误修复Build/Testing/Packaging Improvement——构建与测试侧改进NO CL ENTRY / NOT FOR CHANGELOG——内部变更不影响使用仅在此列出其存在。下面对每一类中影响面最大的条目做逐条讲解并结合当前仓库源码印证其实现位置。二、不兼容变更升级前必须逐条评估2.1 Parquet 输出格式改为标准 date/time 类型变更内容Parquet 输出格式不再把 Date/DateTime 写成裸数值而是转换为 Parquet 原生支持的时间类型——DateTime 由 UInt32 变为DateTime64(3)Date 由 UInt16 变为Date32。若需恢复旧行为可设置output_format_parquet_datetime_as_uint32PR #70950Michael Kolupaev。影响评估所有依赖「Parquet 里 DateTime 是 32 位整数」语义的下游 ETL 都会受影响比如用 Pandas/Spark 读取时列类型变化。该设置目前仍保留在源码中定义于 FormatFactorySettings并在 FormatFactory 中参与输出格式构建说明官方通过设置项保留了向后兼容通道。2.2 ORDER BY 与比较函数默认禁止不可比较类型变更内容默认不再允许 JSON/Object/AggregateFunction 等不可比较类型出现在ORDER BY和less/greater/equal等比较函数中PR #73276Pavel Kruglov。影响评估这是对 25.1 新分析器analyzer语义收紧的延续。升级后类似SELECT ... FROM json_table ORDER BY json.col的语句会直接报错而非隐式按某种规则排序。从 Settings.cpp 中保留的allow_non_comparable_types_in_order_by兼容开关可以推断老行为仍可显式开启建议先用报错排查存量查询再决定是否放宽。2.3 JSONEachRowWithProgress 进度上报时机改变变更内容PR #73834Alexey Milovidov进度事件在进度实际发生时就写出而不是等每个结果块结束后才输出旧行为基本没有实用价值。同时不再显示零值。官方特别提醒进度事件可能非常频繁会显著增加流量输出被压缩时进度不会被即时刷出。后续在 Improvement 一节中PR #74181该格式还做了增强包含 metadata 事件、totals/extremes、rows_before_limit_at_least与rows_before_aggregation进度包含纳秒级 elapsed且运行期进度打印频率不超过interactive_delay的取值。对依赖该格式做前端进度展示的客户端例如 Play UI而言是正向改进但需要处理更高频的事件流。2.4 移除 MaterializedMySQL 数据库引擎变更内容过时的MaterializedMySQL引擎被彻底移除不再可用PR #73879。内部变更一节中亦有对应动作「Remove tests for MaterializedMySQL」#73828印证测试资产同步清理。影响评估如果你的建表语句中还有ENGINE MaterializedMySQL(...)升级后建表会直接失败。MySQL 数据接入应改用mysql()表函数或MySQL字典等现存方案。2.5 mysql 字典源不再执行 SHOW TABLE STATUS变更内容mysql字典源不再发起SHOW TABLE STATUS查询因为对 InnoDB 表它本来就不提供有效信息PR #73914。官方标注「向后兼容但放进此分类以便你注意到」。实操建议排查字典加载延迟时可以确认这一点——旧版本每次刷新都会多一次全库SHOW TABLE STATUS现在没有了。2.6 Merge 引擎统一底层表结构变更内容PR #73956Merge表现在会用底层各表列的并集推导公共类型来统一结构issue #64864 的诉求。在少数情况下这不兼容例如两表没有公共类型但可转换到第一张表的类型如 UInt64 与 Int64或数值类型与 String时结果类型会与旧行为不同。回退手段是设置merge_table_max_tables_to_look_for_schema_inference 1或将compatibility设为24.12或更早。源码印证该设置由 StorageMerge 与 TableFunctionMerge 共同消费说明无论是Merge表引擎还是merge()表函数都遵循同一套结构推导逻辑。2.7 CHECK TABLE 需要独立 CHECK 权限变更内容CHECK TABLE查询从「只需SHOW TABLES权限」改为需要独立的CHECK权限PR #74471。官方解释了动机CHECK TABLE可能很重而 SELECT 查询的常规复杂度限制对它不适用存在 DoS 风险。影响评估这是一项权限收紧运维脚本、BI 工具中所有只授予SHOW的角色升级后都会失去执行CHECK TABLE的能力需要提前GRANT CHECK。2.8 h3ToGeo() 返回顺序改为 (lat, lon)变更内容h3ToGeo()现按几何函数标准顺序返回(lat, lon)需要旧顺序(lon, lat)的可设置h3togeo_lon_lat_result_order truePR #74719。源码印证实现位于 h3toGeo.cpp设置声明在 Settings.cpp 中。升级后所有 H3 网格转坐标的下游坐标写入顺序都会对调这是典型的「静默数据错误」陷阱务必在升级 checklist 中单列。三、新特性本次发布的核心增量3.1 SSH 交互接口注意本版本中默认禁用变更内容新增 SSH 接口可以用任意 SSH 客户端连接 ClickHouse 服务器通过 PTY 与内嵌的 clickhouse-client 交互执行查询PR #48902George Gamezardashvili。关键限制内部变更一节中的「Disable SSH server (unreleased)」#74473Alexey Milovidov明确说明该功能在 4165 这个构建中被禁用了——即 SSH 代码已合入但默认不开放。可以推断该特性处于谨慎启用阶段升级后不要依赖它作为生产访问通道HTTP/TCP 仍是官方支持面。3.2 跳过索引 granule 反序列化内存缓存变更内容PR #70102Robert Schulze为反序列化后的 skipping index granule 增加内存缓存使重复使用跳过索引的查询更快缓存大小由服务器设置skipping_index_cache_size与skipping_index_cache_max_entries控制。官方动机是向量相似度索引——引入缓存后「快了很多」。实践价值对大量小查询反复命中同一批倒排/向量索引的 OLAP 场景这两项服务器设置是新的调优入口同时意味着服务器常驻内存占用会上升需要纳入容量规划。3.3 Iceberg 时间类分区裁剪变更内容PR #72044Daniil Ivanik对 Iceberg 表中基于时间转换如toYYYYMM(ts)的分区字段实现分区裁剪partition pruning。这意味着对WHERE时间谓词引擎可以直接跳过不匹配的 Iceberg 分区文件而无需读元数据后全量过滤。配套的内部重构Iceberg 元数据代码封装PR #72941说明这是一条会持续演进的功能线。3.4 MergeTree 全列默认 min-max 索引默认关闭变更内容PR #72090 / #74266Smita Kulkarni新增enable_minmax_index_for_all_numeric_columns数值列与enable_minmax_index_for_all_string_columns字符串列两个设置可为 MergeTree 管理的列默认创建 min-max 跳过索引。官方明确两个设置当前均为关闭暂不改变行为。内部变更中还有一条「Revert Add minmax indices by default」#74264 随后被重新提交#74266说明该特性经历了一次回滚重做上线态度非常谨慎。使用建议列数多、每列选择性差异大的表可以先开启试试减少手工INDEX ... TYPE minmax的建表噪音代价是 part 元数据与索引文件的膨胀。3.5 sequenceMatchEvents 聚合函数变更内容PR #72349UnamedRus新增聚合函数sequenceMatchEvents返回 pattern 中最长匹配事件链对应的时间戳。这是序列挖掘sessionization/funnel 时间还原场景的补齐能力sequenceMatch家族原来只能告诉「是否匹配/匹配了什么」现在可以直接拿到每个匹配事件发生的时间。3.6 SELECT / VIEW 支持列别名变更内容PR #72480Yarik BriukhovetskyiSELECT与VIEW语句现支持形参式列别名官方示例SELECT b FROM (SELECT number, number*2 FROM numbers(2)) AS x (a, b);官方特别指出这让TPC-H 查询 15 可以不修改直接运行——TPC-H 15 的ViewDefinition1正是CREATE VIEW revenue01 AS (s_suppkey AS supplier_no, ...) AS revenue01 (supplier_no, total_revenue);这种带列名列表的视图定义此前是 ClickHouse 跑 TPC-H 标准脚本的拦路虎之一。3.7 generateSerialID基于 Keeper 的自增序列变更内容PR #73950Alexey Milovidov新增函数generateSerialID用于在表中生成自增编号延续 #64310 的提案。源码级实现实现位于 generateSerialID.cpp从源码可以确认其工作方式函数注册名为generateSerialIDFunctionSerialisStateful() true、isDeterministic() false不可常量折叠构造时从服务器设置series_keeper_path读取 Keeper 上的序列存储路径从查询设置max_autoincrement_series读取允许的序列数量上限依赖Common/ZooKeeper的ZooKeeper客户端完成序列号的原子分配。即该函数把「自增」交给 Keeper 的一致性存储实现适合多分片场景下需要全局递增 ID 的表同时它声明为非确定性、状态相关函数不能被物化/缓存。3.8 PARALLEL WITH 并行子查询语法变更内容PR #73983Vitaly Baranov新增语法query1 PARALLEL WITH query2 PARALLEL WITH queryN语义是「子查询{query1, ..., queryN}允许且期望彼此并行执行」。源码印证解析器实现在 ParserParallelWithQuery.cpp 与 AST 节点 ASTParallelWithQuery.h已挂在 ParserSelectQuery.cpp 的选择查询解析链路上。典型用途是把多个独立的INSERT/大查询显式声明为并行任务避免解释器因保守调度串行化它们。3.9 apply_mutations_on_fly查询提交后立即应用未完成 mutation变更内容PR #74877Anton Popov已回移 #75020新增设置apply_mutations_on_fly默认false声明于 Settings.cpp允许在SELECT提交后立即应用尚未被后台进程物化完成的 mutation。影响面从源码看该设置贯穿查询执行主链路——executeQuery.cpp、MergeTreeSelectProcessor、MergeTreeReadTask 与 MutateTask 均有引用属于「读取时按需等待/应用 mutation」的较深改动。适用场景ALTER TABLE ... UPDATE/DELETE后马上读数据的老痛点mutation 要排队等后台池读到的还是旧值。开启后查询延迟会包含 mutation 应用成本官方把它做成显式开关而非默认行为正是为了把这部分代价交给使用者决策。3.10 Play UI 大改版变更内容PR #74204Web 端 Play UI 一次大升级包含查询运行期进度条支持取消查询显示总行数与速度等扩展信息表格增量渲染数据到达即绘制启用 HTTP 压缩渲染更快表头吸顶sticky header可选中单元格并用方向键导航鼠标悬停列头显示数据类型数字按三位分组高亮正确渲染 inf/nan 与嵌套类型中的大整数连接前校验服务器可达性与凭据正确性显示服务器版本与运行时长uptime。配合同批的 #74201即使 HTTP 响应被压缩也尽快发包让浏览器收到进度包与压缩数据与 #74182沙漏平滑转动Play UI 从「一次性出结果」变成了流式查询控制台。3.11 其他值得知道的新能力特性说明关键设置/前提arrayNormalizedGini函数新增数组归一化 Gini 系数PR #72823直接可用HALF_FLOAT 读取从 Apache Arrow/Parquet/ORC 读取 half float读入 Float32PR #73836注意 IEEE-754 half float 不等于 BFloat16无需配置system.trace_log符号化新增symbols、lines两列存符号化栈便于采集导出 profile 信息PR #73896服务器配置trace_log下的symbolize默认开启force merge 忽略字节上限min_age_to_force_merge_seconds与min_age_to_force_merge_on_partition_only同时开启时强制合并忽略 max bytes 限制PR #73656两个 MergeTree 设置同时为真DateTime64 减号运算支持 DateTime64及 DateTime之间的减法PR #74482直接可用客户端 CtrlDclickhouse-client 支持 CtrlD 结束查询单行模式下等价于回车PR #73293直接可用其中system.trace_log的新列对做「服务内 CPU 热点自助定位」的团队非常实用不用再去服务器手动 symbolize直接 SQL 导出可读栈即可。四、Improvement行为增强与参数语义调整本节条目最多下面按主题分组讲清楚哪些会改变你现有系统的行为。4.1 外部排序内存语义调整max_bytes_before_external_sort的语义从「单个排序线程排序块字节数」改为整个查询所有线程的总内存上限与max_bytes_before_external_group_by对齐同时新增min_external_sort_block_bytes控制落盘块大小PR #72598Azat Khuzhin。注意如果你之前按单块语义调过该值升级后触发外排的时机会变同等设置下更晚触发需要重新校准。4.2 JSON / Dynamic 类型能力扩展支持不同参数 JSON 类型之间的 CAST 与 ALTER#72303支持 JSON 列值的等值比较#72991修复嵌套 JSON 空键解析、Dynamic/Object 结构反序列化导致的CANNOT_READ_ALL_DATA#73993、#73767排序键与跳过索引支持 subcolumn#72644——这是对 JSON 场景排序键的重要补齐Materialized View 的 SELECT 查询支持 subcolumn#74030。4.3 权限模型变化升级必查ALTER TABLE MOVE PARTITION TO TABLE改用专门的ALTER_MOVE_PARTITION权限为兼容若已授予SELECTALTER DELETE则隐式获得但官方声明未来版本会移除该隐式授予#71632。存量账号要显式补ALTER_MOVE_PARTITION。CREATE_USER/ALTER_USER/DROP_USER/CREATE_ROLE/ALTER_ROLE/DROP_ROLE六个权限从全局型改为参数化可限定具体用户/角色对象#72246system.query_log新增script_query_number、script_line_number字段脚本执行到第几条/第几行同步加入 native 协议 ClientInfo 与服务端日志#74477——脚本审计粒度更细。4.4 输出格式体验包Pretty 系列这批改动显著改善了终端可读性且全部带开关行为控制设置PRPretty 格式默认开启列尾空格高亮output_format_pretty_highlight_trailing_spaces#73847长列名默认截断output_format_pretty_max_column_name_width_cut_to/output_format_pretty_max_column_name_width_min_chars_to_cut#73851相邻块时间间隔短则合并显示output_format_pretty_squash_consecutive_ms默认 50ms/output_format_pretty_squash_max_wait_ms默认 1000ms#73852Vertical 格式对列名着色输出到终端时output_format_pretty_color#73898结果超过 N 行时改为「前 N/2 后 N/2」而非只显示前 N 行output_format_pretty_max_rows#73929表格单元格内渲染多行字段output_format_pretty_multiline_fields默认开#74032JSON 输出格式默认 prettyoutput_format_json_pretty_print默认开#72148此外终端下误请求二进制格式Native/Parquet/Avro 等时客户端会先询问确认#73833——脚本里要注意关闭交互或重定向确认避免 CI 卡住。4.5 客户端与协议增强Postgres wire protocol 支持 TLS#73812MySQL 兼容层增强到mysqlshOracle 的富功能 MySQL CLI可直接连接 ClickHouse#73912MySQL 协议错误码也对齐 MySQL 语义#73948clickhouse-client / clickhouse-local 自动识别从文件重定向 stdin 的压缩#73848例如clickhouse-local --query ... data.tsv.gz不再需要先手动 gunzip客户端支持三种方式设置自定义提示符命令行--prompt、配置文件prompt、以及 per-connection 设置#74168连接 9440 端口时自动启用安全连接#74212浏览器场景默认用户需要密码时服务器返回 HTTP 401 触发浏览器交互式凭据输入原来直接 403#72198HTTP handler 可仅以用户名认证#74221X-ClickHouse 响应头暴露给浏览器 JS#74180。4.6 数据湖与队列引擎S3(Azure)Queue存储引擎一批增强允许补设置、commit 设置可 ALTERmax_processed_files_before_commit/max_processed_rows_before_commit/max_processed_bytes_before_commit/max_processing_time_sec_before_commit、多源进度聚合比对 commit 限制、单批文件在同一 Keeper 事务内提交、旧 24.6 结构表迁移到新 bucket 结构#73283、#73635、#73641、#73991、#73467新增system.azure_queue表与system.s3queue对齐#73477新 MongoDB 驱动成为默认想沿用旧驱动可设服务器设置use_legacy_mongodb_integration true#73359内部变更中该旧设置已标记 obsolete #73253use_hive_partitioning默认开启#71636实验标记移除见内部变更 #74065BACKUP/RESTORE支持 core 设置与max_backup_bandwidth#73650、#72665并新增Memory仅当前会话保留与Null不落任何位置两种备份引擎#73690跨云 BACKUP 写尊重 IO 调度设置#71093Azure SAS Token 支持#729594.7 优化器/执行器增强哈希 join 启用时允许更通用的 join 规划算法#71926MergingAggregated步骤支持查询计划层的 predicate push-down#74073析取式公共子表达式提取改进即使不是所有析取项都有公共子表达式也能简化最终过滤表达式#73271EXPLAIN PLAN新增distributed选项EXPLAIN distributed1 ...会把远端计划追加到ReadFromParallelRemote*步骤#73994新分析器下为分布式子查询引入 AST 级谓词下推开关allow_push_predicate_ast_for_distributed_subqueries#74085官方注明这是查询计划序列化落地前的临时方案OPTIMIZE TABLE支持FORCE关键字作为FINAL的替代写法#74342新增 MergeTree 设置materialize_skip_indexes_on_merge抑制合并期间建跳过索引允许通过ALTER TABLE ... MATERIALIZE INDEX显式控制——对向量相似度索引这类构建昂贵的索引很有用#74401PRQL 与 KQL 两种替代查询语言标记为实验性需allow_experimental_prql_dialect 1/allow_experimental_kusto_dialect 1#74224LowCardinality(UUID)默认放行#73826BFloat16数据类型宣布生产可用#73840。4.8 其他值得留意的行为微调least/greatest对 NULL 的默认处理改为忽略 NULL旧行为是任一参数为 NULL 即返回 NULL旧行为可用least_greatest_legacy_null_behavior true恢复#73344formatDateTime的%f现在无条件输出 6 位亚秒数字对齐 MySQLDATE_FORMAT旧行为可用formatdatetime_f_prints_scale_number_of_digits 1恢复#73324parseDateTime64家族对 1970 年之前 / 2106 年之后日期返回正确结果#73594排序键列上 materialize 列改为抛异常而非破坏排序顺序#71891concurrent_threads_soft_limit_num与concurrent_threads_soft_limit_num_ratio_to_cores可不重启热改#73713Keeper 侧客户端可用密码访问 keeper限 16 字符以内与 Keeper Auth 模型无关#74673MySQL/PostgreSQL 表函数与引擎支持 IPv6 地址#74796。五、性能优化无行为变化的提速优化说明PR行比较从最可能不等的列开始排序/去重场景提前短路#63780RowBinary 输入格式优化解析更快#65059字符串反序列化底层优化常见 String 列读取提速#65948grace hash join 右表按键重排右表局部性更好#72237arrayROCAUC/arrayAUCPR支持部分曲面积分可在大数据集上并行计算#72904避免生成过多空闲线程减少调度开销#72920parallel_hashJOIN 探测阶段移除左表哈希分块省去一次切分#73089仅花括号展开的表函数不再列举 blob 存储键减少 ListObjects 调用#73518Nullable 短路执行 纯数值参数快路径修复 #72258 的性能回退#73820maskedExecute不再作用于非函数列短路执行更高效#73965Kafka/NATS/RabbitMQ/FileLog 关闭 header 探测减少首行消耗与探测逻辑#74006日志 wrapper 按值使用、不堆分配减少小对象分配#74034带 grouping sets 的聚合后以更高并行度执行管线后段并行度提升#74082MergeTreeReadPool临界区缩小减少读池锁竞争#74202indexHint优化仅作为 indexHint 参数出现的列不再读表减少 IO#74314并行副本非协议包反序列化固定发生在管线线程initiator 更响应#74398LowCardinality列内存占用计算修正内存核算更准#74688其中indexHint的优化#74314对「用indexHint圈定范围再聚合」的高基数列查询是直接收益——hint 列本身不再产生磁盘读取。六、Bug Fix 中的高优先级项完整修复清单很长此处只挑影响面大或涉及安全的几条其余见原文档安全修复postgresql与sqlite表函数中的SQL 注入问题#74144Pablo Marcos。使用这两个表函数的环境应尽快升级。权限通配授权下的部分 REVOKE 可能多删权限#74751列级GRANT SELECT/INSERT作用于通配库表时现在报错#72646REVOKE ALL ON *.*因隐式授予而失败的问题修复#72872。稳定性CREATE TABLE ... ENGINE Loop组合此前会段错误现在直接禁止#74137system.detached_tables的查询无限循环修复#74190FINALSAMPLE的NOT_FOUND_COLUMN_IN_BLOCK与 CollapsingMergeTree FINAL 错误结果修复#73682Dynamic 列Nested columns sizes are inconsistent逻辑错误修复#73644读取 gzip 数据偶发因客户端解压缺陷失败修复#74707。Keeper修复从磁盘读取日志条目的 bug#74785、开启 Cluster Discovery 时 watch 泄漏#74521、表创建期间 KeeperMap 并发清理#74568。ObjectStorage 队列一系列崩溃/逻辑错误修复#73274、#73420、#73546、#74216、#74892 等。备份恢复RESTORE恢复 part 时跳过metadata_version.txt#73768跨凭据的 S3 复制修复#74331RESTORE基线备份的 native copy 设置修复#74286。七、构建与打包改进内部依赖LLVM 从 16 升级到 18#66053——对源码编译用户意味着对工具链的新要求/行为变化修复 contrib openssl asm 文件生成问题#72622通用安装脚本universal installation script现在在 macOS 上也会提议安装#74339未启用 kerberos 时构建失败的问题修复#74771。八、升级行动清单基于上述变更25.1.1.1 升级到 4165 的建议检查顺序不兼容项逐一过Parquet 输出下游列类型#2.1、ORDER BYJSON/Object 报错#2.2、MaterializedMySQL建表#2.4、Merge表结构推导#2.6必要时merge_table_max_tables_to_look_for_schema_inference 1或compatibility回退、h3ToGeo坐标顺序#2.8必要时h3togeo_lon_lat_result_order true权限补齐给需要CHECK TABLE的角色授予CHECK#2.7给有搬分区需求的角色显式授予ALTER_MOVE_PARTITION#4.3参数重校准max_bytes_before_external_sort语义变化#4.1least_greatest_legacy_null_behavior/formatdatetime_f_prints_scale_number_of_digits两个回退开关按需打开#4.8安全项使用postgresql/sqlite表函数的部署优先升级#74144新功能试点generateSerialID需可用 Keeper、PARALLEL WITH、apply_mutations_on_fly注意查询延迟代价、skipping_index_cache_*两项服务器设置调优均按小流量验证后推广不要依赖 SSH 接口作为升级后的访问方式——本构建中默认禁用#74473。以上所有条目均可在原文档 v25.1.1.4165-stable 发布说明 中按 PR 号与作者完整追溯本文引用的源码位置如 Settings.cpp、StorageMerge.cpp、generateSerialID.cpp、ParserParallelWithQuery.cpp位于当前仓库快照行号与行为可能随后续提交变化核对时请以实际检出版本为准。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ClickHouse v25.1.1.4165-stable 版本变更深度解读：新特性、不兼容变更与性能优化全览
ClickHouse v25.1.1.4165-stable 版本变更深度解读新特性、不兼容变更与性能优化全览【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本文基于仓库中的 v25.1.1.4165-stable 发布说明 编写系统梳理该稳定版相对 v25.1.1.1-new 的全部关键变更。读完后你将掌握本次升级中所有需要适配的不兼容行为、可直接启用的新函数与新语法如generateSerialID、PARALLEL WITH、apply_mutations_on_fly以及一批值得关注的性能优化与缺陷修复并能在升级 25.1 分支前完成影响评估与回滚开关配置。一、版本定位25.1 稳定分支的点发布该发布说明的标题为ClickHouse release v25.1.1.4165-stable (8629bc54796) FIXME as compared to v25.1.1.1-new (204fd5b5431)说明它是 25.1 稳定线上的一次点发布point release基线为 25.1.1.1构建提交为8629bc54796。发布说明按 ClickHouse 惯例分为以下几大类本文按此脉络逐类展开Backward Incompatible Change不兼容变更——升级前必须评估的行为变化New Feature新特性——可直接使用的新能力Performance Improvement性能优化——无行为变化但执行更快Improvement改进——功能增强、参数语义调整、输出格式美化等Bug Fix——用户可见的行为错误修复Build/Testing/Packaging Improvement——构建与测试侧改进NO CL ENTRY / NOT FOR CHANGELOG——内部变更不影响使用仅在此列出其存在。下面对每一类中影响面最大的条目做逐条讲解并结合当前仓库源码印证其实现位置。二、不兼容变更升级前必须逐条评估2.1 Parquet 输出格式改为标准 date/time 类型变更内容Parquet 输出格式不再把 Date/DateTime 写成裸数值而是转换为 Parquet 原生支持的时间类型——DateTime 由 UInt32 变为DateTime64(3)Date 由 UInt16 变为Date32。若需恢复旧行为可设置output_format_parquet_datetime_as_uint32PR #70950Michael Kolupaev。影响评估所有依赖「Parquet 里 DateTime 是 32 位整数」语义的下游 ETL 都会受影响比如用 Pandas/Spark 读取时列类型变化。该设置目前仍保留在源码中定义于 FormatFactorySettings并在 FormatFactory 中参与输出格式构建说明官方通过设置项保留了向后兼容通道。2.2 ORDER BY 与比较函数默认禁止不可比较类型变更内容默认不再允许 JSON/Object/AggregateFunction 等不可比较类型出现在ORDER BY和less/greater/equal等比较函数中PR #73276Pavel Kruglov。影响评估这是对 25.1 新分析器analyzer语义收紧的延续。升级后类似SELECT ... FROM json_table ORDER BY json.col的语句会直接报错而非隐式按某种规则排序。从 Settings.cpp 中保留的allow_non_comparable_types_in_order_by兼容开关可以推断老行为仍可显式开启建议先用报错排查存量查询再决定是否放宽。2.3 JSONEachRowWithProgress 进度上报时机改变变更内容PR #73834Alexey Milovidov进度事件在进度实际发生时就写出而不是等每个结果块结束后才输出旧行为基本没有实用价值。同时不再显示零值。官方特别提醒进度事件可能非常频繁会显著增加流量输出被压缩时进度不会被即时刷出。后续在 Improvement 一节中PR #74181该格式还做了增强包含 metadata 事件、totals/extremes、rows_before_limit_at_least与rows_before_aggregation进度包含纳秒级 elapsed且运行期进度打印频率不超过interactive_delay的取值。对依赖该格式做前端进度展示的客户端例如 Play UI而言是正向改进但需要处理更高频的事件流。2.4 移除 MaterializedMySQL 数据库引擎变更内容过时的MaterializedMySQL引擎被彻底移除不再可用PR #73879。内部变更一节中亦有对应动作「Remove tests for MaterializedMySQL」#73828印证测试资产同步清理。影响评估如果你的建表语句中还有ENGINE MaterializedMySQL(...)升级后建表会直接失败。MySQL 数据接入应改用mysql()表函数或MySQL字典等现存方案。2.5 mysql 字典源不再执行 SHOW TABLE STATUS变更内容mysql字典源不再发起SHOW TABLE STATUS查询因为对 InnoDB 表它本来就不提供有效信息PR #73914。官方标注「向后兼容但放进此分类以便你注意到」。实操建议排查字典加载延迟时可以确认这一点——旧版本每次刷新都会多一次全库SHOW TABLE STATUS现在没有了。2.6 Merge 引擎统一底层表结构变更内容PR #73956Merge表现在会用底层各表列的并集推导公共类型来统一结构issue #64864 的诉求。在少数情况下这不兼容例如两表没有公共类型但可转换到第一张表的类型如 UInt64 与 Int64或数值类型与 String时结果类型会与旧行为不同。回退手段是设置merge_table_max_tables_to_look_for_schema_inference 1或将compatibility设为24.12或更早。源码印证该设置由 StorageMerge 与 TableFunctionMerge 共同消费说明无论是Merge表引擎还是merge()表函数都遵循同一套结构推导逻辑。2.7 CHECK TABLE 需要独立 CHECK 权限变更内容CHECK TABLE查询从「只需SHOW TABLES权限」改为需要独立的CHECK权限PR #74471。官方解释了动机CHECK TABLE可能很重而 SELECT 查询的常规复杂度限制对它不适用存在 DoS 风险。影响评估这是一项权限收紧运维脚本、BI 工具中所有只授予SHOW的角色升级后都会失去执行CHECK TABLE的能力需要提前GRANT CHECK。2.8 h3ToGeo() 返回顺序改为 (lat, lon)变更内容h3ToGeo()现按几何函数标准顺序返回(lat, lon)需要旧顺序(lon, lat)的可设置h3togeo_lon_lat_result_order truePR #74719。源码印证实现位于 h3toGeo.cpp设置声明在 Settings.cpp 中。升级后所有 H3 网格转坐标的下游坐标写入顺序都会对调这是典型的「静默数据错误」陷阱务必在升级 checklist 中单列。三、新特性本次发布的核心增量3.1 SSH 交互接口注意本版本中默认禁用变更内容新增 SSH 接口可以用任意 SSH 客户端连接 ClickHouse 服务器通过 PTY 与内嵌的 clickhouse-client 交互执行查询PR #48902George Gamezardashvili。关键限制内部变更一节中的「Disable SSH server (unreleased)」#74473Alexey Milovidov明确说明该功能在 4165 这个构建中被禁用了——即 SSH 代码已合入但默认不开放。可以推断该特性处于谨慎启用阶段升级后不要依赖它作为生产访问通道HTTP/TCP 仍是官方支持面。3.2 跳过索引 granule 反序列化内存缓存变更内容PR #70102Robert Schulze为反序列化后的 skipping index granule 增加内存缓存使重复使用跳过索引的查询更快缓存大小由服务器设置skipping_index_cache_size与skipping_index_cache_max_entries控制。官方动机是向量相似度索引——引入缓存后「快了很多」。实践价值对大量小查询反复命中同一批倒排/向量索引的 OLAP 场景这两项服务器设置是新的调优入口同时意味着服务器常驻内存占用会上升需要纳入容量规划。3.3 Iceberg 时间类分区裁剪变更内容PR #72044Daniil Ivanik对 Iceberg 表中基于时间转换如toYYYYMM(ts)的分区字段实现分区裁剪partition pruning。这意味着对WHERE时间谓词引擎可以直接跳过不匹配的 Iceberg 分区文件而无需读元数据后全量过滤。配套的内部重构Iceberg 元数据代码封装PR #72941说明这是一条会持续演进的功能线。3.4 MergeTree 全列默认 min-max 索引默认关闭变更内容PR #72090 / #74266Smita Kulkarni新增enable_minmax_index_for_all_numeric_columns数值列与enable_minmax_index_for_all_string_columns字符串列两个设置可为 MergeTree 管理的列默认创建 min-max 跳过索引。官方明确两个设置当前均为关闭暂不改变行为。内部变更中还有一条「Revert Add minmax indices by default」#74264 随后被重新提交#74266说明该特性经历了一次回滚重做上线态度非常谨慎。使用建议列数多、每列选择性差异大的表可以先开启试试减少手工INDEX ... TYPE minmax的建表噪音代价是 part 元数据与索引文件的膨胀。3.5 sequenceMatchEvents 聚合函数变更内容PR #72349UnamedRus新增聚合函数sequenceMatchEvents返回 pattern 中最长匹配事件链对应的时间戳。这是序列挖掘sessionization/funnel 时间还原场景的补齐能力sequenceMatch家族原来只能告诉「是否匹配/匹配了什么」现在可以直接拿到每个匹配事件发生的时间。3.6 SELECT / VIEW 支持列别名变更内容PR #72480Yarik BriukhovetskyiSELECT与VIEW语句现支持形参式列别名官方示例SELECT b FROM (SELECT number, number*2 FROM numbers(2)) AS x (a, b);官方特别指出这让TPC-H 查询 15 可以不修改直接运行——TPC-H 15 的ViewDefinition1正是CREATE VIEW revenue01 AS (s_suppkey AS supplier_no, ...) AS revenue01 (supplier_no, total_revenue);这种带列名列表的视图定义此前是 ClickHouse 跑 TPC-H 标准脚本的拦路虎之一。3.7 generateSerialID基于 Keeper 的自增序列变更内容PR #73950Alexey Milovidov新增函数generateSerialID用于在表中生成自增编号延续 #64310 的提案。源码级实现实现位于 generateSerialID.cpp从源码可以确认其工作方式函数注册名为generateSerialIDFunctionSerialisStateful() true、isDeterministic() false不可常量折叠构造时从服务器设置series_keeper_path读取 Keeper 上的序列存储路径从查询设置max_autoincrement_series读取允许的序列数量上限依赖Common/ZooKeeper的ZooKeeper客户端完成序列号的原子分配。即该函数把「自增」交给 Keeper 的一致性存储实现适合多分片场景下需要全局递增 ID 的表同时它声明为非确定性、状态相关函数不能被物化/缓存。3.8 PARALLEL WITH 并行子查询语法变更内容PR #73983Vitaly Baranov新增语法query1 PARALLEL WITH query2 PARALLEL WITH queryN语义是「子查询{query1, ..., queryN}允许且期望彼此并行执行」。源码印证解析器实现在 ParserParallelWithQuery.cpp 与 AST 节点 ASTParallelWithQuery.h已挂在 ParserSelectQuery.cpp 的选择查询解析链路上。典型用途是把多个独立的INSERT/大查询显式声明为并行任务避免解释器因保守调度串行化它们。3.9 apply_mutations_on_fly查询提交后立即应用未完成 mutation变更内容PR #74877Anton Popov已回移 #75020新增设置apply_mutations_on_fly默认false声明于 Settings.cpp允许在SELECT提交后立即应用尚未被后台进程物化完成的 mutation。影响面从源码看该设置贯穿查询执行主链路——executeQuery.cpp、MergeTreeSelectProcessor、MergeTreeReadTask 与 MutateTask 均有引用属于「读取时按需等待/应用 mutation」的较深改动。适用场景ALTER TABLE ... UPDATE/DELETE后马上读数据的老痛点mutation 要排队等后台池读到的还是旧值。开启后查询延迟会包含 mutation 应用成本官方把它做成显式开关而非默认行为正是为了把这部分代价交给使用者决策。3.10 Play UI 大改版变更内容PR #74204Web 端 Play UI 一次大升级包含查询运行期进度条支持取消查询显示总行数与速度等扩展信息表格增量渲染数据到达即绘制启用 HTTP 压缩渲染更快表头吸顶sticky header可选中单元格并用方向键导航鼠标悬停列头显示数据类型数字按三位分组高亮正确渲染 inf/nan 与嵌套类型中的大整数连接前校验服务器可达性与凭据正确性显示服务器版本与运行时长uptime。配合同批的 #74201即使 HTTP 响应被压缩也尽快发包让浏览器收到进度包与压缩数据与 #74182沙漏平滑转动Play UI 从「一次性出结果」变成了流式查询控制台。3.11 其他值得知道的新能力特性说明关键设置/前提arrayNormalizedGini函数新增数组归一化 Gini 系数PR #72823直接可用HALF_FLOAT 读取从 Apache Arrow/Parquet/ORC 读取 half float读入 Float32PR #73836注意 IEEE-754 half float 不等于 BFloat16无需配置system.trace_log符号化新增symbols、lines两列存符号化栈便于采集导出 profile 信息PR #73896服务器配置trace_log下的symbolize默认开启force merge 忽略字节上限min_age_to_force_merge_seconds与min_age_to_force_merge_on_partition_only同时开启时强制合并忽略 max bytes 限制PR #73656两个 MergeTree 设置同时为真DateTime64 减号运算支持 DateTime64及 DateTime之间的减法PR #74482直接可用客户端 CtrlDclickhouse-client 支持 CtrlD 结束查询单行模式下等价于回车PR #73293直接可用其中system.trace_log的新列对做「服务内 CPU 热点自助定位」的团队非常实用不用再去服务器手动 symbolize直接 SQL 导出可读栈即可。四、Improvement行为增强与参数语义调整本节条目最多下面按主题分组讲清楚哪些会改变你现有系统的行为。4.1 外部排序内存语义调整max_bytes_before_external_sort的语义从「单个排序线程排序块字节数」改为整个查询所有线程的总内存上限与max_bytes_before_external_group_by对齐同时新增min_external_sort_block_bytes控制落盘块大小PR #72598Azat Khuzhin。注意如果你之前按单块语义调过该值升级后触发外排的时机会变同等设置下更晚触发需要重新校准。4.2 JSON / Dynamic 类型能力扩展支持不同参数 JSON 类型之间的 CAST 与 ALTER#72303支持 JSON 列值的等值比较#72991修复嵌套 JSON 空键解析、Dynamic/Object 结构反序列化导致的CANNOT_READ_ALL_DATA#73993、#73767排序键与跳过索引支持 subcolumn#72644——这是对 JSON 场景排序键的重要补齐Materialized View 的 SELECT 查询支持 subcolumn#74030。4.3 权限模型变化升级必查ALTER TABLE MOVE PARTITION TO TABLE改用专门的ALTER_MOVE_PARTITION权限为兼容若已授予SELECTALTER DELETE则隐式获得但官方声明未来版本会移除该隐式授予#71632。存量账号要显式补ALTER_MOVE_PARTITION。CREATE_USER/ALTER_USER/DROP_USER/CREATE_ROLE/ALTER_ROLE/DROP_ROLE六个权限从全局型改为参数化可限定具体用户/角色对象#72246system.query_log新增script_query_number、script_line_number字段脚本执行到第几条/第几行同步加入 native 协议 ClientInfo 与服务端日志#74477——脚本审计粒度更细。4.4 输出格式体验包Pretty 系列这批改动显著改善了终端可读性且全部带开关行为控制设置PRPretty 格式默认开启列尾空格高亮output_format_pretty_highlight_trailing_spaces#73847长列名默认截断output_format_pretty_max_column_name_width_cut_to/output_format_pretty_max_column_name_width_min_chars_to_cut#73851相邻块时间间隔短则合并显示output_format_pretty_squash_consecutive_ms默认 50ms/output_format_pretty_squash_max_wait_ms默认 1000ms#73852Vertical 格式对列名着色输出到终端时output_format_pretty_color#73898结果超过 N 行时改为「前 N/2 后 N/2」而非只显示前 N 行output_format_pretty_max_rows#73929表格单元格内渲染多行字段output_format_pretty_multiline_fields默认开#74032JSON 输出格式默认 prettyoutput_format_json_pretty_print默认开#72148此外终端下误请求二进制格式Native/Parquet/Avro 等时客户端会先询问确认#73833——脚本里要注意关闭交互或重定向确认避免 CI 卡住。4.5 客户端与协议增强Postgres wire protocol 支持 TLS#73812MySQL 兼容层增强到mysqlshOracle 的富功能 MySQL CLI可直接连接 ClickHouse#73912MySQL 协议错误码也对齐 MySQL 语义#73948clickhouse-client / clickhouse-local 自动识别从文件重定向 stdin 的压缩#73848例如clickhouse-local --query ... data.tsv.gz不再需要先手动 gunzip客户端支持三种方式设置自定义提示符命令行--prompt、配置文件prompt、以及 per-connection 设置#74168连接 9440 端口时自动启用安全连接#74212浏览器场景默认用户需要密码时服务器返回 HTTP 401 触发浏览器交互式凭据输入原来直接 403#72198HTTP handler 可仅以用户名认证#74221X-ClickHouse 响应头暴露给浏览器 JS#74180。4.6 数据湖与队列引擎S3(Azure)Queue存储引擎一批增强允许补设置、commit 设置可 ALTERmax_processed_files_before_commit/max_processed_rows_before_commit/max_processed_bytes_before_commit/max_processing_time_sec_before_commit、多源进度聚合比对 commit 限制、单批文件在同一 Keeper 事务内提交、旧 24.6 结构表迁移到新 bucket 结构#73283、#73635、#73641、#73991、#73467新增system.azure_queue表与system.s3queue对齐#73477新 MongoDB 驱动成为默认想沿用旧驱动可设服务器设置use_legacy_mongodb_integration true#73359内部变更中该旧设置已标记 obsolete #73253use_hive_partitioning默认开启#71636实验标记移除见内部变更 #74065BACKUP/RESTORE支持 core 设置与max_backup_bandwidth#73650、#72665并新增Memory仅当前会话保留与Null不落任何位置两种备份引擎#73690跨云 BACKUP 写尊重 IO 调度设置#71093Azure SAS Token 支持#729594.7 优化器/执行器增强哈希 join 启用时允许更通用的 join 规划算法#71926MergingAggregated步骤支持查询计划层的 predicate push-down#74073析取式公共子表达式提取改进即使不是所有析取项都有公共子表达式也能简化最终过滤表达式#73271EXPLAIN PLAN新增distributed选项EXPLAIN distributed1 ...会把远端计划追加到ReadFromParallelRemote*步骤#73994新分析器下为分布式子查询引入 AST 级谓词下推开关allow_push_predicate_ast_for_distributed_subqueries#74085官方注明这是查询计划序列化落地前的临时方案OPTIMIZE TABLE支持FORCE关键字作为FINAL的替代写法#74342新增 MergeTree 设置materialize_skip_indexes_on_merge抑制合并期间建跳过索引允许通过ALTER TABLE ... MATERIALIZE INDEX显式控制——对向量相似度索引这类构建昂贵的索引很有用#74401PRQL 与 KQL 两种替代查询语言标记为实验性需allow_experimental_prql_dialect 1/allow_experimental_kusto_dialect 1#74224LowCardinality(UUID)默认放行#73826BFloat16数据类型宣布生产可用#73840。4.8 其他值得留意的行为微调least/greatest对 NULL 的默认处理改为忽略 NULL旧行为是任一参数为 NULL 即返回 NULL旧行为可用least_greatest_legacy_null_behavior true恢复#73344formatDateTime的%f现在无条件输出 6 位亚秒数字对齐 MySQLDATE_FORMAT旧行为可用formatdatetime_f_prints_scale_number_of_digits 1恢复#73324parseDateTime64家族对 1970 年之前 / 2106 年之后日期返回正确结果#73594排序键列上 materialize 列改为抛异常而非破坏排序顺序#71891concurrent_threads_soft_limit_num与concurrent_threads_soft_limit_num_ratio_to_cores可不重启热改#73713Keeper 侧客户端可用密码访问 keeper限 16 字符以内与 Keeper Auth 模型无关#74673MySQL/PostgreSQL 表函数与引擎支持 IPv6 地址#74796。五、性能优化无行为变化的提速优化说明PR行比较从最可能不等的列开始排序/去重场景提前短路#63780RowBinary 输入格式优化解析更快#65059字符串反序列化底层优化常见 String 列读取提速#65948grace hash join 右表按键重排右表局部性更好#72237arrayROCAUC/arrayAUCPR支持部分曲面积分可在大数据集上并行计算#72904避免生成过多空闲线程减少调度开销#72920parallel_hashJOIN 探测阶段移除左表哈希分块省去一次切分#73089仅花括号展开的表函数不再列举 blob 存储键减少 ListObjects 调用#73518Nullable 短路执行 纯数值参数快路径修复 #72258 的性能回退#73820maskedExecute不再作用于非函数列短路执行更高效#73965Kafka/NATS/RabbitMQ/FileLog 关闭 header 探测减少首行消耗与探测逻辑#74006日志 wrapper 按值使用、不堆分配减少小对象分配#74034带 grouping sets 的聚合后以更高并行度执行管线后段并行度提升#74082MergeTreeReadPool临界区缩小减少读池锁竞争#74202indexHint优化仅作为 indexHint 参数出现的列不再读表减少 IO#74314并行副本非协议包反序列化固定发生在管线线程initiator 更响应#74398LowCardinality列内存占用计算修正内存核算更准#74688其中indexHint的优化#74314对「用indexHint圈定范围再聚合」的高基数列查询是直接收益——hint 列本身不再产生磁盘读取。六、Bug Fix 中的高优先级项完整修复清单很长此处只挑影响面大或涉及安全的几条其余见原文档安全修复postgresql与sqlite表函数中的SQL 注入问题#74144Pablo Marcos。使用这两个表函数的环境应尽快升级。权限通配授权下的部分 REVOKE 可能多删权限#74751列级GRANT SELECT/INSERT作用于通配库表时现在报错#72646REVOKE ALL ON *.*因隐式授予而失败的问题修复#72872。稳定性CREATE TABLE ... ENGINE Loop组合此前会段错误现在直接禁止#74137system.detached_tables的查询无限循环修复#74190FINALSAMPLE的NOT_FOUND_COLUMN_IN_BLOCK与 CollapsingMergeTree FINAL 错误结果修复#73682Dynamic 列Nested columns sizes are inconsistent逻辑错误修复#73644读取 gzip 数据偶发因客户端解压缺陷失败修复#74707。Keeper修复从磁盘读取日志条目的 bug#74785、开启 Cluster Discovery 时 watch 泄漏#74521、表创建期间 KeeperMap 并发清理#74568。ObjectStorage 队列一系列崩溃/逻辑错误修复#73274、#73420、#73546、#74216、#74892 等。备份恢复RESTORE恢复 part 时跳过metadata_version.txt#73768跨凭据的 S3 复制修复#74331RESTORE基线备份的 native copy 设置修复#74286。七、构建与打包改进内部依赖LLVM 从 16 升级到 18#66053——对源码编译用户意味着对工具链的新要求/行为变化修复 contrib openssl asm 文件生成问题#72622通用安装脚本universal installation script现在在 macOS 上也会提议安装#74339未启用 kerberos 时构建失败的问题修复#74771。八、升级行动清单基于上述变更25.1.1.1 升级到 4165 的建议检查顺序不兼容项逐一过Parquet 输出下游列类型#2.1、ORDER BYJSON/Object 报错#2.2、MaterializedMySQL建表#2.4、Merge表结构推导#2.6必要时merge_table_max_tables_to_look_for_schema_inference 1或compatibility回退、h3ToGeo坐标顺序#2.8必要时h3togeo_lon_lat_result_order true权限补齐给需要CHECK TABLE的角色授予CHECK#2.7给有搬分区需求的角色显式授予ALTER_MOVE_PARTITION#4.3参数重校准max_bytes_before_external_sort语义变化#4.1least_greatest_legacy_null_behavior/formatdatetime_f_prints_scale_number_of_digits两个回退开关按需打开#4.8安全项使用postgresql/sqlite表函数的部署优先升级#74144新功能试点generateSerialID需可用 Keeper、PARALLEL WITH、apply_mutations_on_fly注意查询延迟代价、skipping_index_cache_*两项服务器设置调优均按小流量验证后推广不要依赖 SSH 接口作为升级后的访问方式——本构建中默认禁用#74473。以上所有条目均可在原文档 v25.1.1.4165-stable 发布说明 中按 PR 号与作者完整追溯本文引用的源码位置如 Settings.cpp、StorageMerge.cpp、generateSerialID.cpp、ParserParallelWithQuery.cpp位于当前仓库快照行号与行为可能随后续提交变化核对时请以实际检出版本为准。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考