ClickHouse v23.8.2.7-lts 变更解析分布式并行副本读取、IPv6 布隆过滤器与 S3Queue 实验性状态【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse本文基于 ClickHouse 官方发布说明 docs/changelogs/archive/v23.8.2.7-lts.md 展开聚焦该 LTS 补丁版本中的两项用户可见 Bug 修复分布式表并行读取副本、IPv6 布隆过滤器索引及一项内部变更S3Queue 引擎实验性状态声明并结合当前仓库源码逐一剖析其实现原理、相关设置与升级影响。读完本文你将能理解这两个修复背后的机制、如何在集群环境中正确启用并行副本读取以及布隆过滤器索引对 IPv6 列的支持边界与 S3Queue 引擎的使用约束。版本背景与发布说明结构v23.8.2.7-lts 是 ClickHouse 23.8 LTS 分支上的一个补丁版本基于 commitf73c8f37874对照基线为 v23.8.1.2992-ltscommitebc7d9a9f3b。该版本属于官方稳定发行分支LTS其发布说明按类型划分为两类变更Bug Fix用户可见的官方稳定版行为异常共两项分别是并行副本读取只使用单个副本的问题以及布隆过滤器对 IPv6 的向后兼容性问题。NOT FOR CHANGELOG / INSIGNIFICANT不写入对外变更日志的内部改动一项将 S3Queue 标记为实验性功能。这类补丁版发布说明记录了稳定分支在维护周期内的修正轨迹对升级评估和故障排查具有直接参考价值。修复一分布式表并行读取副本仅使用单副本的问题问题现象发布说明中记录的第一项修复对应 issue #54209、PR #54199指出通过 Distributed 表从副本并行读取时每个分片只使用一个副本。也就是说在执行分布式查询时尽管集群配置中一个分片包含多个副本查询发起端initiator却只从中选取一个副本参与读取导致多副本的计算能力没有被充分利用无法发挥并行副本读取parallel replicas带来的横向扩展效果。源码中的并行读取实现在当前的仓库源码中集群表包括cluster()表函数与 Distributed 存储引擎的读取扇出逻辑位于 src/Storages/IStorageCluster.cpp 的ReadFromCluster::read方法中其关键流程为读取设置max_parallel_replicas见 src/Storages/IStorageCluster.cpp#L168-L171size_t replica_index 0; auto max_replicas_to_use static_castUInt64(cluster-getShardsInfo().size()); if (current_settings[Setting::max_parallel_replicas] 1) max_replicas_to_use std::min(max_replicas_to_use, current_settings[Setting::max_parallel_replicas].value);默认上限为集群分片数若设置值大于 1则取两者较小值作为本次查询最多参与的副本数量。遍历每个分片通过shard_info.pool-getMany(...)以PoolMode::GET_ONE模式只取该分片的一个连接把所有副本当作分片来构建管道见 src/Storages/IStorageCluster.cpp#L177-L217并为每个远程执行器携带ReplicaInfo{number_of_current_replica}最终Pipe::unitePipes合并所有远端数据流。从源码结构可以推断修复前的缺陷正是出在每个分片只取一个连接GET_ONE与按副本数扇出之间的协调逻辑上当max_parallel_replicas设置正确、且存在多个副本时读取应针对每个副本分别建立连接并分配不同的数据片段而旧逻辑在某些路径下退化为单副本连接即每个分片只返回一个副本的数据。相关设置与正确用法并行副本读取由一组联动设置控制其完整定义位于 src/Core/Settings.cpp设置默认值说明allow_experimental_parallel_reading_from_replicas别名enable_parallel_replicas00 关闭1 开启并在失败时静默降级2 开启并在失败时抛出异常见 src/Core/Settings.cpp#L8265-L8268max_parallel_replicas1000每个分片参与查询执行的最大副本数正整数见 src/Core/Settings.cpp#L8277-L8300parallel_replicas_custom_key任意整数表达式用于在副本间切分工作单分片多副本集群下会把副本转成虚拟分片parallel_replicas_modeREAD_TASKS自定义键的过滤方式default对自定义键取模或range按取值范围切分cluster_for_parallel_replicas当前服务器所在分片的集群名Cloud 默认defaultparallel_replicas_count/parallel_replica_offset0内部设置由发起端自动写入用户不应直接使用见 src/Core/Settings.cpp#L8304-L8309设置文档同时给出了性能注意事项src/Core/Settings.cpp#L8290-L8295并行执行可能因以下场景反而变慢——采样键在分区键中的位置导致范围扫描效率低下、为添加采样键而牺牲了其他列的过滤效率、采样键本身计算昂贵、以及集群延迟长尾分布使查询整体延迟上升。因此是否启用并行副本读取需要结合数据分布与集群拓扑评估。对于max_parallel_replicas 1的场景还需注意相关设置parallel_replicas_for_non_replicated_merge_tree默认false若为true非复制 MergeTree 表也会采用并行副本算法。此外src/Storages/StorageMergeTree.cpp#L1270 中可以看到在普通非复制MergeTree 的本地执行路径中会显式将max_parallel_replicas置为 1这与上述设置互为印证。验证建议升级到包含该修复的版本后可通过以下方式验证并行读取是否生效在启用enable_parallel_replicas与max_parallel_replicas 1后执行EXPLAIN查看计划中是否出现多个副本的读取分支观察system.query_log中各副本节点实际参与查询的数量对比修复前后多副本集群上的分布式聚合查询耗时与 CPU 利用率。修复二布隆过滤器索引恢复对 IPv6 的支持问题现象第二项修复对应 issue #54233、PR #54200描述为允许布隆过滤器使用 IPv6修复向后兼容性问题。这意味着在早期稳定版本中布隆过滤器bloom_filter跳过索引对 IPv6 类型的列失效导致依赖该索引的等值/IN 类过滤无法正确裁剪数据 part查询被迫扫描更多数据该修复恢复了 IPv6 与布隆过滤器索引的兼容行为。布隆过滤器索引支持的类型布隆过滤器索引的列类型校验位于 src/Storages/MergeTree/MergeTreeIndexBloomFilter.cpp 的assertIndexColumnsType中if (!which.isUInt() !which.isInt() !which.isString() !which.isFixedString() !which.isFloat() !which.isDate() !which.isDateTime() !which.isDateTime64() !which.isEnum() !which.isUUID() !which.isIPv4() !which.isIPv6()) throw Exception(ErrorCodes::ILLEGAL_COLUMN, Unexpected type {} of bloom filter index., type-getName());当前源码明确允许isIPv4()与isIPv6()参与布隆过滤器索引这与发布说明中恢复 IPv6 支持的修复方向一致。同样MergeTreeIndexBloomFilterText.cpp的文本类布隆过滤器也支持String、FixedString与IPv6类型见 src/Storages/MergeTree/MergeTreeIndexBloomFilterText.cpp#L1040。索引工作机理布隆过滤器索引在查询侧的匹配逻辑位于 src/Storages/MergeTree/KeyCondition.cppprepareBloomFilterDatasrc/Storages/MergeTree/KeyCondition.cpp#L7055-L7056接收hash_one单值哈希与hash_many列值批量哈希两个回调将等值条件、IN、与范围边界转换为探针哈希集合对IN集合会先排序去重避免重复哈希与碰撞冲突src/Storages/MergeTree/KeyCondition.cpp#L7110-L7133mayExistOnBloomFiltersrc/Storages/MergeTree/KeyCondition.cpp#L1373-L1390逐列调用findAnyHash做存在性检测若任一探针哈希未命中则将该 part 直接裁剪。布隆过滤器本质是宁可误报、绝不漏报的概率结构某列任一探针哈希未命中即可安全跳过 part全部命中则仍需进一步验证。因此 IPv6 支持恢复后WHERE ip ::1或WHERE ip IN (...)这类查询可以在 part 级完成裁剪显著减少扫描量。从源码结构看IPv6 在 ClickHouse 内部基于定长字节表示其哈希与 UUID/FixedString 走同一条布隆过滤器哈希管线这也是修复只需在索引类型校验与哈希转换路径上放开限制即可的原因。布隆过滤器索引的创建示例CREATE TABLE events ( id UInt64, client_ip IPv6, user_agent String, INDEX bf_ip client_ip TYPE bloom_filter GRANULARITY 1, INDEX bf_ua user_agent TYPE bloom_filter GRANULARITY 1 ) ENGINE MergeTree ORDER BY id;其中GRANULARITY 1表示每个索引粒度默认 8192 行维护一个布隆过滤器bloom_filter索引构造函数中的误判率参数默认为0.025可显式指定如TYPE bloom_filter(0.01)见 src/Storages/MergeTree/MergeTreeIndexBloomFilter.cpp#L1342-L1353。需要说明的是当前源码为 23.8 之后的版本状态若你正运行或评估 23.8 分支请以该分支实际代码与官方发布说明为准。内部变更S3Queue 表引擎被标记为实验性发布说明第三条PR #54214属于NOT FOR CHANGELOG类别S3Queue 是实验性的experimental。这条声明的含义是在 v23.8.2.7-lts 时期S3Queue 表引擎仍处于实验性阶段官方不建议将其用于生产环境的关键路径变更日志对外不宣传该特性。S3Queue 引擎的定位S3Queue 是 ClickHouse 提供的对象存储流式导入表引擎用于持续消费 S3及 Azure Blob桶中出现的新文件功能定位与 Kafka、RabbitMQ 引擎类似但面向 S3 生态。其注册与完整说明位于 src/Storages/ObjectStorageQueue/registerQueueStorage.cpp该文件内嵌了引擎的官方文档字符串引擎名称集合为{S3Queue, AzureQueue}见 src/Storages/ObjectStorageQueue/StorageObjectStorageQueue.h#L122核心实现位于 src/Storages/ObjectStorageQueue/StorageObjectStorageQueue.cpp。引擎参数与三种处理模式CREATE TABLE s3queue_engine_table (name String, value UInt32) ENGINE S3Queue(path, [NOSIGN, | aws_access_key_id, aws_secret_access_key,] format, [compression], [headers], [extra_credentials]) [SETTINGS] [mode ,] [after_processing keep,] [keeper_path ,] [processing_threads_num 16,] [parallel_inserts false,] [enable_logging_to_queue_log true,] [last_processed_path ,] [tracked_files_limit 1000,] [tracked_file_ttl_sec 0,] [polling_min_timeout_ms 1000,] [polling_max_timeout_ms 600000,] [polling_backoff_ms 30000,] [cleanup_interval_min_ms 60000,] [cleanup_interval_max_ms 60000,] [buckets 0,] [enable_hash_ring_filtering 0,] [max_processed_files_before_commit 100,] ...引擎参数与 S3 表引擎一致。核心设置包括设置默认值说明mode24.6 前默认ordered24.6 起必须显式指定unorderedZooKeeper 记录全部已处理文件、ordered按字典序处理仅记录最大已消费文件名要求后加入的文件名字典序更大、exclusive不记录任何元数据要求 URL 唯一适用于高吞吐/自托管场景after_processingkeep处理成功后文件处置keep/delete/move/tagafter_processing_retries10后处理动作的重试次数processing_threads_numCPU 数或 16处理线程数仅对unordered/exclusive模式生效parallel_insertsfalse默认多线程只并行下载与解析单条 INSERT置true可并行 INSERT会产生更多数据 partkeeper_path/ZooKeeper 队列元数据路径支持{database}/{uuid}宏与辅助 Keeper 前缀loading_retries10文件加载重试次数tracked_files_limit1000unordered模式下 ZooKeeper 节点上限超出后删除最旧记录会重新处理tracked_file_ttl_sec0已处理文件在 ZooKeeper 中的保留秒数0 为永久到期后文件被重新导入polling_min_timeout_ms/polling_max_timeout_ms/polling_backoff_ms1000/600000/30000轮询最小/最大间隔与无新文件时的退避增量buckets0ordered模式下的逻辑线程数分布式场景建议不小于副本数详见下方说明persistent_processing_node_ttl_seconds216006 小时非优雅停机残留处理节点的清理 TTLbuckets的设置要点来自引擎文档 src/Storages/ObjectStorageQueue/registerQueueStorage.cpp#L576-L578在分布式多副本场景下每个处理线程通过文件名哈希抢占某个桶进行加锁处理因此buckets至少应等于副本数最优值约为副本数 × processing_threads_num。实验性状态的实践含义在 v23.8.x 这一代版本中S3Queue 属于实验性能力。这意味着其行为、设置名与默认值可能在不同小版本间变化如mode默认值的变更、24.7 起设置可省略s3queue_前缀、24.10 起可通过system.s3_queue_settings查看表设置官方文档在 24.6/24.7 等后续版本对buckets、processing_threads_num、持久化处理节点等行为做了多次调整说明该引擎处于快速演进期若在 23.8 分支使用该引擎应锁定版本并充分验证或优先选择 Kafka/RabbitMQ 等成熟流式引擎。流式消费的典型用法S3Queue 的正确打开方式是配合物化视图形成对象存储 → 实时导入的数据管道用 S3Queue 引擎创建表将其视为数据流创建目标结构表创建物化视图将 S3Queue 表的数据转换后写入目标表。当物化视图挂载后引擎开始后台持续收集数据。CREATE TABLE s3queue_engine_table (name String, value UInt32) ENGINES3Queue(https://example-bucket.s3.amazonaws.com/my-test-bucket-768/*, CSV, gzip) SETTINGS mode unordered; CREATE TABLE target_table (name String, value UInt32) ENGINE MergeTree ORDER BY name; CREATE MATERIALIZED VIEW queue_mv TO target_table AS SELECT name, value FROM s3queue_engine_table;引擎还支持基于extra_credentials(role_arn arn:aws:iam::...:role/role)的 S3 角色访问方式见 src/Storages/ObjectStorageQueue/registerQueueStorage.cpp#L553-L566。默认禁止对 S3Queue 表直接SELECT防止误读导致数据丢失调试时需要显式开启stream_like_engine_allow_direct_select并结合commit_on_select默认False保留数据、True读取后移除控制读取语义。升级与验证建议汇总针对本版本的三项变更建议按以下清单评估与验证并行副本读取确认集群配置中分片内副本数正确若要启用需同时配置enable_parallel_replicas、max_parallel_replicas、cluster_for_parallel_replicas与parallel_replicas_custom_key或依赖SAMPLE键升级后通过EXPLAIN与system.query_log验证多副本是否真正参与读取。IPv6 布隆过滤器若表在 IPv6 列上建了bloom_filter索引升级后无需重建索引即可恢复 part 级裁剪能力可用system.data_skipping_indices检查索引状态并通过EXPLAIN indexes 1观察索引是否被命中。S3Queue仅当明确知晓其实验性风险时使用关注mode、buckets、processing_threads_num、after_processing等设置在不同小版本间的语义差异生产建议锁定版本并保留 ZooKeeper 元数据备份。发布说明的完整归档位于 docs/changelogs 目录每个补丁版本的原始条目均可追溯对应的问题与 PR 编号便于在升级时做针对性回归测试。【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考