ClickHouse v25.8.2.29-lts 版本详解：Iceberg 元数据日志、Delta Lake 写入与关键 Bug 修复

数据库OLAP列式数据库大数据实时分析数据分析【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址https://gitcode.com/GitHub_Trending/cli/ClickHouse点击查看免费下载v25.8.2.29-lts 是 ClickHouse 25.8 LTS 系列的一个补丁发布相对基线 v25.8.1.5101-lts。本指南以官方变更日志为主体结合仓库源码逐一拆解该版本引入的新功能Iceberg 元数据系统表、Delta Lake 写入开关、按通道 JSON 日志、七项用户可见 Bug 修复及若干内部改进帮助你在升级与排障时准确判断每个变更的影响范围。一、版本基线说明本发布构建号build hash为874146507b0对比基线为v25.8.1.5101-ltshash4f2b50b8c92。变更内容按官方分类分为四类New Feature新增功能Improvement改进与增强Bug Fix官方稳定版中用户可见的错误行为修复NOT FOR CHANGELOG / INSIGNIFICANT内部修复或测试修正通常不产生用户可见行为变化。以下逐项说明每类变更的实质内容及其源码依据。二、新功能system.iceberg_metadata_log系统表本版本新增系统表iceberg_metadata_log用于在 SELECT 查询执行期间检索并记录 Iceberg 表的元数据文件PR #86152。2.1 表结构与字段说明从源码 src/Interpreters/IcebergMetadataLog.cpp 的getColumnsDescription()可以看出该表包含以下字段字段类型含义hostnameLowCardinality(String)执行查询的服务器主机名clickhouse_versionLowCardinality(String)产生该行的服务器版本system_processorLowCardinality(String)服务器 CPU 架构event_dateDate条目日期event_timeDateTime事件时间query_idString查询 IDcontent_typeEnum8元数据内容类型见下table_pathString表路径file_pathString文件路径contentStringJSON 格式的内容json 文件内容、avro 元数据或 avro 条目row_in_fileNullable(UInt64)文件中的行号pruning_statusNullable(Enum8)该文件的裁剪状态content_type是关键的诊断字段其枚举值直接对应查询级设置iceberg_metadata_log_level的六个级别见 IcebergMetadataLog.cppNone—— 不记录元数据日志Metadata—— 记录根 metadata.json 文件ManifestListMetadata—— 以上全部外加与快照对应的 avro manifest list 的元数据ManifestListEntry—— 以上全部外加 avro manifest list 条目ManifestFileMetadata—— 以上全部外加遍历到的 avro manifest 文件的元数据ManifestFileEntry—— 以上全部外加遍历到的 avro manifest 文件条目。pruning_status字段分区裁剪 / min-max 索引裁剪状态的取值为NotPruned、PartitionPruned、MinMaxIndexPruned见 IcebergMetadataLog.cpp可用于观察查询执行期间 Iceberg 元数据裁剪是否生效——这是排查为什么读到了多余分区文件这类问题的重要线索。2.2 配套查询级设置iceberg_metadata_log_level该表通过查询级设置iceberg_metadata_log_level控制记录级别默认值为None不记录。其说明位于 src/Core/Settings.cpp明确指出通常该设置仅用于调试目的。使用方式示例-- 在会话中开启元数据日志级别仅根 metadata.json SET iceberg_metadata_log_level metadata; -- 或仅对单条查询生效 SELECT count() FROM iceberg_s3(https://bucket.s3.amazonaws.com/path/, key, secret) SETTINGS iceberg_metadata_log_level manifest_list_entry; -- 查询结束后在 system.iceberg_metadata_log 中查看本次查询记录的元数据 SELECT query_id, content_type, table_path, file_path, pruning_status FROM system.iceberg_metadata_log ORDER BY event_time;写入逻辑在 src/Interpreters/IcebergMetadataLog.h 的insertRowToLogTable模板函数中仅当当前上下文的iceberg_metadata_log_level不低于该行对应的日志级别时才真正写入而 src/Interpreters/IcebergMetadataLog.cpp 的insertRowToLogTableImpl通过全局上下文的getIcebergMetadataLog()见 src/Interpreters/Context.cpp获取系统表实例并追加日志行同时记录查询 ID 与时间戳。若日志表未配置会抛出BAD_ARGUMENTS异常。另外从 src/Storages/ObjectStorage/DataLakes/Iceberg/StatelessMetadataFileGetter.cpp 的存在可以看出Iceberg 元数据的读取与记录贯穿无状态元数据文件获取 → 日志写入的完整链路本系统表相当于为这条链路加上了可观测性。三、改进一Delta Lake 写入实验开关allow_experimental_delta_lake_writes本版本新增设置allow_experimental_delta_lake_writesPR #86180用于控制 Delta Lake 表的写入能力。3.1 设置定义与实验属性从 src/Core/Settings.cpp 可以看到该设置被标记为BETA测试阶段默认关闭。这意味着在 v25.8.2.29 中对 DeltaLake 表执行 INSERT 前需要显式开启SET allow_experimental_delta_lake_writes 1;作为对照同族实验开关在 src/Databases/enableAllExperimentalSettings.cpp 中统一管理allow_experimental_*系列设置均被纳入一键开启全部实验功能的机制中。3.2 配套的 DeltaLake 表引擎与表函数该设置服务于DeltaLake表引擎族。在 src/Storages/ObjectStorage/registerStorageObjectStorage.cpp 中注册了DeltaLake存储引擎并根据磁盘/配置类型选择 S3、Azure、本地对应的配置实现StorageS3DeltaLakeConfiguration、StorageAzureDeltaLakeConfiguration、StorageLocalDeltaLakeConfiguration同文件还注册了DeltaLakeS3、DeltaLakeAzure、DeltaLakeLocal等表函数见 registerStorageObjectStorage.cpp覆盖了常见对象存储与本地路径场景。典型的建表与写入流程-- 开启实验性写入v25.8.2.29 中的写法 SET allow_experimental_delta_lake_writes 1; -- 基于 S3 路径创建 DeltaLake 表 CREATE TABLE delta_table ENGINE DeltaLake(https://bucket.s3.amazonaws.com/path/, aws_access_key_id, aws_secret_access_key); -- 写入数据 INSERT INTO delta_table VALUES (...);需要说明的是Delta Lake 写入属于实验能力官方对版本差异有明确区分后续版本中该设置更名为allow_delta_lake_writes升级或跨版本使用时请以目标版本的 Setting 定义 为准并通过SELECT * FROM system.settings WHERE name LIKE %delta_lake%核对当前版本实际可用的设置名。四、改进二按日志通道启用 JSON 格式化本版本允许只对特定日志通道启用 JSON 格式化配置项为logger.formatting.channelPR #86331。在服务器默认配置 programs/server/config.xml 中formatting标签支持两种用法对所有通道生效省略channel标签仅对指定通道生效设置channel为syslog/console/errorlog/log之一。logger !-- 仅对 console 通道输出 JSON 日志 -- formatting typejson/type channelconsole/channel names date_timedate_time/date_time date_time_utcdate_time_utc/date_time_utc thread_namethread_name/thread_name thread_idthread_id/thread_id levellevel/level query_idquery_id/query_id logger_namelogger_name/logger_name messagemessage/message source_filesource_file/source_file source_linesource_line/source_line /names /formatting /logger配置要点摘自 config.xml 的注释说明目前仅支持json一种格式启用 JSON 日志前需取消整个formatting标签的注释可通过names下的标签值重命名字段名如把date_time改成自定义键名可注释掉names中不想要的属性例如不需要query_id就注释query_id标签若全部注释程序将打印默认字段。这一改进的实际价值在于生产环境中往往只有部分通道需要结构化输出如仅把 errorlog 交给日志采集系统做 JSON 解析此前全局 JSON 化的做法会破坏终端可读性本版本提供了精细化的控制粒度。五、Bug Fix官方稳定版中的七项行为修复本版本包含七项官方确认的用户可见修复覆盖存储、物化视图、内存跟踪、分布式协调等多个子系统。5.1 数据库副本恢复期间的表关闭顺序修复内容恢复数据库副本时不再错误地关闭表。此前不正确的关闭顺序会在数据库副本恢复过程中对部分表引擎触发LOGICAL_ERRORPR #84744。影响场景使用Replicated数据库ZooKeeper/Keeper 协调并在恢复期访问表的集群升级后可消除这类逻辑错误。5.2 从 SQL 创建磁盘时默认处理/etc/metrika.xml的 includes修复内容通过 SQL 创建磁盘CREATE DISK时现在会像其他配置路径一样默认处理来自/etc/metrika.xml的 include 替换PR #86232。影响场景依赖/etc/metrika.xml中定义的共享宏/凭据片段如clickhouse_remote_servers、S3 密钥宏来配置磁盘的用户此前从 SQL 建盘时这些 include 不会被展开可能得到错误或缺失的配置值。5.3 Azure blob 空文件读取的 Range 请求错误修复内容修复plain_rewritable磁盘从 Azure blob storage 读取空 blob 时抛出416 The range specified is invalid for the current size of the resource的问题PR #86400。影响场景使用 Azure Blob Storage 作为plain_rewritable类型磁盘且表中存在大小为零的空对象时相关查询会失败升级后空对象可被正常读取。5.4 同名重建的物化视图可能失效修复内容修复物化视图Materialized View被创建、删除、再以同名创建后可能不工作的问题PR #86413。影响场景频繁通过删表重建同名 MV来更新物化视图定义的用户此前可能遇到重建后 MV 不再接收/处理数据需要重启或额外操作才能恢复本修复保证同名重建后 MV 立即正常工作。5.5MergesMutationsMemoryTracking内存泄漏与query_views_log流式来源修复内容修复Buffer表导致的MergesMutationsMemoryTracking指标泄漏并修复从Kafka及其他流式来源读取时query_views_log的记录问题PR #86422。影响场景使用Buffer表承接写入、以及使用 Kafka 引擎表驱动物化视图MV 上游为 Kafka的用户。前者表现为内存跟踪指标虚高、可能触发不必要的内存限制后者表现为system.query_views_log中流式来源的视图执行记录缺失或不完整。5.6getSubcolumnType未初始化内存修复内容修复getSubcolumnType中使用未初始化内存的问题PR #86498。影响场景涉及子列subcolumn如map类型、Nullable结构、Tuple嵌套等类型推导的查询此前在特定路径下可能读到未初始化内存产生不可预期的结果甚至崩溃。5.7 关闭阶段日志刷盘异常处理修复内容关闭shutdown期间刷日志的异常现在会被忽略且关闭过程更安全避免SIGSEGVPR #86546。影响场景服务器停机/升级时若日志系统处于异常状态此前可能因刷盘异常导致进程段错误、退出码异常本修复保证关闭流程稳定完成。六、NOT FOR CHANGELOG 与测试修正以下变更不产生用户可见行为差异列出便于完整追踪发布内容数据库锁获取的重试逻辑在获取数据库锁时存在重试逻辑失败时抛出ErrorCodes::TIMEOUT_EXCEEDEDPR #86321属于锁竞争路径的内部行为收紧测试修正修复test_multiple_disks::test_system_tables测试PR #86338报错信息改进Iceberg Manifest 文件初始化错误信息更详细PR #86409便于定位元数据损坏问题NO CL CATEGORY一条未归类的小改动PR #86558对用户无感知。七、升级与验证建议针对本版本变更建议按以下顺序验证升级功能验证执行SELECT * FROM system.settings WHERE name IN (iceberg_metadata_log_level, allow_experimental_delta_lake_writes)确认新设置已生效对 Iceberg 表执行一次带iceberg_metadata_log_level的查询并检查system.iceberg_metadata_log落盘情况注意该表通过全局日志表机制写入默认关闭仅调试使用。配置验证若使用 JSON 日志检查logger.formatting.channel的生效通道是否符合预期参考 programs/server/config.xml 中的注释示例。回归验证重点回归物化视图同名重建、Buffer表内存指标、Azureplain_rewritable磁盘空对象读取以及数据库副本恢复四条路径对应本版本的 5.1、5.3、5.4、5.5 四项修复。行为差异提示Delta Lake 写入为实验功能跨小版本升级时设置名可能变化未来版本更名为allow_delta_lake_writes请以目标版本 Settings.cpp 的定义为准。八、版本发布内容速查表分类变更源码/配置参考用户可见性New Feature新增system.iceberg_metadata_log及iceberg_metadata_log_level设置src/Interpreters/IcebergMetadataLog.h、IcebergMetadataLog.cpp、Settings.cpp调试 Iceberg 查询元数据裁剪Improvement新增allow_experimental_delta_lake_writesBETA默认关闭Settings.cpp、registerStorageObjectStorage.cppDelta Lake 写入开关Improvementlogger.formatting.channel按通道 JSON 日志programs/server/config.xml日志输出格式控制Bug Fix ×7副本恢复关闭顺序、metrika.xml includes、Azure 空 blob 416、MV 同名重建、内存跟踪泄漏/query_views_log、getSubcolumnType 未初始化内存、shutdown 刷日志安全见第五节各条目对应场景下的错误行为消除内部修复DB 锁重试、测试修正、Iceberg 报错信息增强—无或仅日志信息通过本指南你可以按图索骥地验证 v25.8.2.29-lts 的各项变更并在升级后快速定位与之相关的行为变化。赞分享数据库OLAP列式数据库大数据实时分析数据分析【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址https://gitcode.com/GitHub_Trending/cli/ClickHouse点击查看免费下载相关推荐ClickHouse v25.8.3.66-lts 版本解析Delta Lake 写入控制、Iceberg 读取修复与 Keeper 递归删除优化ClickHouse v25.8.3.66 lts 版本解析Delta Lake 写入控制、Iceberg 读取修复与 Keeper 递归删除优化 导读 本文数据库OLAP列式数据库大数据实时分析数据分析ClickHouse v24.3.15.72-lts 版本变更全解析强制合并新特性、复制表元数据修复与关键 Bug 修复清单ClickHouse v24.3.15.72 lts 版本变更全解析强制合并新特性、复制表元数据修复与关键 Bug 修复清单 本指南基于 ClickHouse数据库OLAP列式数据库大数据实时分析数据分析ClickHouse v22.3.9.19-lts 发行版解析六个关键 Bug 修复与 LTS 回补机制ClickHouse v22.3.9.19 lts 发行版解析六个关键 Bug 修复与 LTS 回补机制 本文以 ClickHouse 官方 2022 年 C数据库OLAP列式数据库大数据实时分析数据分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考