ClickHouse v24.5 版本全解析：从 Dynamic 类型、UUIDv7 到全文本索引迁移的实践指南

ClickHouse v24.5 版本全解析从 Dynamic 类型、UUIDv7 到全文本索引迁移的实践指南【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse导读本文基于 ClickHouse v24.5.1.1763-stable 的官方 Changelog 整理而成。v24.5 是 ClickHouse 2024 年度的重要稳定版本带来了Dynamic 动态类型、UUIDv7 时间戳型 UUID 函数族、嵌入式 RocksDB 批量导入、S3 归档文件查询等一批影响深远的新特性同时通过inverted indexes更名full-text indexes引入了必须人工介入的向后不兼容变更。读完本文你将系统掌握 v24.5 的升级注意点、新函数与新增配置的使用方法、性能优化手段以及该版本修复的关键 Bug 清单可直接用于升级评估与生产实践。一、升级必读向后不兼容变更Backward Incompatible Changev24.5 引入了三项影响既有集群行为的变更升级前必须逐条核对。1.1 inverted indexes 更名为 full-text indexes将面向开发者的技术术语inverted indexes倒排索引更名为更友好的full-text indexes全文索引。由于内部表元数据随之改变该变更会破坏所有已存在的实验性 inverted indexes 表。官方要求升级前DROP INDEX删除此类索引升级后重新创建索引。1.2 四个函数被标记废弃neighbor、runningAccumulate、runningDifferenceStartingWithFirstValue、runningDifference这四个函数因易用错、语义容易产生误导而被废弃deprecated。官方建议改用标准窗口函数window functions实现同类需求。若确有兼容需要可显式设置allow_deprecated_functions1恢复使用。注意该设置在后续版本中进一步更名为allow_deprecated_error_prone_window_functions参见 changelog 中的Rename allow_deprecated_functions to allow_deprecated_error_prone_win...条目。1.3 system.columns 权限语义收紧当列数量很多、且大量数据库/表未授予SHOW TABLES权限时system.columns查询会更快。但行为上有重要变化旧版本对单个列授予SHOW COLUMNS即使未对对应表授予SHOW TABLESsystem.columns仍会显示这些列新版本将整体跳过整张表。同时移除了拖慢查询的 trace 日志 Access granted / Access denied。二、新特性New Feature深度解读2.1 Dynamic 动态类型一张表装下任意类型v24.5 引入Dynamic数据类型允许在不知道全部类型的情况下存储任意类型的值相当于列级别的多态容器。该类型需通过设置allow_experimental_dynamic_type开启源码中可见其随版本演进为MAKE_OBSOLETE状态即新版默认放开的实验特性。该特性为后续 JSON 类型、Variant 类型等灵活 schema 能力奠定了基础尤其适合半结构化日志、动态事件数据的存储场景。2.2 UUIDv7 函数族与 UUID 工具函数这是本版本最受关注的函数类新特性实现在 src/Functions/generateUUIDv7.cpp 中新增函数包括函数说明generateUUIDv7()生成标准版本 7 UUID基于 RFC 9562带单调计数器generateUUIDv7ThreadMonotonic()线程内单调版本性能与单调性折中generateUUIDv7NonMonotonic()非单调版本性能优先UUIDToNum()提取 UUID 的原始字节UUIDv7ToDateTime()提取 UUIDv7 中的时间戳分量从源码看实现细节非常值得注意位布局见 src/Functions/UUIDv7Utils.hUUIDv7 由 48 位unix_ts_ms时间戳 4 位版本号ver 42 位计数器counter_high_bits 12 位 counter_low_bits 30 位 2 位 variant 标记 62 位随机分量rand_b组成性能技巧clock_gettime(CLOCK_REALTIME, ...)按数据块chunk而非每条记录调用一次在满足 UUID 标准的前提下减少系统调用开销并发保证通过SharedMutex 静态计数器字段CounterFields保证同一时间戳内跨线程生成的 UUID 计数器单调确定性isDeterministic()返回false并且支持传入一个可选表达式参数generateUUIDv7(expr)以绕过公共子表达式消除CSE避免查询中多次调用返回相同值。典型用法SELECT generateUUIDv7(number) FROM numbers(3); -- ┌─generateUUIDv7(number)───────────────┐ -- │ 019947fb-5766-7ed0-b021-d906f8f7cebb │ -- ... -- 提取时间戳 SELECT UUIDv7ToDateTime(generateUUIDv7());2.3 StorageEmbeddedRocksDB 批量导入SST Bulk Loading为嵌入式 RocksDB 存储引擎引入批量加载通过直接创建并摄入 SST 文件绕开 RocksDB 内置 memtable显著提升导入速度尤其对长时运行的 INSERT效果明显。同时新增了StorageEmbeddedRocksDB表级设置项。注意该特性在 v24.5 开发期间经历过一次 Revert 后重新合入changelog 的 NO CL ENTRY 部分可见Revert Introduce bulk loading to StorageEmbeddedRocksDB及其后续合并最终以 #63324 的版本正式发布。2.4 S3 存储与归档文件查询S3 磁盘和s3表函数现在支持直接遍历 S3 上的归档文件如 tar 等格式内部的文件进行查询解决了此前无法从归档中选数的痛点对日志归档分析场景价值明显。2.5 非等值 JOIN 条件支持涉及左右两表列的非等值连接条件例如t1.y t2.y。启用方式SET allow_experimental_join_condition 1;该设置在源码 src/Core/SettingsChangesHistory.cpp 中也有记录属于实验性开关。2.6 新的输入/输出格式与解析能力Form 格式支持读写单条application/x-www-form-urlencoded编码记录npy 输出格式支持输出 NumPy.npy格式相关测试覆盖了不同字节序TSV 解析 CRLF新增设置input_format_tsv_crlf_end_of_line定义于 src/Core/FormatFactorySettings.h解决 Windows 风格 CRLF 行结束符的 TSV 解析问题强制 NULL 填充新增设置input_format_force_null_for_omitted_fields同样定义于 FormatFactorySettings.h对省略字段强制写入 NULL 而非默认值Raw 格式别名Raw成为TSVRaw的同义词。2.7 CROSS JOIN 优化与压缩支持在 CROSS JOIN 中进行压缩新增cross_join_min_rows_to_compress默认 10000000 行与cross_join_min_bytes_to_compress默认 1 GiB两个设置定义于 src/Core/Settings.cpp当结果规模超过阈值时启用压缩CROSS JOIN 结果超出内存限制时可溢出到临时文件继续执行。2.8 新增 clamp 条件函数支持条件函数clamp将值限制在 [min, max] 区间内实现位于src/Functions目录。2.9 STDOUT 重定向自动压缩在 Linux/macOS 上若程序 STDOUT 被重定向到带压缩扩展名的文件将自动采用对应压缩方法行为与INTO OUTFILE一致例如clickhouse-client --query SELECT 1 out.gz会直接产出 gzip 压缩文件。2.10 Azure Workload Identity 认证s3/AzureBlobStorage 相关表函数与配置支持use_workload_identity参数可直接使用 Azure Workload Identity 对 Azure Blob Storage 进行认证适配 Azure 托管应用场景。三、性能改进Performance Improvementv24.5 的性能优化覆盖面广值得在生产环境中验证收益优化点内容备注投影Projection块合并跳过INSERT 期间跳过新创建投影块的合并提升写入吞吐UTF8 字符串函数 ASCII 快路径输入全为 ASCII 时按asciily处理整体提速 1.07x~1.62x部分场景峰值内存下降实现于src/FunctionsStorageS3 选择 glob 性能改进{}选择通配符的处理新排序合并配置新增prefer_merge_sort_block_bytes控制多列合并排序时的内存与速度最多可提速 2 倍clickhouse-local 启动加速修复此前未删除临时目录的问题启动更快新分析器微优化针对 analyzer 的微优化DateTime 与 DateTime64 索引分析DateTime与DateTime64比较时索引分析生效对应修复 #63441 / #63532set 类型索引加速去掉垃圾数据后 set 索引约提速 1.5 倍文件系统缓存减少缓存竞争第 4 部分允许通过keep_free_space_size(_elements)_ratio做后台额外驱逐其中prefer_merge_sort_block_bytes特别适合列数多、内存受限的合并排序场景system.columns的权限检查优化则在大集群运维中收益明显。四、常规改进Improvement4.1 数据类型与函数Map 键类型扩展Float32、Float64、Array(T)、Map(K,V)、Tuple(...)均可作为 Map 的键groupArray 大小限制新增aggregate_function_group_array_has_limit_size设置可在特定场景丢弃部分数据以避免内存膨胀后续版本更名为group_array_has_limit_sizeKeyed hashing 函数修复 Array 与 Map 配合 Keyed 哈希函数及物化键的支持。4.2 配置与运维YAML Merge Key 支持配置可引用 YAML 锚点合并:并支持从 YAML 文件进行配置替换substitutionReplicated 库自动恢复若某个 DDL 任务连续失败超过max_retries_before_automatic_recovery默认 100 次且错误相同自动将该副本标记为 lost 并启动恢复同时修复了早期异常可能跳过 DDL 条目的问题max_block_size0自动纠正为默认值plain_rewritable 元数据本地与 Azure 对象存储启用plain_rewritable元数据格式S3 场景可通过endpoint_subpath设置共享同一 endpoint对象存储磁盘支持 TRUNCATEMaterializedMySQL允许在未连接 MySQL 的情况下创建数据库INSERT 尾随逗号INSERT INTO test (a, b, c, ) VALUES ...现在合法Values 格式尾随逗号VALUES (4, 5, 6,)现在合法Pretty 格式stdout 非 TTY 时禁用output_format_pretty_max_rows/output_format_pretty_max_value_width限制多行字符串边框保留、列宽正确计算忽略 ANSI 转义序列Unicode 引号支持查询中出现英文风格 Unicode 引号如 “Hello”、‘world’时自动兼容方便从 Word 等文档复制 SQL。4.3 查询与客户端体验clickhouse-local 位置参数clickhouse/ch可直接把查询或查询文件作为位置参数例如ch SELECT 1、ch --param_test Hello SELECT {test:String}、ch query.sql客户端建议os_user与client_hostname现在能在命令行建议中正确设置skim 建议选择建议后保留终端原有数据进度条system.zeros/system.zeros_mt与generateRandom表函数的简单 LIMIT 查询也有进度条且总记录数超过max_rows_to_read时提前抛异常。4.4 存储与对象存储system.parts_columns增加 TTL 信息trace_log增加build_idALIAS 列便于检测二进制变更后自动改名Azure Blob 备份改用 multi-copy并支持跨容器原生 copynative copySystem.remote_data_paths相关并发删除场景的健壮性增强。五、构建/测试/打包改进Build/Testing/Packaging编译器升级ClickHouse 改由clang-18构建启用大量 clang-tidy-18 新检查新平台实验性支持loongarch64重新启用 s390x CI 构建aarch64 Linux 交叉编译启用 gRPCApache Datasketches 库更新CI 符号数据库每个构建的每个编译单元的符号信息收集到 CI 数据库binary_symbols表便于二进制问题定位Dockerfile 通过 docker 官方镜像库审查对应 upstream docker-library 的 #15846。六、Bug 修复与稳定性Bug Fix Critical Bug Fix6.1 关键修复数据正确性 / 崩溃类多分片备份修复修复多分片场景下备份失败的问题#56566FINAL 查询错误结果表未使用自适应粒度时FINAL查询给出错误结果FINAL 与分布式查询修复非 MergeTree 表远程查询带finaltrue时错误抛出 Storage doesnt support FINALWindow 函数与优化器query_plan_remove_redundant_distinct在新分析器下破坏 WINDOW 函数查询#62820新分析器禁止 WINDOW 重定义#63539GROUPING SETSGROUPING SETSWHEREgroup_by_use_nullstrue组合的逻辑错误#60538并行副本并行副本读取物化视图导致错误查询结果skip_unused_shards1LIMIT BY 新分析器时的 Not found column分布式查询修复罕见分布式查询结果缺数据、递归 CTE 分布式查询、常量 CTE 在 GROUP BY 键中报 Cannot find column 等问题查询缓存权限绕过查询缓存现在区分不同数据库中的相同查询避免绕过缺表读取权限安全修复backportedenable_vertical_final 默认关闭该设置因存在数据错误 Bug#64543被默认禁用Critical Bug Fixbackported #64591并行读缓冲卡死max_download_thread 0时线程无法分配导致查询卡死SIGSEGV 修复CPU/Real profilerquery_profiler_real_time_period_ns/query_profiler_cpu_time_period_ns自 2022 年以来的偶发崩溃尤其在分布式引擎下aarch64 上 SIGSEGV 信号栈过小的 unwind 崩溃。6.2 格式与解析修复Parquet分析器下 Parquet filter pushdown 失效修复KQL 表函数交互模式下客户端中止问题修复二进制反序列化加固不可信二进制输入以更安全方式反序列化HTTP 无效压缩数据改抛CANNOT_DECOMPRESS而非CORRUPTED_DATARegexp 格式异常信息更友好。6.3 存储与复制修复MergeTree 转 Replicated 校验若 zookeeper 中该表路径已存在则禁止转换该修复后续曾 Revert见 NO CL ENTRY 条目需以最终发布版本行为为准部分相交处理DROP range 重启后相交 part 修复cgroups v2 检测异常位置的 cgroups v2 内存控制器检测改进Lazy 数据库 DROP确保 DROP 后所有磁盘数据被清理避免孤儿文件Buffer 表 PREWHERE修复Logical error: Bad cast#64172。6.4 Keeper / 客户端修复keeper-client 的find_super_nodes/find_big_family修复ZNONODE 处理、超节点内查找、子树节点计数Keeper 忽略text_log配置。七、v24.5 升级与验证清单综合以上变更给出面向生产的升级建议清单检查 inverted indexes升级前SHOW INDEX排查并删除实验性倒排索引升级后按新语法重建为 full-text index审计废弃函数全局搜索neighbor、runningAccumulate、runningDifference等调用替换为窗口函数lag、runningAccumulate替代方案等若短期无法替换临时SET allow_deprecated_functions 1核对权限模型确认依赖system.columns且未授予SHOW TABLES的账户是否有查询依赖避免升级后列不可见评估新特性收益对 S3 归档、RocksDB 批量导入、UUIDv7 主键、Dynamic 类型等新能力做小规模验证后再推广关注回归风险点enable_vertical_final已默认关闭若此前手动开启需评估数据正确性影响query_plan_remove_redundant_distinct对 window 查询的破坏已修复但升级后建议跑一遍涉及 WINDOW 的回归测试跟踪 backport本 changelog 中多个修复标注了 Backported in #xxxxx说明在后续补丁版如 v24.5.x 后续 patch中继续跟进生产环境应升级到包含这些 backport 的最新补丁版。八、从 Changelog 到源码的阅读指引UUIDv7 完整实现与文档示例src/Functions/generateUUIDv7.cpp、位布局与计数器并发控制见 src/Functions/UUIDv7Utils.h格式相关设置定义src/Core/FormatFactorySettings.hinput_format_tsv_crlf_end_of_line、input_format_force_null_for_omitted_fieldsCROSS JOIN 压缩阈值设置src/Core/Settings.cppcross_join_min_rows_to_compress默认 10000000、cross_join_min_bytes_to_compress默认 1 GiB实验特性开关演进src/Core/SettingsChangesHistory.cppallow_experimental_join_condition、allow_experimental_dynamic_type等服务端配置模板programs/server/config.xml客户端配置参考 programs/client/config.xml完整历史 Changelog 归档docs/changelogs/ 目录可对照查看 v24.4、v24.3 LTS 等相邻版本的行为差异。总而言之ClickHouse v24.5 是一个新能力密集、升级动作明确的版本Dynamic 类型与 UUIDv7 为 schema-less 与分布式 ID 生成提供了官方级方案S3 归档查询与 RocksDB 批量导入显著降低了特定场景的 IO 成本而全文本索引更名与四函数废弃则要求升级前做好索引重建与 SQL 改写规划。结合本仓库的源码与配置实现可以快速验证并落地这些能力。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考