Bucket Table 动态扩容最佳实践--ByteHouse云数仓版-火山引擎

文档中心

ByteHouse云数仓版

数据建模

Bucket Table 动态扩容最佳实践

ByteHouse 新增支持了分桶表（bucket table）动态扩容功能，支持动态调整包括唯一键表在内的存储桶表的总存储桶数。

注意事项

该功能当前正在灰度发布中，若使用中遇到问题，可提交工单或联系 ByteHouse 团队。

功能概述

分桶表动态扩容是指您可根据数据表中数据量或负载的变化，调整分桶的数量或分布。当分桶表中的数据持续增长或查询负载增加时，原有的桶数量可能不足以高效处理数据，影响查询性能。分桶表动态扩容功能支持通过调整桶的数量或分布很好地解决这一问题，优化负载均衡，提升查询并行度。
ByteHouse 分桶表动态扩容功能基于 settings 参数实现，当前 ByteHouse 支持如下 settings 参数，本文将结合具体场景说明如何使用 settings 参数。

Settings 参数	说明
enable_recluster_multiple_parts	表设置，启用后可减少分桶后输出 parts 的数量，提升查询性能。默认值为 0（关闭），可设置为 1（开启）。
enable_scale_bucket_optimization	表设置，启用后支持 select 查询时使用新的分桶键表达式。该功能也适用于由于调整分桶数量导致的不同 parts 分桶总数不同的场景。如果未启用，查询时将仍使用旧的分桶键，无法使用新的分桶键表达式。默认值为 0（关闭），可设置为 1（开启）。
force_modify_unique_table_cluster_by	查询设置，用于修改唯一键表中的 `cluster by` 语句。默认值为 0（关闭），可设置为 1（开启）。
enable_legacy_cluster_by	查询设置，启用后支持使用新的分桶键表达式（`CLUSTER BY expression`）和旧的分桶键语法（`CLUSTER BY <column_name>`）修改分桶定义。默认值为 1（开启）。将该值设置为 0（关闭）后，仅支持使用新的分桶键表达式创建分桶表和修改桶数量。

场景 1：将非分桶表调整为分桶表

操作步骤

使用 ALTER TABLE 命令添加分桶表达式。

ALTER TABLE t MODIFY CLUSTER BY EXPRESSION cityHash64V2(x + y) INTO 4 BUCKETS SETTINGS enable_legacy_cluster_by=1 [, force_modify_unique_table_cluster_by=1]

ALTER TABLE t MODIFY SETTINGS enable_recluster_multiple_parts=1

参数说明如下：

参数	是否必填	说明
`ALTER TABLE t`	是	指定需要调整的表名。
`MODIFY CLUSTER BY EXPRESSION cityHash64V2(x + y)`	是	使用表达式定义分桶键。为实现更好的性能表现，建议使用`cityHash64V2`包装表达式。其中 x、y 为列名，x + y 表示列名拼接。
`INTO 4 BUCKETS`	是	定义分桶数。
`SETTINGS`	是	配置参数。使用 settings 参数执行分桶表动态扩容相关操作。

按需执行如下任一命令，执行重新分桶操作，将新的分桶键应用于存量数据。重新分桶任务将异步运行。
- 指定某个分区
  将命令中的 “2025-04-14” 替换为您实际设置的分区键。
```
ALTER TABLE t RECLUSTER PARTITION '2025-04-14'  
```
- 指定所有分区
```
ALTER TABLE t RECLUSTER PARTITION WHERE 1=1  
```
- 指定条符合条件的分区
```
ALTER TABLE t RECLUSTER PARTITION WHERE ...  
```
您可通过以下命令查看任务状态。
```
SELECT * FROM system.mutations WHERE database='...' and table = '...'
```
更改表设置，后续 select 查询时将支持使用新的分桶键表达式。
```
ALTER TABLE t MODIFY SETTINGS enable_scale_bucket_optimization=1
```

场景 2：扩容现有桶数

注意事项

扩容分桶后，表中的存量数据不会移动/重新分桶，但并不影响正常使用。如需进一步优化存量数据，您可以继续执行步骤 2 的命令将存量数据重新分桶。

操作步骤

修改分桶数量。新设定的桶数量必须是之前设定的桶数量的倍数。
以如下命令为例，假设初始的桶数为 4，执行该命令后，新插入的数据将存入 8 个桶中。
```
ALTER TABLE t MODIFY SETTING enable_recluster_multiple_parts=1, enable_scale_bucket_optimization=1 -- 每个表仅需执行一次该命令
ALTER TABLE t MODIFY BUCKET NUMBER 8
```
（可选）按需执行如下任一命令，执行重新分桶操作，将新的分桶定义应用于存量数据。重新分桶任务将异步运行。
- 指定某个分区
  将命令中的 “2025-04-14” 替换为您实际设置的分区键。
```
ALTER TABLE t RECLUSTER PARTITION '2025-04-14'  
```
- 指定所有分区
```
ALTER TABLE t RECLUSTER PARTITION WHERE 1=1  
```
- 指定条符合条件的分区
```
ALTER TABLE t RECLUSTER PARTITION WHERE ...  
```
您可通过以下命令查看任务状态。
```
SELECT * FROM system.mutations WHERE database='...' and table = '...'
```

场景 3：修改分桶键

注意事项

修改分桶键后，表中存量数据和新插入数据使用的分桶键不同，将导致引擎无法使用新的分桶键表达式执行优化查询操作，因此，不建议修改分桶键。但如果您的业务场景要求必须修改分桶键，建议您修改分桶键后执行步骤 2，触发存量数据的重新分桶。

操作步骤

修改分桶键。

ALTER TABLE t MODIFY CLUSTER BY EXPRESSION cityHash64V2(x - y) INTO 4 BUCKETS settings enable_legacy_cluster_by=1 [, force_modify_unique_table_cluster_by=1]

按需执行如下任一命令，执行重新分桶操作，将新的分桶键应用于存量数据。重新分桶任务将异步运行。
- 指定某个分区
  将命令中的 “2025-04-14” 替换为您实际设置的分区键。
```
ALTER TABLE t RECLUSTER PARTITION '2025-04-14'  
```
- 指定所有分区
```
ALTER TABLE t RECLUSTER PARTITION WHERE 1=1  
```
- 指定条符合条件的分区
```
ALTER TABLE t RECLUSTER PARTITION WHERE ...  
```
您可通过以下命令查看任务状态，确认重新分桶任务是否执行完成。
```
SELECT * FROM system.mutations WHERE database='...' and table = '...'
```

常见问题

执行重新分桶操作后内存使用或 OOM 突发，该怎么处理？

减少表中 max_addition_mutation_task_num 的数值。

重新分桶操作导致有核心转储（core dump），该怎么处理？

在表的定义中设置 max_addition_mutation_task_num=0。

ByteHouse云数仓版

操作步骤 #

注意事项 #

操作步骤 #

注意事项 #

操作步骤 #

执行重新分桶操作后内存使用或 OOM 突发，该怎么处理？ #

重新分桶操作导致有核心转储（core dump），该怎么处理？ #

操作步骤

注意事项

操作步骤

注意事项

操作步骤

执行重新分桶操作后内存使用或 OOM 突发，该怎么处理？

重新分桶操作导致有核心转储（core dump），该怎么处理？