This is an automated email from the ASF dual-hosted git repository.
dataroaring pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new e7cba94ca51 [docs] Add ALTER TABLE DISTRIBUTION documentation for
modifying default bucket configuration (#3358)
e7cba94ca51 is described below
commit e7cba94ca51b9f856dfd1ae7aea6364ba9beace4
Author: zclllyybb <[email protected]>
AuthorDate: Wed Feb 11 01:50:44 2026 +0800
[docs] Add ALTER TABLE DISTRIBUTION documentation for modifying default
bucket configuration (#3358)
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../table/ALTER-TABLE-DISTRIBUTION.md | 173 +++++++++++++++++++++
.../table-and-view/table/ALTER-TABLE-PROPERTY.md | 2 +-
.../table/ALTER-TABLE-DISTRIBUTION.md | 173 +++++++++++++++++++++
.../table-and-view/table/ALTER-TABLE-PROPERTY.md | 2 +-
.../table/ALTER-TABLE-DISTRIBUTION.md | 173 +++++++++++++++++++++
.../table-and-view/table/ALTER-TABLE-PROPERTY.md | 2 +-
sidebars.ts | 1 +
.../table/ALTER-TABLE-DISTRIBUTION.md | 173 +++++++++++++++++++++
.../table-and-view/table/ALTER-TABLE-PROPERTY.md | 2 +-
versioned_sidebars/version-4.x-sidebars.json | 1 +
10 files changed, 698 insertions(+), 4 deletions(-)
diff --git
a/docs/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
b/docs/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
new file mode 100644
index 00000000000..a35def989d5
--- /dev/null
+++
b/docs/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
@@ -0,0 +1,173 @@
+---
+{
+ "title": "ALTER TABLE DISTRIBUTION",
+ "language": "en",
+ "description": "This statement is used to modify the default distribution
bucket configuration of a partitioned table."
+}
+---
+
+## Description
+
+This statement is used to modify the default distribution bucket configuration
of a partitioned table. This operation is synchronous, and the return of the
command indicates the completion of the execution.
+
+This statement only changes the default bucket count for **newly created
partitions**. Existing partitions retain their original bucket count unchanged.
+
+grammar:
+
+```sql
+ALTER TABLE [database.]table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(column1[,
column2, ...]) BUCKETS { num | AUTO };
+ALTER TABLE [database.]table MODIFY DISTRIBUTION DISTRIBUTED BY RANDOM BUCKETS
{ num | AUTO };
+```
+
+Note:
+
+- `num`: A positive integer specifying a fixed number of buckets for new
partitions.
+- `AUTO`: Let the system automatically determine the number of buckets for new
partitions based on data volume and cluster configuration.
+- The distribution type (HASH or RANDOM) and distribution columns must remain
the same as the original table definition. Only the bucket count can be changed.
+- This statement only applies to **partitioned tables** (RANGE or LIST
partitioned). Unpartitioned tables are not supported.
+- This statement is not supported on **Colocate** tables.
+- You can switch freely between a fixed bucket count and `AUTO`, and perform
multiple modifications in sequence.
+
+### Interaction with AUTO PARTITION
+
+For tables using [AUTO
PARTITION](../../../../table-design/data-partitioning/auto-partitioning), new
partitions that are automatically created by data insertion after executing
`ALTER TABLE MODIFY DISTRIBUTION` will use the new bucket configuration.
Partitions that were already auto-created before the modification remain
unchanged.
+
+For example, if an AUTO PARTITION table originally uses `BUCKETS 5` and you
modify it to `BUCKETS 8`, any subsequent INSERT that triggers the creation of a
new auto partition will assign 8 buckets to that partition. If you further
modify it to `BUCKETS AUTO`, newly auto-created partitions will have their
bucket count determined automatically by the system.
+
+### Interaction with Dynamic Partition
+
+For tables using [Dynamic
Partition](../../../../table-design/data-partitioning/dynamic-partitioning),
new partitions that are automatically created by the dynamic partition
scheduler after executing `ALTER TABLE MODIFY DISTRIBUTION` will use the new
bucket configuration. Existing dynamic partitions remain unchanged.
+
+Note that Dynamic Partition tables also support the
`dynamic_partition.buckets` property. If both are configured, the
`dynamic_partition.buckets` property takes precedence for dynamically created
partitions. To use the table-level default bucket count (set by `MODIFY
DISTRIBUTION`) for dynamic partitions, ensure that `dynamic_partition.buckets`
is not explicitly set, or update it accordingly via `ALTER TABLE ... SET
("dynamic_partition.buckets" = "...")`.
+
+## Example
+
+1. Modify the default bucket count of a RANGE partitioned table with HASH
distribution from the original value to 10
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 10;
+```
+
+After this, any newly added partition will use 10 buckets:
+
+```sql
+ALTER TABLE example_db.my_table ADD PARTITION p3 VALUES LESS THAN ('30');
+-- p3 will have 10 buckets; existing partitions remain unchanged
+```
+
+2. Switch from a fixed bucket count to AUTO
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS AUTO;
+```
+
+After this, newly created partitions will have their bucket count
automatically determined by the system.
+
+3. Switch from AUTO back to a fixed bucket count
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 3;
+```
+
+4. Modify the default bucket count of a LIST partitioned table
+
+```sql
+ALTER TABLE example_db.my_list_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 8;
+```
+
+5. Modify the default bucket count of a table with RANDOM distribution
+
+```sql
+ALTER TABLE example_db.my_random_table MODIFY DISTRIBUTION DISTRIBUTED BY
RANDOM BUCKETS 12;
+```
+
+6. Switch a RANDOM distribution table to AUTO buckets
+
+```sql
+ALTER TABLE example_db.my_random_table MODIFY DISTRIBUTION DISTRIBUTED BY
RANDOM BUCKETS AUTO;
+```
+
+7. Modify the default bucket count of an AUTO PARTITION table (RANGE)
+
+```sql
+-- Original table uses AUTO PARTITION BY RANGE with BUCKETS 5
+ALTER TABLE example_db.my_auto_range_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 8;
+
+-- New auto-created partitions from subsequent INSERT will use 8 buckets
+INSERT INTO example_db.my_auto_range_table VALUES ('2024-01-03', 3);
+```
+
+8. Modify the default bucket count of an AUTO PARTITION table (LIST)
+
+```sql
+-- Original table uses AUTO PARTITION BY LIST with BUCKETS 4
+ALTER TABLE example_db.my_auto_list_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 7;
+
+-- New auto-created partitions from subsequent INSERT will use 7 buckets
+INSERT INTO example_db.my_auto_list_table VALUES ('ccc', 3);
+```
+
+9. Switch an AUTO PARTITION table from AUTO buckets to fixed, and back
+
+```sql
+-- Table originally created with BUCKETS AUTO
+ALTER TABLE example_db.my_auto_auto_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 5;
+-- New partitions will use 5 buckets
+
+ALTER TABLE example_db.my_auto_auto_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS AUTO;
+-- New partitions will return to system-determined bucket count
+```
+
+10. Multiple sequential modifications
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 4;
+ALTER TABLE example_db.my_table ADD PARTITION p2 VALUES LESS THAN ('20');
+-- p2 has 4 buckets
+
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS AUTO;
+ALTER TABLE example_db.my_table ADD PARTITION p3 VALUES LESS THAN ('30');
+-- p3 has system-determined bucket count
+
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 6;
+ALTER TABLE example_db.my_table ADD PARTITION p4 VALUES LESS THAN ('40');
+-- p4 has 6 buckets
+```
+
+11. Error cases
+
+Colocate tables are not supported:
+
+```sql
+-- This will fail with: "Cannot change default bucket number of colocate table"
+ALTER TABLE example_db.my_colocate_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 10;
+```
+
+Unpartitioned tables are not supported:
+
+```sql
+-- This will fail with: "Only support change partitioned table's distribution"
+ALTER TABLE example_db.my_unpartitioned_table MODIFY DISTRIBUTION DISTRIBUTED
BY HASH(k1) BUCKETS 10;
+```
+
+Cannot change the distribution type:
+
+```sql
+-- Original table uses HASH distribution; changing to RANDOM will fail
+-- Error: "Cannot change distribution type"
+ALTER TABLE example_db.my_hash_table MODIFY DISTRIBUTION DISTRIBUTED BY RANDOM
BUCKETS 10;
+```
+
+Cannot change the distribution columns:
+
+```sql
+-- Original table uses HASH(k1); changing to HASH(k2) will fail
+-- Error: "Cannot assign hash distribution with different distribution cols"
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k2)
BUCKETS 10;
+```
+
+## Keywords
+
+```text
+ALTER, TABLE, DISTRIBUTION, MODIFY DISTRIBUTION, BUCKETS, ALTER TABLE
+```
diff --git
a/docs/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
b/docs/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
index 50bb48b7b11..201b9f160b7 100644
---
a/docs/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
+++
b/docs/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
@@ -119,7 +119,7 @@ ALTER TABLE example_db.my_table MODIFY DISTRIBUTION
DISTRIBUTED BY HASH(k1) BUCK
Note:
-- Only support non colocate table with RANGE partition and HASH distribution
+- Only support partitioned non-Colocate tables. See [ALTER TABLE
DISTRIBUTION](./ALTER-TABLE-DISTRIBUTION) for more details.
9. Modify table comments
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
new file mode 100644
index 00000000000..d3f0feaf3dc
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
@@ -0,0 +1,173 @@
+---
+{
+ "title": "ALTER TABLE DISTRIBUTION",
+ "language": "zh-CN",
+ "description": "该语句用于修改分区表的默认分桶配置。"
+}
+---
+
+## 描述
+
+该语句用于修改分区表的默认分桶配置。这个操作是同步的，命令返回表示执行完毕。
+
+该语句仅修改**新创建分区**的默认分桶数。已有分区的分桶数保持不变。
+
+语法：
+
+```sql
+ALTER TABLE [database.]table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(column1[,
column2, ...]) BUCKETS { num | AUTO };
+ALTER TABLE [database.]table MODIFY DISTRIBUTION DISTRIBUTED BY RANDOM BUCKETS
{ num | AUTO };
+```
+
+说明：
+
+- `num`：正整数，指定新分区使用的固定分桶数。
+- `AUTO`：由系统根据数据量和集群配置自动决定新分区的分桶数。
+- 分桶方式（HASH 或 RANDOM）和分桶列必须与建表时保持一致，仅能修改分桶数。
+- 该语句仅适用于**分区表**（RANGE 分区或 LIST 分区）。不支持非分区表。
+- 不支持 **Colocate** 表。
+- 可以在固定分桶数和 `AUTO` 之间自由切换，并支持多次连续修改。
+
+### 与自动分区（AUTO PARTITION）的联用
+
+对于使用[自动分区](../../../../table-design/data-partitioning/auto-partitioning)的表，在执行
`ALTER TABLE MODIFY DISTRIBUTION` 之后，由数据导入自动创建的新分区将使用新的分桶配置。修改之前已经自动创建的分区保持不变。
+
+例如，某自动分区表原先使用 `BUCKETS 5`，修改为 `BUCKETS 8` 后，后续 INSERT 触发自动创建的新分区将使用 8
个分桶。若进一步修改为 `BUCKETS AUTO`，则新自动创建的分区将由系统自动决定分桶数。
+
+### 与动态分区（Dynamic Partition）的联用
+
+对于使用[动态分区](../../../../table-design/data-partitioning/dynamic-partitioning)的表，在执行
`ALTER TABLE MODIFY DISTRIBUTION` 之后，由动态分区调度器自动创建的新分区将使用新的分桶配置。已有的动态分区保持不变。
+
+注意，动态分区表还支持 `dynamic_partition.buckets` 属性。如果两者同时设置，动态创建的分区将优先使用
`dynamic_partition.buckets` 属性指定的分桶数。若希望动态分区使用表级别的默认分桶数（即通过 `MODIFY
DISTRIBUTION` 设置的值），请确保未显式设置 `dynamic_partition.buckets`，或通过 `ALTER TABLE ...
SET ("dynamic_partition.buckets" = "...")` 同步更新。
+
+## 示例
+
+1. 将 RANGE 分区、HASH 分桶表的默认分桶数修改为 10
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 10;
+```
+
+之后新增的分区将使用 10 个分桶：
+
+```sql
+ALTER TABLE example_db.my_table ADD PARTITION p3 VALUES LESS THAN ('30');
+-- p3 将使用 10 个分桶；已有分区不受影响
+```
+
+2. 从固定分桶数切换为 AUTO
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS AUTO;
+```
+
+之后新建的分区将由系统自动决定分桶数。
+
+3. 从 AUTO 切换回固定分桶数
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 3;
+```
+
+4. 修改 LIST 分区表的默认分桶数
+
+```sql
+ALTER TABLE example_db.my_list_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 8;
+```
+
+5. 修改 RANDOM 分桶表的默认分桶数
+
+```sql
+ALTER TABLE example_db.my_random_table MODIFY DISTRIBUTION DISTRIBUTED BY
RANDOM BUCKETS 12;
+```
+
+6. 将 RANDOM 分桶表切换为 AUTO
+
+```sql
+ALTER TABLE example_db.my_random_table MODIFY DISTRIBUTION DISTRIBUTED BY
RANDOM BUCKETS AUTO;
+```
+
+7. 修改自动分区表（RANGE）的默认分桶数
+
+```sql
+-- 原表使用 AUTO PARTITION BY RANGE，分桶数为 5
+ALTER TABLE example_db.my_auto_range_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 8;
+
+-- 后续 INSERT 触发自动创建的新分区将使用 8 个分桶
+INSERT INTO example_db.my_auto_range_table VALUES ('2024-01-03', 3);
+```
+
+8. 修改自动分区表（LIST）的默认分桶数
+
+```sql
+-- 原表使用 AUTO PARTITION BY LIST，分桶数为 4
+ALTER TABLE example_db.my_auto_list_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 7;
+
+-- 后续 INSERT 触发自动创建的新分区将使用 7 个分桶
+INSERT INTO example_db.my_auto_list_table VALUES ('ccc', 3);
+```
+
+9. 将自动分区表从 AUTO 分桶切换为固定分桶，再切换回 AUTO
+
+```sql
+-- 原表建表时使用 BUCKETS AUTO
+ALTER TABLE example_db.my_auto_auto_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 5;
+-- 新分区将使用 5 个分桶
+
+ALTER TABLE example_db.my_auto_auto_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS AUTO;
+-- 新分区将恢复为系统自动决定分桶数
+```
+
+10. 多次连续修改
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 4;
+ALTER TABLE example_db.my_table ADD PARTITION p2 VALUES LESS THAN ('20');
+-- p2 使用 4 个分桶
+
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS AUTO;
+ALTER TABLE example_db.my_table ADD PARTITION p3 VALUES LESS THAN ('30');
+-- p3 使用系统自动决定的分桶数
+
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 6;
+ALTER TABLE example_db.my_table ADD PARTITION p4 VALUES LESS THAN ('40');
+-- p4 使用 6 个分桶
+```
+
+11. 错误示例
+
+不支持 Colocate 表：
+
+```sql
+-- 将会失败，错误信息："Cannot change default bucket number of colocate table"
+ALTER TABLE example_db.my_colocate_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 10;
+```
+
+不支持非分区表：
+
+```sql
+-- 将会失败，错误信息："Only support change partitioned table's distribution"
+ALTER TABLE example_db.my_unpartitioned_table MODIFY DISTRIBUTION DISTRIBUTED
BY HASH(k1) BUCKETS 10;
+```
+
+不能更改分桶方式：
+
+```sql
+-- 原表使用 HASH 分桶，改为 RANDOM 将会失败
+-- 错误信息："Cannot change distribution type"
+ALTER TABLE example_db.my_hash_table MODIFY DISTRIBUTION DISTRIBUTED BY RANDOM
BUCKETS 10;
+```
+
+不能更改分桶列：
+
+```sql
+-- 原表使用 HASH(k1)，改为 HASH(k2) 将会失败
+-- 错误信息："Cannot assign hash distribution with different distribution cols"
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k2)
BUCKETS 10;
+```
+
+## 关键词
+
+```text
+ALTER, TABLE, DISTRIBUTION, MODIFY DISTRIBUTION, BUCKETS, ALTER TABLE
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
index 2e9abf966ca..8b7a1787f44 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
@@ -113,7 +113,7 @@ ALTER TABLE example_db.my_table MODIFY DISTRIBUTION
DISTRIBUTED BY HASH(k1) BUCK
注意：
-- 只能用在分区类型为 RANGE，采用哈希分桶的非 colocate 表
+- 仅支持分区表且非 Colocate 表。详见 [ALTER TABLE
DISTRIBUTION](./ALTER-TABLE-DISTRIBUTION)。
9. 修改表注释
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
new file mode 100644
index 00000000000..d3f0feaf3dc
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
@@ -0,0 +1,173 @@
+---
+{
+ "title": "ALTER TABLE DISTRIBUTION",
+ "language": "zh-CN",
+ "description": "该语句用于修改分区表的默认分桶配置。"
+}
+---
+
+## 描述
+
+该语句用于修改分区表的默认分桶配置。这个操作是同步的，命令返回表示执行完毕。
+
+该语句仅修改**新创建分区**的默认分桶数。已有分区的分桶数保持不变。
+
+语法：
+
+```sql
+ALTER TABLE [database.]table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(column1[,
column2, ...]) BUCKETS { num | AUTO };
+ALTER TABLE [database.]table MODIFY DISTRIBUTION DISTRIBUTED BY RANDOM BUCKETS
{ num | AUTO };
+```
+
+说明：
+
+- `num`：正整数，指定新分区使用的固定分桶数。
+- `AUTO`：由系统根据数据量和集群配置自动决定新分区的分桶数。
+- 分桶方式（HASH 或 RANDOM）和分桶列必须与建表时保持一致，仅能修改分桶数。
+- 该语句仅适用于**分区表**（RANGE 分区或 LIST 分区）。不支持非分区表。
+- 不支持 **Colocate** 表。
+- 可以在固定分桶数和 `AUTO` 之间自由切换，并支持多次连续修改。
+
+### 与自动分区（AUTO PARTITION）的联用
+
+对于使用[自动分区](../../../../table-design/data-partitioning/auto-partitioning)的表，在执行
`ALTER TABLE MODIFY DISTRIBUTION` 之后，由数据导入自动创建的新分区将使用新的分桶配置。修改之前已经自动创建的分区保持不变。
+
+例如，某自动分区表原先使用 `BUCKETS 5`，修改为 `BUCKETS 8` 后，后续 INSERT 触发自动创建的新分区将使用 8
个分桶。若进一步修改为 `BUCKETS AUTO`，则新自动创建的分区将由系统自动决定分桶数。
+
+### 与动态分区（Dynamic Partition）的联用
+
+对于使用[动态分区](../../../../table-design/data-partitioning/dynamic-partitioning)的表，在执行
`ALTER TABLE MODIFY DISTRIBUTION` 之后，由动态分区调度器自动创建的新分区将使用新的分桶配置。已有的动态分区保持不变。
+
+注意，动态分区表还支持 `dynamic_partition.buckets` 属性。如果两者同时设置，动态创建的分区将优先使用
`dynamic_partition.buckets` 属性指定的分桶数。若希望动态分区使用表级别的默认分桶数（即通过 `MODIFY
DISTRIBUTION` 设置的值），请确保未显式设置 `dynamic_partition.buckets`，或通过 `ALTER TABLE ...
SET ("dynamic_partition.buckets" = "...")` 同步更新。
+
+## 示例
+
+1. 将 RANGE 分区、HASH 分桶表的默认分桶数修改为 10
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 10;
+```
+
+之后新增的分区将使用 10 个分桶：
+
+```sql
+ALTER TABLE example_db.my_table ADD PARTITION p3 VALUES LESS THAN ('30');
+-- p3 将使用 10 个分桶；已有分区不受影响
+```
+
+2. 从固定分桶数切换为 AUTO
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS AUTO;
+```
+
+之后新建的分区将由系统自动决定分桶数。
+
+3. 从 AUTO 切换回固定分桶数
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 3;
+```
+
+4. 修改 LIST 分区表的默认分桶数
+
+```sql
+ALTER TABLE example_db.my_list_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 8;
+```
+
+5. 修改 RANDOM 分桶表的默认分桶数
+
+```sql
+ALTER TABLE example_db.my_random_table MODIFY DISTRIBUTION DISTRIBUTED BY
RANDOM BUCKETS 12;
+```
+
+6. 将 RANDOM 分桶表切换为 AUTO
+
+```sql
+ALTER TABLE example_db.my_random_table MODIFY DISTRIBUTION DISTRIBUTED BY
RANDOM BUCKETS AUTO;
+```
+
+7. 修改自动分区表（RANGE）的默认分桶数
+
+```sql
+-- 原表使用 AUTO PARTITION BY RANGE，分桶数为 5
+ALTER TABLE example_db.my_auto_range_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 8;
+
+-- 后续 INSERT 触发自动创建的新分区将使用 8 个分桶
+INSERT INTO example_db.my_auto_range_table VALUES ('2024-01-03', 3);
+```
+
+8. 修改自动分区表（LIST）的默认分桶数
+
+```sql
+-- 原表使用 AUTO PARTITION BY LIST，分桶数为 4
+ALTER TABLE example_db.my_auto_list_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 7;
+
+-- 后续 INSERT 触发自动创建的新分区将使用 7 个分桶
+INSERT INTO example_db.my_auto_list_table VALUES ('ccc', 3);
+```
+
+9. 将自动分区表从 AUTO 分桶切换为固定分桶，再切换回 AUTO
+
+```sql
+-- 原表建表时使用 BUCKETS AUTO
+ALTER TABLE example_db.my_auto_auto_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 5;
+-- 新分区将使用 5 个分桶
+
+ALTER TABLE example_db.my_auto_auto_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS AUTO;
+-- 新分区将恢复为系统自动决定分桶数
+```
+
+10. 多次连续修改
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 4;
+ALTER TABLE example_db.my_table ADD PARTITION p2 VALUES LESS THAN ('20');
+-- p2 使用 4 个分桶
+
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS AUTO;
+ALTER TABLE example_db.my_table ADD PARTITION p3 VALUES LESS THAN ('30');
+-- p3 使用系统自动决定的分桶数
+
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 6;
+ALTER TABLE example_db.my_table ADD PARTITION p4 VALUES LESS THAN ('40');
+-- p4 使用 6 个分桶
+```
+
+11. 错误示例
+
+不支持 Colocate 表：
+
+```sql
+-- 将会失败，错误信息："Cannot change default bucket number of colocate table"
+ALTER TABLE example_db.my_colocate_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 10;
+```
+
+不支持非分区表：
+
+```sql
+-- 将会失败，错误信息："Only support change partitioned table's distribution"
+ALTER TABLE example_db.my_unpartitioned_table MODIFY DISTRIBUTION DISTRIBUTED
BY HASH(k1) BUCKETS 10;
+```
+
+不能更改分桶方式：
+
+```sql
+-- 原表使用 HASH 分桶，改为 RANDOM 将会失败
+-- 错误信息："Cannot change distribution type"
+ALTER TABLE example_db.my_hash_table MODIFY DISTRIBUTION DISTRIBUTED BY RANDOM
BUCKETS 10;
+```
+
+不能更改分桶列：
+
+```sql
+-- 原表使用 HASH(k1)，改为 HASH(k2) 将会失败
+-- 错误信息："Cannot assign hash distribution with different distribution cols"
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k2)
BUCKETS 10;
+```
+
+## 关键词
+
+```text
+ALTER, TABLE, DISTRIBUTION, MODIFY DISTRIBUTION, BUCKETS, ALTER TABLE
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
index 2e9abf966ca..8b7a1787f44 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
@@ -113,7 +113,7 @@ ALTER TABLE example_db.my_table MODIFY DISTRIBUTION
DISTRIBUTED BY HASH(k1) BUCK
注意：
-- 只能用在分区类型为 RANGE，采用哈希分桶的非 colocate 表
+- 仅支持分区表且非 Colocate 表。详见 [ALTER TABLE
DISTRIBUTION](./ALTER-TABLE-DISTRIBUTION)。
9. 修改表注释
diff --git a/sidebars.ts b/sidebars.ts
index 0007f8403b4..0ee999eca50 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -2260,6 +2260,7 @@ const sidebars: SidebarsConfig = {
'sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-REPLACE',
'sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY',
'sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-COMMENT',
+
'sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION',
'sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-ADD-GENERATED-COLUMN',
'sql-manual/sql-statements/table-and-view/table/CANCEL-ALTER-TABLE',
'sql-manual/sql-statements/table-and-view/table/SHOW-ALTER-TABLE',
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
b/versioned_docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
new file mode 100644
index 00000000000..a35def989d5
--- /dev/null
+++
b/versioned_docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION.md
@@ -0,0 +1,173 @@
+---
+{
+ "title": "ALTER TABLE DISTRIBUTION",
+ "language": "en",
+ "description": "This statement is used to modify the default distribution
bucket configuration of a partitioned table."
+}
+---
+
+## Description
+
+This statement is used to modify the default distribution bucket configuration
of a partitioned table. This operation is synchronous, and the return of the
command indicates the completion of the execution.
+
+This statement only changes the default bucket count for **newly created
partitions**. Existing partitions retain their original bucket count unchanged.
+
+grammar:
+
+```sql
+ALTER TABLE [database.]table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(column1[,
column2, ...]) BUCKETS { num | AUTO };
+ALTER TABLE [database.]table MODIFY DISTRIBUTION DISTRIBUTED BY RANDOM BUCKETS
{ num | AUTO };
+```
+
+Note:
+
+- `num`: A positive integer specifying a fixed number of buckets for new
partitions.
+- `AUTO`: Let the system automatically determine the number of buckets for new
partitions based on data volume and cluster configuration.
+- The distribution type (HASH or RANDOM) and distribution columns must remain
the same as the original table definition. Only the bucket count can be changed.
+- This statement only applies to **partitioned tables** (RANGE or LIST
partitioned). Unpartitioned tables are not supported.
+- This statement is not supported on **Colocate** tables.
+- You can switch freely between a fixed bucket count and `AUTO`, and perform
multiple modifications in sequence.
+
+### Interaction with AUTO PARTITION
+
+For tables using [AUTO
PARTITION](../../../../table-design/data-partitioning/auto-partitioning), new
partitions that are automatically created by data insertion after executing
`ALTER TABLE MODIFY DISTRIBUTION` will use the new bucket configuration.
Partitions that were already auto-created before the modification remain
unchanged.
+
+For example, if an AUTO PARTITION table originally uses `BUCKETS 5` and you
modify it to `BUCKETS 8`, any subsequent INSERT that triggers the creation of a
new auto partition will assign 8 buckets to that partition. If you further
modify it to `BUCKETS AUTO`, newly auto-created partitions will have their
bucket count determined automatically by the system.
+
+### Interaction with Dynamic Partition
+
+For tables using [Dynamic
Partition](../../../../table-design/data-partitioning/dynamic-partitioning),
new partitions that are automatically created by the dynamic partition
scheduler after executing `ALTER TABLE MODIFY DISTRIBUTION` will use the new
bucket configuration. Existing dynamic partitions remain unchanged.
+
+Note that Dynamic Partition tables also support the
`dynamic_partition.buckets` property. If both are configured, the
`dynamic_partition.buckets` property takes precedence for dynamically created
partitions. To use the table-level default bucket count (set by `MODIFY
DISTRIBUTION`) for dynamic partitions, ensure that `dynamic_partition.buckets`
is not explicitly set, or update it accordingly via `ALTER TABLE ... SET
("dynamic_partition.buckets" = "...")`.
+
+## Example
+
+1. Modify the default bucket count of a RANGE partitioned table with HASH
distribution from the original value to 10
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 10;
+```
+
+After this, any newly added partition will use 10 buckets:
+
+```sql
+ALTER TABLE example_db.my_table ADD PARTITION p3 VALUES LESS THAN ('30');
+-- p3 will have 10 buckets; existing partitions remain unchanged
+```
+
+2. Switch from a fixed bucket count to AUTO
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS AUTO;
+```
+
+After this, newly created partitions will have their bucket count
automatically determined by the system.
+
+3. Switch from AUTO back to a fixed bucket count
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 3;
+```
+
+4. Modify the default bucket count of a LIST partitioned table
+
+```sql
+ALTER TABLE example_db.my_list_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 8;
+```
+
+5. Modify the default bucket count of a table with RANDOM distribution
+
+```sql
+ALTER TABLE example_db.my_random_table MODIFY DISTRIBUTION DISTRIBUTED BY
RANDOM BUCKETS 12;
+```
+
+6. Switch a RANDOM distribution table to AUTO buckets
+
+```sql
+ALTER TABLE example_db.my_random_table MODIFY DISTRIBUTION DISTRIBUTED BY
RANDOM BUCKETS AUTO;
+```
+
+7. Modify the default bucket count of an AUTO PARTITION table (RANGE)
+
+```sql
+-- Original table uses AUTO PARTITION BY RANGE with BUCKETS 5
+ALTER TABLE example_db.my_auto_range_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 8;
+
+-- New auto-created partitions from subsequent INSERT will use 8 buckets
+INSERT INTO example_db.my_auto_range_table VALUES ('2024-01-03', 3);
+```
+
+8. Modify the default bucket count of an AUTO PARTITION table (LIST)
+
+```sql
+-- Original table uses AUTO PARTITION BY LIST with BUCKETS 4
+ALTER TABLE example_db.my_auto_list_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 7;
+
+-- New auto-created partitions from subsequent INSERT will use 7 buckets
+INSERT INTO example_db.my_auto_list_table VALUES ('ccc', 3);
+```
+
+9. Switch an AUTO PARTITION table from AUTO buckets to fixed, and back
+
+```sql
+-- Table originally created with BUCKETS AUTO
+ALTER TABLE example_db.my_auto_auto_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 5;
+-- New partitions will use 5 buckets
+
+ALTER TABLE example_db.my_auto_auto_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS AUTO;
+-- New partitions will return to system-determined bucket count
+```
+
+10. Multiple sequential modifications
+
+```sql
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 4;
+ALTER TABLE example_db.my_table ADD PARTITION p2 VALUES LESS THAN ('20');
+-- p2 has 4 buckets
+
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS AUTO;
+ALTER TABLE example_db.my_table ADD PARTITION p3 VALUES LESS THAN ('30');
+-- p3 has system-determined bucket count
+
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1)
BUCKETS 6;
+ALTER TABLE example_db.my_table ADD PARTITION p4 VALUES LESS THAN ('40');
+-- p4 has 6 buckets
+```
+
+11. Error cases
+
+Colocate tables are not supported:
+
+```sql
+-- This will fail with: "Cannot change default bucket number of colocate table"
+ALTER TABLE example_db.my_colocate_table MODIFY DISTRIBUTION DISTRIBUTED BY
HASH(k1) BUCKETS 10;
+```
+
+Unpartitioned tables are not supported:
+
+```sql
+-- This will fail with: "Only support change partitioned table's distribution"
+ALTER TABLE example_db.my_unpartitioned_table MODIFY DISTRIBUTION DISTRIBUTED
BY HASH(k1) BUCKETS 10;
+```
+
+Cannot change the distribution type:
+
+```sql
+-- Original table uses HASH distribution; changing to RANDOM will fail
+-- Error: "Cannot change distribution type"
+ALTER TABLE example_db.my_hash_table MODIFY DISTRIBUTION DISTRIBUTED BY RANDOM
BUCKETS 10;
+```
+
+Cannot change the distribution columns:
+
+```sql
+-- Original table uses HASH(k1); changing to HASH(k2) will fail
+-- Error: "Cannot assign hash distribution with different distribution cols"
+ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k2)
BUCKETS 10;
+```
+
+## Keywords
+
+```text
+ALTER, TABLE, DISTRIBUTION, MODIFY DISTRIBUTION, BUCKETS, ALTER TABLE
+```
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
b/versioned_docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
index 50bb48b7b11..201b9f160b7 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY.md
@@ -119,7 +119,7 @@ ALTER TABLE example_db.my_table MODIFY DISTRIBUTION
DISTRIBUTED BY HASH(k1) BUCK
Note:
-- Only support non colocate table with RANGE partition and HASH distribution
+- Only support partitioned non-Colocate tables. See [ALTER TABLE
DISTRIBUTION](./ALTER-TABLE-DISTRIBUTION) for more details.
9. Modify table comments
diff --git a/versioned_sidebars/version-4.x-sidebars.json
b/versioned_sidebars/version-4.x-sidebars.json
index eca94a53522..a6c6313cf71 100644
--- a/versioned_sidebars/version-4.x-sidebars.json
+++ b/versioned_sidebars/version-4.x-sidebars.json
@@ -2262,6 +2262,7 @@
"sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-REPLACE",
"sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-PROPERTY",
"sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-COMMENT",
+
"sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-DISTRIBUTION",
"sql-manual/sql-statements/table-and-view/table/ALTER-TABLE-ADD-GENERATED-COLUMN",
"sql-manual/sql-statements/table-and-view/table/CANCEL-ALTER-TABLE",
"sql-manual/sql-statements/table-and-view/table/SHOW-ALTER-TABLE",
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
