ClickHouse AggregateFunction(sumForEach,Array(UInt32))类型转换方法

ClickHouse 原生不支持不同内层数值类型的 AggregateFunction 类型直接转换，sumForEach 聚合状态的二进制存储格式和内层数组元素类型强绑定，直接通过 INSERT...SELECT 写同名字段、或者直接 ALTER TABLE MODIFY COLUMN 改列类型都会触发你遇到的报错，对于底层为ReplicatedSummingMergeTree + 上层Distributed表的架构，错误操作还会导致副本同步中断、数据损坏。

方案1：状态反解重聚合迁移（推荐） #

该方案不需要长时间停写，无数据损坏风险，适配所有版本的ClickHouse：

• 前置准备：在所有分片的每个副本上，创建新的目标本地表，表的引擎参数、分区键、排序键、TTL等配置和原本地表完全一致，仅将valuesCol字段类型定义为AggregateFunction(sumForEach, Array(Int32))；再创建新的Distributed表，指向新创建的本地表，分片键、副本配置和原分布式表保持一致。
• 分批迁移数据：在每个分片本地执行写入语句，不要通过分布式表跨分片写入，避免数据shuffle导致聚合结果错误，核心逻辑是先把原聚合状态还原为计算后的值，做类型转换后重新生成目标类型的聚合状态，参考SQL：

-- 可以按分区粒度分批执行，避免单次写入占用过多内存
INSERT INTO 新本地表
SELECT
  -- 这里按原表结构把除valuesCol外的所有字段按顺序写上
  分区字段, 排序键字段1, 排序键字段2, 其他维度字段,
  sumForEachState(CAST(sumForEachMerge(valuesCol) AS Array(Int32))) AS valuesCol
FROM 原本地表
-- 按分区筛选的话加WHERE条件，比如 WHERE toYYYYMM(pt_date) = 202401
GROUP BY 分区字段, 排序键字段1, 排序键字段2, 其他维度字段

• 校验切流：全量数据迁移完成后，抽样对比原表和新表同维度下sumForEachMerge(valuesCol)的输出结果，确认数值完全一致后，将业务写入、查询流量切到新的分布式表，观察无异常后下线旧表即可。

方案2：元数据修改离线迁移（适合超大表，节省重聚合资源） #

该方案需要停全量写入，操作前必须做全量数据备份，适合数据量达到TB级、重聚合耗时过长的场景：

• 停掉所有流向该表的写入，查询system.merges表，确认所有副本上该表没有正在运行的后台合并任务，等所有待合并的数据块全部处理完成。
• 对每个分片的每个副本，依次执行卸载表命令：DETACH TABLE 原本地表。
• 登录对应副本的服务器，找到该表的元数据文件（默认在/var/lib/clickhouse/metadata/库名/表名.sql路径下），将文件中valuesCol的类型定义从AggregateFunction(sumForEach, Array(UInt32))修改为AggregateFunction(sumForEach, Array(Int32))，保存文件。
• 执行挂载命令重新加载表：ATTACH TABLE 原本地表，随后执行OPTIMIZE TABLE 原本地表 FINAL强制触发全量数据重写，把所有历史数据块的字段类型转为目标类型。
• 所有副本都完成上述操作后，刷新分布式表的元数据缓存，恢复业务写入即可。

• 不要直接执行ALTER TABLE 原表 MODIFY COLUMN valuesCol AggregateFunction(sumForEach, Array(Int32))，该操作只会修改元数据，不会重写历史数据，后续查询、副本同步、后台合并都会持续报类型不匹配错误。
• 不要直接拷贝原表的物理数据文件到新表目录，两种类型的聚合状态二进制格式不兼容，直接读取会出现数值溢出、乱码问题。

内容的提问来源于stack exchange，提问作者Timofey Gorshkov