ClickHouse 2026 年度版本全解读：26.1 到 26.9 的关键演进、不兼容变更与升级实战

ClickHouse 2026 年度版本全解读：26.1 到 26.9 的关键演进、不兼容变更与升级实战

【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse

2026 年 ClickHouse 从 26.1 一路迭代到 26.9，其中 26.3 与 26.8 被标记为 LTS（长期支持）版本。本文以仓库内的 2026 年官方 Changelog（docs/_includes/content/changelog.md）为主体，逐版本梳理向后不兼容变更、新功能、实验性功能、性能改进与稳定性修复的主线，并结合仓库源码说明其落地位置。读完本文，你将能回答三个问题：升级前必须处理哪些"红线"变更？每个版本带来了哪些值得立即使用的 SQL、引擎与系统表？如何利用compatibility设置平滑过渡并规避已知坑位。

一、2026 年发布节奏总览

ClickHouse 2026 年保持每月一版的节奏，两个版本被标记为 LTS，官方推荐的长期生产版本为 26.3 与 26.8：

二、向后不兼容变更：升级前必须处理的红线

Changelog 每版都以 "Backward Incompatible Change" 开头，这是运维升级前最需要逐条核对的部分。按主题归类如下。

1. 查询引擎与分析器

• 分析器彻底不可关闭（26.9）：enable_analyzer（及其旧名allow_experimental_analyzer）成为历史，设置为0会被直接拒绝，compatibility也不再回退它。分析器自 24.3 起就是默认，旧的分析路径已不受支持。若要与旧分析行为对比，只能使用 26.9 之前的版本。
• NOT运算符优先级对齐 SQL 标准（26.3）：NOT现在比IS NULL、BETWEEN、LIKE绑定更松，NOT (x) IS NULL由(NOT x) IS NULL变为NOT (x IS NULL)，依赖旧语义的查询结果会变化。
• EXPLAIN SYNTAX输出改为单条记录（26.8）：默认以单条含换行的String记录返回（single_record = 1），SELECT count() FROM (EXPLAIN SYNTAX ...)直接返回 1；single_record = 0恢复逐行输出。
• UNION裸写报错更友好（26.9）：提示应写UNION ALL/UNION DISTINCT或设置union_default_mode。
• LIMIT n WITH TIES需配合ORDER BY（26.x 多轮修复）：多个版本修复了WITH TIES在分布式、负LIMIT、collation 下的边界行为。

2. 压缩与存储格式

• 默认压缩从LZ4切换为ZSTD(3)（26.9）：这是 2026 年影响面最大的存储变更之一。客户端/服务端、服务端/服务端网络通信统一改用ZSTD(3)；MergeTree列数据按"写时已知的 part 大小"自适应——低于 100 MB 用LZ4，达到或超过用ZSTD(3)；StripeLog、Set/Join引擎持久文件、checksums.txt等一律ZSTD(3)；HTTPcompress=1也走network_compression_method。恢复旧行为的方式：网络压缩用compatibility或network_compression_method='LZ4'，列数据用CODEC(LZ4)，其余流无运行时回退（每帧自带描述，读取始终正确）。
• 序列化版本向嵌套类型传播（26.3，LTS 版本最重要警告）：propagate_types_serialization_versions_to_nested_types默认开启后，String的with_size_stream序列化会作用于Array/Map/Variant/JSON等嵌套类型内部的所有String。升级安全，但降级不安全——26.3 写出的含嵌套类型列在旧版本上不可读，回滚前必须确认没有 26.3 写入的数据。
• x86 默认构建目标从 x86-64-v2 提升到 x86-64-v3（AVX2）（26.6）：要求 Intel Haswell 及以后、AMD Excavator 及以后的 CPU，老 CPU 需改用amd64compat构建。
• ALP(STD)编解码器改用Float64做缩放运算（26.8）：压缩比提升，但旧版本写出的Float32值可能差 1 ULP。
• 硬件编解码器移除（26.1）：DEFLATE_QPL与ZSTD_QAT被移除，升级前需将数据转码。
• insert_deduplication_version演进（26.6 → 26.7）：26.6 默认从compatible_double_hashes改为new_unified_hash（整块按插入去重）；26.7 起不再支持旧值，升级前需先经过compatible_double_hashes过渡窗口。

3. 移除的功能与引擎

26.9 是一次大规模"清理"版本：

• CatBoost 集成移除：catboostEvaluate、system.models、SYSTEM RELOAD MODEL(S)全部下线。升级前需 revokeSYSTEM RELOAD MODEL权限、清空分布式 DDL 队列、删除引用该函数的表定义，否则启动失败。
• WINDOW VIEW实验功能移除：WATCH语句与windowID函数随之删除，相关设置保留为 no-op；存量 window view 必须提前 drop，否则元数据解析失败导致启动失败。时间窗函数tumble/hop等保留。
• WasmEdge引擎移除：WebAssembly UDF 只支持wasmtime。
• 分片GROUP BY（enable_sharding_aggregator）移除：由自适应聚合（enable_adaptive_aggregator）取代，旧设置保留为无效 no-op。
• CREATE TABLE ... AS mergeTreeIndex(...)等代理表形式禁止（26.9），timeSeriesSamples系列同样禁止。
• s3_disable_checksum移除（26.9）、read_resource/write_resource磁盘选项移除（26.9）。
• 更早版本：Lazy数据库引擎（26.1）、hypothesis跳数索引类型（26.3）、kql表函数（26.5，改用SET dialect='kusto'）、library字典源（26.8）、Apache Arrow 库读写器（26.8，原生实现成唯一选项）、废弃的snowflakeToDateTime等函数（26.7）。

4. 权限与安全

2026 年权限模型明显收紧，多条涉及特权提升/信息泄露的修复：

• BACKUP/RESTORE与BACKUP数据库引擎要求SOURCES授权（26.9）：Disk(...)目标需要WRITE ON DISK/READ ON DISK；此前 26.8 已对S3/Azure/FILE来源实施同样的SOURCES检查。
• CREATE TOKEN新语句（26.9）：为应用生成绑定用户、限定时间与权限的令牌，如CREATE TOKEN VALID FOR INTERVAL 30 DAY GRANTS (SELECT ON db.table)，默认有效期由create_token_default_ttl_seconds（默认 30 分钟）控制；ALTER USER ... ADD IDENTIFIED ... GRANTS (...)也可把某认证方法限定为"交集权限"。
• hasColumnInTable移除远程三参形式（26.7），并要求SHOW COLUMNS权限（26.6 起）。
• joinGet强制SELECT授权（26.1）：对底层Join表的主键列与属性列都要有授权。
• 大量 SQL 注入与 SSRF 修复：PostgreSQL wire 协议预编译参数改为数据绑定、MySQLSHOW TABLE STATUS LIKE重解析、S3 301 重定向校验remote_url_allow_hosts、http_forbid_headers在 schema 推断前生效（26.7）、PostgreSQL/Cassandra/XDBC 字典源转义修复（26.5）。
• 凭据掩码扩展：system.query_log、system.processes、SHOW CREATE、EXPLAIN等对 URL、S3、HMAC、format_avro_schema_registry_url中的密钥统一[HIDDEN]处理（26.6/26.7 多轮）。
• CREATE USER OR REPLACE需要DROP权限（26.7）、TRUNCATE DATABASE ... ON CLUSTER需要DROP DATABASE（26.7）。
• TOTP 每次验证只接受一次（26.8 修复，RFC 6238）。

5. 数据语义与格式

• IN对Bool采用精确值语义（26.4）：CAST(1,'Bool') IN (256)从1变0；复合类型内的Decimal有损转换也一并拒绝。
• CAST到DateTime/DateTime64保留源时区（26.5）。
• Date32范围扩展到[0000-01-01, 9999-12-31]（26.8），DateTime64同样扩展到该范围（26.7）；toDate32(N)的数值解释规则相应调整。
• PostgreSQL/MySQL 日期映射升级：PostgreSQLDATE→Date32（26.2），MySQLDATE→Date32、DECIMAL→Decimal（26.3）。
• date_time_input_format与cast_string_to_date_time_mode默认改best_effort（26.5）：2024 April 4这类字符串默认可解析，旧严格行为用compatibility或显式basic。
• RANK/DENSE_RANK不再接受参数（26.5），allow_rank_dense_rank_arguments=1可恢复宽松行为。
• HTTPX-ClickHouse-Format头优先级提升（26.8）：现在等同output_format，覆盖查询的FORMAT子句。
• arrayIntersect等重复值语义修正（26.8）：同一参数内重复出现的值不再视为多次出现。
• AggregatingMergeTree建表校验（26.7）：既非排序键也非聚合状态列会被拒绝，可用allow_dimensions_outside_sorting_key=1恢复旧行为。

三、新功能亮点（按版本展开）

26.9

• DISTINCT支持落盘：max_bytes_before_external_distinct与max_bytes_ratio_before_external_distinct控制阈值。
• 新的LIMIT边界语义：LIMIT n AFTER cond、LIMIT UNTIL cond、LIMIT AFTER c1 UNTIL c2、LIMIT n AFTER cond ALL按流顺序与条件选取行，如LIMIT 3 AFTER number >= 5返回5,6,7。
• CREATE TOKEN（见上文权限部分）。
• SQL 标准线性回归聚合函数：regr_slope、regr_intercept、regr_r2、regr_count、regr_avgx、regr_avgy、regr_sxx、regr_syy、regr_sxy。
• MergeTree表大小上限：max_table_size_rows、max_table_size_bytes_compressed、max_table_size_bytes_uncompressed；数据库级max_tables限制表/视图/字典数量。
• system.statements系统表暴露 SQL 语句文档（名称、语法、说明、示例）。
• JSON子列方括号语法：json['key1']['key2']被解析为嵌套arrayElement调用。
• system.session_query_ids：记录当前会话最近执行的 query_id，便于在system.query_log定位"我刚跑的查询"。
• 可刷新物化视图增量刷新：REFRESH ... APPEND INCREMENTAL只追加上次刷新以来的提交行。

26.8（LTS）

• Pipe 操作符：FROM t |> WHERE x > 1 |> AGGREGATE count() AS c GROUP BY y |> ORDER BY c DESC |> LIMIT 10，等价于嵌套子查询；以FROM开头时SELECT子句可省略。
• run_query_in_background：服务端接受查询、立即返回空结果、断开连接也继续执行，配合 query_id 在system.processes/system.query_log跟踪。
• system.user_query_log：每个用户只能看到自己的查询日志记录，无需对 query_log 的全局授权。
• Framing 输出格式：framing_output_format支持EventStream（SSE）、JSONEachPacketBase64、JSONEachPacketString，把数据、totals/extremes、进度、profile 事件、日志、异常复用到单一 HTTP 响应流。
• GROUPS窗口帧（SQL:2011）：如any(price) OVER (PARTITION BY symbol ORDER BY ts GROUPS BETWEEN CURRENT ROW AND 1 FOLLOWING)。
• Keeper 落盘存储：use_lsmt_storage=true+storage_memory_only=false+data_storage_path/data_storage_disk（支持s3_plain磁盘）。
• bigquery表函数与BigQuery表引擎；Snowflake Horizon（Iceberg REST 目录）支持；Puffin文件格式支持。
• HTTP URL 路径访问表：/database/table.format.gz?filter=a>0，配合http_allow_database_as_path、http_allow_table_as_file、http_allow_filters_as_path等设置。
• default_session_user：空用户名连接的默认用户不再硬编码为default。

26.7

• EXPLAIN ANALYZE：真实执行并输出各步骤实际指标。
• -Tuple聚合组合器：sumTuple(t)对Tuple各元素独立聚合并保留元素名。
• AT TIME ZONE/AT LOCAL后缀：toTimeZone的语法糖。
• Remote/RemoteSecure表引擎：remote/remoteSecure表函数的持久化对应物。
• URL引擎按 scheme 分发：file://、s3://、az://、hdfs://、http(s)://自动路由到对应后端。
• QueryRunner表引擎：插入即执行查询，可用于异步执行、基准、模糊测试与影子流量。
• GeoJSON输出格式（26.6 为输入）：每行一个 feature，几何列写为geometry。
• QBit向量数据类型的 stride 参数与Int8元素：QBit(T, dimension, stride)支持 Matryoshka 式部分维度读取；randomHadamardTransform用于嵌入向量旋转/投影。
• system.stemmers、dictGetRoot、SYSTEM UNLOAD DICTIONARY、xxHash64Spark、digits、sqr等函数。

26.6

• MergeTree连续查询（streaming 雏形）：通过快照序列读取实现，是流式查询的第一步。
• 假设索引 WHATIF：CREATE HYPOTHETICAL INDEX ... ON t (expr) TYPE ...+EXPLAIN WHATIF SELECT ...无物化评估跳索引收益，system.hypothetical_indexes可见。
• /schemaWeb UI：表、物化视图、字典、分布式表之间的依赖关系可视化。
• PNG输出格式：查询结果直接渲染为图片。
• AI 编码代理检测：识别 Claude Code、Cursor、Codex 等，写入system.query_log.client_agent。
• system.documentation：把函数、表引擎、数据类型、设置等内嵌文档统一成可查询的 Markdown 表；随后 26.8 的/docs搜索页与clickhouse-client的help命令都基于它。
• MVT 系列函数（MVTEncodeGeom、MVTEncode、MVTBoundingBox，含ST_AsMVTGeom别名）与system.iceberg_files。

26.5

• filesystem表函数：把目录结构当表查，SQL 查询文件元数据与内容。
• 高阶函数支持裸函数名：arrayMap(negate, [1,2,3])等价于arrayMap(x -> negate(x), [1,2,3])。
• LIMIT BY支持负数：LIMIT -2 BY id取每组最后两行。
• tokenizeQuery/highlightQuery：SQL 词法与语法高亮。
• url_base：url表函数与URL引擎的相对 URL 解析（RFC 3986）。
• Paimon表引擎：增量读取 + Keeper 快照进度跟踪，paimon_target_snapshot_id定向增量。
• isPrime/isProbablePrime（UInt64 精确、UInt128/256 概率）。

26.4

• Arrow Flight SQL：Arrow Flight 表引擎与表函数、预编译语句。
• NATURAL JOIN：按同名列自动匹配并去重。
• VALUES表表达式：SELECT * FROM (VALUES (1,'a'),(2,'b')) AS t(id,val)。
• 按规范化查询哈希的配额：CREATE QUOTA q KEYED BY normalized_query_hash与MAX queries_per_normalized_hash。
• EXTRACT扩展 PostgreSQL 单位：EPOCH、DOW、DOY、ISOYEAR、CENTURY等。
• 文本索引 GA（26.4 起不受compatibility关闭，26.2 已宣布 GA）。
• 其余：arrayAutocorrelation、obfuscateQuery、JSONAllValues、commit_order投影索引、highlight函数。

26.3（LTS）

• Map桶化序列化：map_serialization_version='with_buckets'把键按哈希分桶，m['key']只读一个桶，单键查询加速 2–49 倍。
• 物化 CTE：MATERIALIZEDCTE 只求值一次并存入临时表，多分支共享。
• table_readonlyMergeTree设置：标记表只读，禁止插入与修改（26.7 起同时抑制全部后台任务并拒绝分区变更命令）。
• ALTER TABLE ... EXECUTE expire_snapshots('')（Iceberg）。
• mergeTreeTextIndex表函数：直接读文本索引做内省或聚合。
• 异步插入默认开启：compatibility < 26.2时恢复旧默认false。

26.2

• 插入去重默认开启：同步/异步/物化视图统一默认deduplicate_insert；新增insert_deduplication_version服务端设置做迁移。
• ClickStack 集成：内置可观测 UI。
• TOTP 认证：时间基一次性口令。
• lazy_load_tables数据库设置：表在首次访问时才真实加载。
• system.tokenizers、system.user_defined_functions、system.jemalloc_stats、system.fail_points。
• xxh3_128、OPTIMIZE ... DRY RUN PARTS、add_minmax_index_for_temporal_columns。

26.1

• Keeper HTTP API 与内置 Web UI。
• use_variant_as_common_type默认开启：不兼容类型可进入Array、UNION与if/multiIf分支。
• mergeTreeAnalyzeIndexes、cosineDistanceTransposed、reverseBySeparator、ClickHouse_InfoPrometheus 指标。
• use_primary_key设置可关闭主键粒度剪枝。

四、实验性功能：技术方向观察

Changelog 的 Experimental Feature 一栏最能反映研发方向：

• TimeSeries + PromQL 体系：26.6 引入 TimeSeries 表引擎与 PromQL HTTP API，26.7/26.8/26.9 密集迭代——prometheusQuery/prometheusQueryRange表函数、absent/count_values、sum_over_time系列范围函数、max_over_time/min_over_time、histogram_quantile、deriv、increase、/api/v1/series与/api/v1/labels端点；26.9 将 TimeSeries 从 experimental 提升到 private preview，allow_experimental_time_series_table更名为enable_time_series_table，并新增基于 LSM 的 Keeper 磁盘存储、增量recent_samples表等。
• 分布式查询计划make_distributed_plan：26.6 引入多阶段执行（scatter/broadcast/gather/shuffle 交换），26.7–26.9 不断扩展INTERSECT/EXCEPT、窗口函数、IN子查询、Cascades 代价优化器（enable_cascades_optimizer）、聚合下推与 JOIN 分发。
• 向量搜索：QBit位打包存储（26.2 GA）、转置距离函数（L2DistanceTransposed等）、量化编解码（Quantized、quantizeBFloat16ToInt8）、hierarchicalKMeans/assignCentroid搭建 IVF 检索。
• WASM UDF：26.3 起引入，支持BUFFERED_V1ABI、AssemblyScript ABI、燃料限制与输入分块；26.9 移除 WasmEdge 后仅剩 wasmtime。
• AI 函数：aiGenerate/aiClassify/aiExtract/aiTranslate/aiRedact/aiFilter/aiEmbed/aiSimilarity，26.9 升至 beta 并默认ai_function_max_retries=1。
• KQL/Trino 方言：26.9 重写 KQL 为独立词法/语法分析器；新增实验trino方言。
• silk 纤程运行时（26.9）：enable_silk_runtime让子系统在等待 I/O 时占用纤程而非 OS 线程。

五、性能改进主线

2026 年的性能工作可以归纳为四条主线，changelog 每版都有对应的设置与实现：

1. 聚合与哈希表

• 自适应并行聚合enable_adaptive_aggregator（26.8 引入，26.9 移除分片聚合后成为唯一路径）：每线程哈希表冻结 + 桶内回填。
• 字符串键聚合的 packed keys（enable_packed_string_keys_in_aggregation）、enable_parallel_single_level_merge、bucket top-K（query_plan_aggregation_bucket_top_k）。
• uniq/uniqExact/groupUniqArray的 CRC32 哈希、位图实现与并行合并优化。

2. JOIN

• join_algorithm家族扩展：26.8 新增parallel_full_sorting_merge；ie_join默认启用（26.8），按条件选择性选键（26.9）；JOIN runtime filter 默认开启（26.2）并在 26.9 生产化。
• 哈希表索引化行引用、enable_hash_join_row_store、键专用哈希表（enable_join_key_only_hash_tables）。
• dpsub/dpsize/dphyp连接顺序枚举与 CD-C/CD-A 冲突检测（26.9）。

3. 存储、压缩与 IO

• ZSTD 解压向量化（SSSE3/NEON）、T64 转置向量化、DoubleDelta解压加速、Delta编解码器向量化。
• 对象存储读取优化：load_marks_asynchronously默认开启（26.9）、parquet 字典过滤下推、懒物化（lazy materialization）扩展到对象存储/本地文件（26.8）。
• 用户态页缓存、filesystem cache 的 SLRU 优化与锁竞争削减、jemalloc独立 arena（jemalloc_merge_tree_arenas）。

4. 索引与读取路径

• 文本索引持续优化：懒 posting list、packed 位置、tokenizer（splitByRegexp提取模式、keyValuePairs、26.8 的japanese/chinese/icu）。
• SELECT count()由_minmax_count_projection与稀疏列统计直接作答（optimize_trivial_count_with_sparsity_filter）。
• 只读数据库table_readonly、只读副本SYSTEM RESTART DISK（26.6）。

六、稳定性与安全：Bug Fix 主题归纳

每个版本的 Bug Fix 一栏都在解决"官方稳定版中的用户可见错误"，按主题归纳：

• 内存安全与恶意输入：大量针对 Parquet/ORC/Avro/Arrow/Native/Protobuf/BSON 等格式读取器、聚合状态反序列化（groupConcat、quantileTiming、windowFunnel、uniqTheta等）的越界、OOM 与崩溃修复；26.7 批量收紧了二进制输入的类型复杂度上限（input_format_binary_max_type_complexity）。
• 索引剪枝正确性：多轮修复主键/分区/跳数索引在NaN、±inf、Enumvs 字符串常量、FixedString填充、时区边界（toWeek、toUnixTimestamp、DateTime64越界）下的错误剪枝，防止"静默少行"。
• 可取消性：KILL QUERY/max_execution_time从arrayFold、replaceRegexpAll、geohashesInBox、h3PolygonToCells、isProbablePrime、base58Decode、dictGet、外部数据库读取等长路径中生效。
• 权限与泄露：Alias引擎 RBAC 绕过、loop表函数行策略绕过、EXPLAIN泄露列名、getServerSetting绕过授权、CREATE TOKEN相关配额等均被修复。
• WITH FILL/INTERPOLATE/LIMIT BY边界：多轮修复填充行重复、排序前缀、常量与 collation 组合下的错误。

七、升级与工程实践建议

1. 用compatibility做灰度

Changelog 中几乎所有默认值变更都预留了回退路径，典型写法：

SET compatibility = '26.8'; -- 恢复 26.8 及更早版本的默认行为 SET network_compression_method = 'LZ4'; -- 或针对单项覆盖

注意 26.9 的两处例外：enable_analyzer不再接受0；compatibility也不会再关闭分析器。而 26.3 的序列化版本传播属于"不可降级"型变更，升级前务必评估回滚窗口。

2. 升级检查清单（依据 changelog）

1. 删除/改写引用已移除功能的定义：catboostEvaluate、windowID、WINDOW VIEW、hypothesis索引、library字典、kql表函数、snowflakeToDateTime等。
2. revoke 已删除权限：SYSTEM RELOAD MODEL（26.9）会让含该授权的访问实体无法解析。
3. 核对权限收紧：BACKUP/RESTORE目标授权、joinGet的SELECT、hasColumnInTable的SHOW COLUMNS。
4. CPU 指令集：26.6 起默认 x86-64-v3，老 CPU 用amd64compat。
5. 压缩策略：26.9 起按需给列指定CODEC(LZ4)，或接受ZSTD(3)以换取存储/带宽。

3. 关注 LTS 与测试资产

• 长期运行优先选择 26.3 与 26.8 两个 LTS；26.9 属于"进行中"，新特性（CREATE TOKEN、LIMIT边界语义等）可在非生产验证。
• 仓库内 tests/benchmarks 自 26.3/26.4 起补齐了 TPC-H 与全部 99 条 TPC-DS 正确性测试，可作为升级后回归的基线。

4. 结合源码深入验证

• 文本索引（text index）的实现与条件分析位于 src/Storages/MergeTree/MergeTreeIndexText.h、src/Storages/MergeTree/MergeTreeIndexConditionText.cpp，配合 src/Storages/MergeTree/MergeTreeIndexTextPreprocessor.cpp 可追踪 26.8 新增的preprocessor/postprocessor与多语言 tokenizer 逻辑。
• 向量搜索的QBit类型定义在 src/DataTypes/DataTypeQBit.h 与 src/Columns/ColumnQBit.h，26.7–26.9 的转置距离、量化与 stride 读取都在其上实现。
• 服务端配置默认值（如 26.6 提到的keep_alive_timeout=30）可直接查阅 programs/server/config.xml。

结语

2026 年是 ClickHouse 从"极致单机列存"走向"分布式查询计划、时序/向量/AI 一体"的关键一年：26.9 以大规模清理（分析器固化、压缩默认切换、旧功能移除）为年度收尾，26.3 与 26.8 两个 LTS 则分别锚定了存储格式升级与分布式/流式能力的地基。对于使用者而言，逐版核对"Backward Incompatible Change"清单、善用compatibility设置、并关注system.documentation与各系统表的新增观测能力，是平滑升级并快速消化新功能的最短路径。

【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse