ALTER TABLE DISTRIBUTION

説明

このステートメントは、パーティション化されたテーブルのデフォルト分散バケット設定を変更するために使用されます。この操作は同期的であり、コマンドの戻りは実行の完了を示します。

このステートメントは新しく作成されるパーティションのデフォルトバケット数のみを変更します。既存のパーティションは元のバケット数を変更されずに保持します。

grammar:

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との相互作用

AUTO PARTITIONを使用するテーブルでは、ALTER TABLE MODIFY DISTRIBUTION実行後にデータ挿入によって自動的に作成される新しいパーティションは、新しいバケット設定を使用します。変更前にすでに自動作成されていたパーティションは変更されません。

例えば、AUTO PARTITIONテーブルが元々BUCKETS 5を使用しており、それをBUCKETS 8に変更した場合、その後の新しいautoパーティションの作成をトリガーするINSERTは、そのパーティションに8個のバケットを割り当てます。さらにBUCKETS AUTOに変更した場合、新しく自動作成されるパーティションのバケット数はシステムによって自動的に決定されます。

Dynamic Partitionとの相互作用

Dynamic Partitionを使用するテーブルでは、ALTER TABLE MODIFY DISTRIBUTION実行後にdynamic partitionスケジューラーによって自動的に作成される新しいパーティションは、新しいバケット設定を使用します。既存のdynamic partitionは変更されません。

Dynamic Partitionテーブルはdynamic_partition.bucketsプロパティもサポートしていることに注意してください。両方が設定されている場合、動的に作成されるパーティションではdynamic_partition.bucketsプロパティが優先されます。dynamic partitionでテーブルレベルのデフォルトバケット数（MODIFY DISTRIBUTIONで設定）を使用するには、dynamic_partition.bucketsが明示的に設定されていないことを確認するか、ALTER TABLE ... SET ("dynamic_partition.buckets" = "...")を使用して適切に更新してください。

例

1. HASH分散のRANGEパーティションテーブルのデフォルトバケット数を元の値から10に変更する

ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1) BUCKETS 10;

この後、新しく追加されるパーティションは全て10個のバケットを使用します：

ALTER TABLE example_db.my_table ADD PARTITION p3 VALUES LESS THAN ('30');
-- p3 will have 10 buckets; existing partitions remain unchanged

2. 固定バケット数からAUTOに切り替える

ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1) BUCKETS AUTO;

この後、新しく作成されたパーティションのバケット数は、システムによって自動的に決定されます。

3. AUTOから固定バケット数に戻す

ALTER TABLE example_db.my_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1) BUCKETS 3;

4. LIST パーティション化されたテーブルのデフォルトバケット数を変更する

ALTER TABLE example_db.my_list_table MODIFY DISTRIBUTION DISTRIBUTED BY HASH(k1) BUCKETS 8;

5. RANDOM分散を持つテーブルのデフォルトバケット数を変更する

ALTER TABLE example_db.my_random_table MODIFY DISTRIBUTION DISTRIBUTED BY RANDOM BUCKETS 12;

6. RANDOM分散テーブルをAUTOバケットに切り替える

ALTER TABLE example_db.my_random_table MODIFY DISTRIBUTION DISTRIBUTED BY RANDOM BUCKETS AUTO;

7. AUTO PARTITION テーブル (RANGE) のデフォルトバケット数を変更する

-- 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. AUTO PARTITIONテーブル（LIST）のデフォルトバケット数を変更する

-- 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. AUTO PARTITION テーブルを AUTO buckets から固定に切り替え、また元に戻す

-- 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. 複数の連続的な変更

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. エラーケース

Colocate テーブルはサポートされていません：

-- 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;

パーティション化されていないテーブルはサポートされていません：

-- 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;

distribution typeを変更できません:

-- 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;

分散列を変更できません：

-- 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;

キーワード

ALTER, TABLE, DISTRIBUTION, MODIFY DISTRIBUTION, BUCKETS, ALTER TABLE