ClickHouse v25.9.2.1-stable 版本解析：Breaking Changes、新特性与关键修复全景指南

ClickHouse v25.9.2.1-stable 版本解析Breaking Changes、新特性与关键修复全景指南【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本文围绕 ClickHouse v25.9.2.1-stable 官方发布日志对应仓库 docs/changelogs/v25.9.2.1-stable.md展开系统梳理该版本的三类向后不兼容变更、近三十项新特性、性能优化与大量用户可见的 Bug 修复并结合当前仓库源码给出可验证的实现依据。读完本文你将能判断升级到 v25.9 后哪些行为会发生变化、哪些新能力如数据湖写入、动态元数据、倒排文本索引、统计信息驱动 JOIN 优化值得第一时间试用以及在升级后遇到问题时如何快速回退到旧行为。版本背景与升级须知v25.9.2.1-stable是 ClickHouse 2025 年 9 月发布周期的稳定版本commitc2a9511f7bc与上一版本v25.9.1.1-new相比它包含 3 项 Breaking Change、10 余项 New Feature、9 项性能改进、60 余项改进以及近百项用户可见的 Bug 修复同时还有一批构建/测试/打包改进。作为 stable 分支它面向生产环境滚动发布升级前建议重点评估下述 Breaking Change 对现有查询与配置的影响。一、向后不兼容变更Backward Incompatible Change该版本共有 3 项行为变化升级后可能影响存量查询或配置需要优先关注。1. 禁止 IPv4/IPv6 与非法类型的二元运算非整数类型与 IPv4/IPv6 的加/减运算Plus/Minus被正式禁用。此前该运算会与浮点类型碰巧通过并在遇到其他类型如DateTime时抛出逻辑错误logical errors。现在这类运算在类型检查阶段即被拒绝行为更加一致可预测。如果你的存量 SQL 中出现了IPv4 字面量 浮点数之类的写法升级后需要改为显式转换。2. 弃用设置allow_dynamic_metadata_for_data_lakes数据湖Iceberg的动态元数据开关被移除新的行为是所有 Iceberg 表在执行每一条查询前都会尝试从存储中获取最新的表 schema。这意味着查询结果始终与远端 schema 演进保持一致但也引入了每次查询前的元数据拉取开销。3. 倒排文本索引inverted text index从零开始重构倒排文本索引被彻底重写目标是支持无法完全放入内存的数据集scalable for datasets that dont fit into RAM。这是本版本在全文检索方向上的重要架构性变化旧索引文件与新的实现不兼容升级后需要重建索引。二、新特性New Feature速览v25.9.2.1 的新特性横跨表引擎、系统表、函数、设置语法、数据湖与可观测性等多个方向下面按主题分组介绍。表引擎与数据湖Alias 表引擎新增Alias表引擎PR #76569并在本版本的后续开发中一度引入又回退见NO CL ENTRY中的 Revert Alias 与 Backport to 25.9: Revert Merge pull request #76569 ... alias使用时请以最终发布行为为准。Iceberg 写入能力大幅增强新增ALTER UPDATEfor Iceberg 表引擎支持多数据文件multiple data files in iceberg writes、更多分区类型、可省略identity()分区函数新增iceberg_metadata_log系统表用于在 SELECT 期间检索 Iceberg 元数据文件支持 ORC、Avro 格式写入DROP 时可选删除文件。同时引入设置allowed_disks_for_table_engines允许为数据湖表指定已有的磁盘配置例如CREATE TABLE test ENGINE Iceberg(path/inside/disk) SETTING datalake_disk_name some_user_disk;Delta Lake 写入新增实验性设置allow_experimental_delta_lake_writes默认关闭新增deltaLakeAzureCluster与deltaLakeS3Cluster函数便于在集群上下文中访问 Delta Lake。NATS JetStream 支持NATS 引擎新增nats_stream与nats_consumer设置用于消费 JetStream 消息。系统表与可观测性新增system.database_replicas表提供数据库副本信息实现位于 StorageSystemDatabaseReplicas.cpp 并在 attachSystemTables.cpp 中注册。新增system.aggregated_zookeeper_log表按 session id、父路径与操作类型聚合 ZooKeeper 操作统计操作数、平均延迟、错误数并周期性落盘。system.warnings表新增 CPU 与内存告警。新增system.parts_columns.statistics列system.query_cache现在返回所有查询结果缓存条目此前只返回共享条目或同用户同角色的非共享条目。函数与 SQL 语法新增arrayExcept函数从源数组中减去另一数组集合差源码实现位于 arrayExcept.cpp。该实现基于哈希集合做精确比较保留源数组顺序、保留未出现在排除集中的重复元素并将 NULL 作为独立值处理SELECT arrayExcept([1, 2, 3, 2, 4], [3, 5]) -- [1,2,2,4] SELECT arrayExcept([1, NULL, 2, NULL], [2]) -- [1,NULL,NULL] SELECT arrayExcept([apple, banana], [banana]) -- [apple]新增isValidASCII函数检查字符串是否仅包含 ASCII 字符0x00–0x7F支持 String 与 FixedString源码见 isValidASCII.cpp。在开启 SIMDUTF 的构建中走simdutf::validate_ascii的 SIMD 内核否则使用优化过的乐观/悲观检查并注册了别名isASCIISELECT isValidASCII(hello) AS is_ascii, isValidASCII(你好) AS is_not_ascii; -- ┌─is_ascii─┬─is_not_ascii─┐ -- │ 1 │ 0 │ -- └──────────┴──────────────┘新增 PromQL 时间序列聚合函数timeSeriesChangesToGrid与timeSeriesResetsToGrid与timeSeriesRateToGrid同参数结构开始时间、结束时间、步长、回看窗口但每个窗口只需 1 个样本分别统计样本值变化次数与回落次数返回Array(Nullable(Float64))。同时将timeSeries*()的 staleness 窗口改为左开右闭并修复了timeSeriesResampleToGridWithStaleness()首桶无值的问题。裸设置名语法查询设置中允许裸设置名等价于1例如SELECT ... SETTINGS use_query_cache等价于use_query_cache 1并配套修复了非布尔设置无法通过此语法赋值的缺陷。临时视图允许使用与临时表相同的语法创建临时视图。物化视图TO支持查询参数例如CREATE MATERIALIZED VIEW mv TO {to_table:Identifier} AS SELECT * FROM src_table。配置与运维新增logger.startupLevel与logger.shutdownLevel可分别覆盖 ClickHouse 启动与关闭阶段的日志级别后续被重命名为startup_level/shutdown_level以对齐通用设置格式。新增logger.formatting.channel可仅对syslog/console/errorlog/log中的特定 channel 启用 JSON 日志。http_handlers支持按完整 URLfull_url指令含 schema 与 host:port过滤请求。可配置线程的 nice 值为 merge/mutate、query、物化视图、zookeeper 客户端等线程设置不同优先级。clickhouse-benchmark新增--precise标志在查询耗时接近上报间隔--delay D时提供更稳定的 QPS 统计。三、性能优化Performance ImprovementPREWHERE 优化增强改善形如func(primary_column) xx与column in (xxx)条件下的 prewhere 优化效果。JOIN 重写为 SEMI/ANTI/FULL可将LEFT ANY JOIN/RIGHT ANY JOIN在过滤条件恒为 false 时改写为 SEMI/ANTI JOIN由新设置query_plan_convert_any_join_to_semi_or_anti_join控制默认开启声明见 Settings.cppFULL ALL JOIN在单侧非匹配行恒为 false 时可改写为LEFT ALL/RIGHT ALL。统计信息驱动的 JOIN 重排可通过allow_statistics_optimize 1及别名use_statistics默认true配合query_plan_optimize_join_order_limit 10默认值 10见 Settings.cpp启用基于统计信息的 JOIN 顺序优化。轻量删除后的垂直合并提速、HashJoin在大量未匹配行场景下的微优化、RadixSort 使用 SIMD 与软件预取仅 Intel CPU 动态分发启用、快查询在表含大量 parts 时通过devector替代deque优化MarkRanges、以及 join 模式下 patch parts 应用性能改进。四、核心改进Improvement详解查询计划与 JOIN 语义修正引入实验性 JOIN 顺序优化由query_plan_optimize_join_order_limit控制。当前统计支持有限主要依赖存储引擎的行数估算。升级后如遇 JOIN 查询异常可临时关闭新实现SET query_plan_use_new_logical_join_step 0并反馈问题。USING 子句标识符解析修正OUTER JOIN ... USING中未限定的 USING 列现在总是解析为合并coalesced列而限定的t1.a/t2.a解析为非合并列。此前a, t1.a, t2.a混选时a会错误解析到t1.aSELECT a, t1.a, t2.a FROM (SELECT 1 as a WHERE 0) t1 FULL JOIN (SELECT 2 as a) t2 USING (a); -- Before: a0, t1.a0, t2.a2 (错误a 解析到 t1.a) -- After: a2, t1.a0, t2.a2 (正确a 为合并列)存储与索引新增设置use_skip_indexes_on_data_read声明于 Settings.cpp默认开启允许在读取时用跳过索引过滤数据 part减少不必要的索引读取并在 MergeTreeDataSelectExecutor.cpp、ReadFromMergeTree.cpp 等查询路径中参与 granule 级裁剪。另有配套设置query_condition_cache_selectivity_threshold默认 1.0低于该选择度的谓词扫描结果不进入查询条件缓存以内存换取缓存命中率。EXPLAIN查询计划描述被限制长度新增设置query_plan_max_step_description_length默认 500见 Settings.cpp。alter table ... materialize statistics all可一次性物化表的所有统计信息。S3 / Azure 与外部存储S3 重试策略可配置化且 S3 磁盘的设置可在修改 config XML 后热加载。将原backup_slow_all_threads_after_retryable_s3_error推广为s3_slow_all_threads_after_retryable_error覆盖 S3 磁盘并随后在 #87198 中默认禁用backport 至本版本。azure_max_single_part_size_copy设置现在同样作用于普通 copy 操作。S3 表引擎与s3表函数新增参数storage_class_name用于指定 AWS 智能分层存储类别支持键值对与位置参数两种写法。arrowFlight()表函数新增认证与 SSL 支持并修复了 IPv6listen_host支持与 handler 关闭问题。Variant / Dynamic / JSONallow_experimental_variant/dynamic/json与enable_variant/dynamic/json设置被标记为 obsolete这三种类型现在无条件启用不再需要开关。内存与性能剖析升级 jemalloc改进基于其内部工具的内存分配剖析新增配置jemalloc_enable_global_profiler与jemalloc_collect_global_profile_samples_in_trace_log全局采样写入system.trace_log的JemallocSample类型以及按查询的设置jemalloc_enable_profiler与jemalloc_collect_profile_samples_in_trace_log。在排序、异步插入、文件日志等已知会分配超过 16MiB 内存的路径上尊重内存限制新增FailedInternal*Queryprofile events 与异步指标QueriesMemoryUsage/QueriesPeakMemoryUsage。ZooKeeper / Keeper / 复制新增维度指标startup_scripts_failure_reason用于区分启动脚本失败中的瞬时错误如MEMORY_LIMIT_EXCEEDED、KEEPER_EXCEPTION与非瞬时错误便于告警。Keeper 的RemoveRecursive请求性能提升复制去重窗口上调至 10000。SYSTEM DROP REPLICA在元数据损坏的 Catalog 上执行不再报错。其他值得注意的改进today()与yesterday()改为大小写不敏感与NOW()一致。WHERE子句中允许使用原生数值此前仅作为逻辑函数参数允许简化 filter 下推与 move-to-prewhere 优化。PrettyJSONEachRow在输出 JSON 类型时移除多余空白。network_compression_method若非受支持的通用 codec 将直接抛异常。性能测试脚本支持对远端 ClickHouse含 ClickHouse Cloud运行.xml用例。S3(Azure)Queue 引擎新增use_persistent_processing_nodes设置可用ALTER TABLE MODIFY SETTING修改提升对 ZooKeeper 连接丢失的容忍度。五、Bug Fix 关键修复清单用户可见行为复制与分布式ALTER 查询结果仅在发起节点校验修复已提交的 alter 在其他节点卡死的问题轻量更新ON CLUSTER修复复制数据库副本恢复时表未正确关闭导致的 LOGICAL_ERROR 修复。从*cluster函数读取时若所有副本不可用则直接失败parallel replicas 下多 JOIN尤其 RIGHT JOIN 跟在 LEFT/INNER JOIN 后的逻辑错误修复分布式查询describe_compact_output1修复。数据湖Iceberg / Delta Lake / HiveIceberg 源 id 与 parquet 列名映射在文件写入后按每个数据文件 schema 处理Iceberg 分区表达式解析移除 UB目录无/支持读取格式改为从 Iceberg 元数据获取Iceberg 迭代器异步异常处理iceberg_metadata_log未配置时访问给出明确错误文件系统缓存不再因 Iceberg 元数据缓存关闭而禁用。DeltaLake 非默认列映射模式下子列读取修复DeltaLake 写入逻辑错误修复Hive 的 LowCardinality 支持、分区列检查、空格式 LOGICAL_ERROR 等系列修复。查询执行与函数uniqExact在ROLLUP/CUBE下的可能错误结果修复非相关EXISTS影响 25.8 的execute_exists_as_scalar_subquery1修复CTE 中函数结果非确定性修复CASE函数与 Dynamic 参数修复searchAny/searchAll空 needle 现在返回true匹配一切replaceRegex在 FixedString haystack 与空 needle 下崩溃修复accurateCastOrNull/OrDefault从 String 到 JSON 修复。存储与 MergeTreeFINAL查询在index_granularity_bytes 0且带跳过索引的表上抛异常修复merge_tree_min_read_task_size为 0 时崩溃修复TTL 带WHERE的无限重算修复有默认表达式的列在 patch 应用时缺失于 data part 的修复max_temporary_data_on_disk_size限制跟踪修正。客户端 / HTTP / 格式send_chunk_header开启时经 HTTP 协议调用 UDF 缺失 chunk header 修复两处RowBinary输入中 NULL 写入 JSON 共享数据修复CSV 从空字符串读空数组修复JSON 路径带 Enum 提示时默认值错误修复。Keeper / ZooKeeperIPv6 在内核层面被禁用如 RHELipv6.disable1时Keeper 回退到 IPv4 监听器system.distributed_ddl_queue在缺少 Keeper 节点的任务上查询修复KeeperMap 表在 25.1 之前创建的数据在 DROP 后残留 ZooKeeper 数据的问题修复。内存与并发BackgroundSchedulePool按类型限制每类任务数由服务器设置background_schedule_pool_max_parallel_tasks_per_type_ratio控制避免单类型任务占满槽位导致的饥饿与死锁jemalloc profile flush 开启时的死锁修复文件系统缓存动态扩容时的逻辑错误修复PipelineExecutor 降级逻辑死锁修复。六、构建 / 测试 / 打包改进修复与 abseil-cpp 20250814.0 的兼容性openldap 升至 2.6.10、krb5 升至 1.22.1-final。修复旧 ARM CPU 上缺少vmull_p64指令时的 crc32c 构建WASM lexer 独立构建置于 flag 之后darwin 上不再拦截memalign。新增 Distributed Cache 的缺失 profile events 与限流引用list-licenses.sh修复 Rust crate 名解包。七、升级与运维建议综合以上变更针对 v25.9.2.1-stable 的升级给出如下实操建议升级前扫描存量 SQL重点排查 IPv4/IPv6 与浮点/DateTime 的加减运算、依赖旧倒排索引格式的表升级后需重建索引、以及显式开启过allow_dynamic_metadata_for_data_lakes的配置。关注 JOIN 行为变化若升级后 JOIN 查询异常可依次尝试SET query_plan_use_new_logical_join_step 0回退到旧逻辑并检查USING列解析是否符合新语义。数据湖用户Iceberg 每次查询前拉取最新 schema 的新行为会带来元数据开销可通过system.iceberg_metadata_log观察元数据读取情况Delta Lake 写入仍为实验特性需显式开启allow_experimental_delta_lake_writes。可观测性升级推荐接入system.aggregated_zookeeper_log与system.warnings辅助运维监控使用startup_scripts_failure_reason指标区分瞬时与非瞬时启动脚本错误以优化告警规则。性能调优尝鲜可尝试use_skip_indexes_on_data_read默认开启与统计信息驱动的 JOIN 重排query_plan_optimize_join_order_limit 10并结合EXPLAIN观察执行计划变化。本文所有功能条目均可在仓库 docs/changelogs/v25.9.2.1-stable.md 中溯源到对应 PR关键实现的源码位置包括isValidASCII见 src/Functions/isValidASCII.cpp、arrayExcept见 src/Functions/array/arrayExcept.cpp、system.database_replicas见 src/Storages/System/StorageSystemDatabaseReplicas.cpp各项设置声明见 src/Core/Settings.cpp。如需进一步验证可在对应源码文件与 tests/queries 的功能测试中检索arrayExcept、isValidASCII、use_skip_indexes_on_data_read等关键字。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考