ALTER TABLE
Description
Modifies an existing table, including:
- Rename table, partition, index, or column
- Modify table comment
- Modify partitions (add/delete partitions and modify partition attributes)
- Modify the bucketing method and number of buckets
- Modify columns (add/delete columns and change the order of columns)
- Create/delete rollup index
- Modify bitmap index
- Modify table properties
- Atomic swap
- Manual data version compaction
This operation requires the ALTER privilege on the destination table.
Syntax
ALTER TABLE [<db_name>.]<tbl_name>
alter_clause1[, alter_clause2, ...]
alter_clause
can held the following operations: rename, comment, partition, bucket, column, rollup index, bitmap index, table property, swap, and compaction.
- rename: renames a table, rollup index, partition, or column (supported from v3.3.2 onwards).
- comment: modifies the table comment (supported from v3.1 onwards).
- partition: modifies partition properties, drops a partition, or adds a partition.
- bucket: modifies the bucketing method and number of buckets.
- column: adds, drops, or reorders columns, or modifies column type.
- rollup index: creates or drops a rollup index.
- bitmap index: modifies index (only Bitmap index can be modified).
- swap: atomic exchange of two tables.
- compaction: performs manual compaction to merge versions of loaded data (supported from v3.1 onwards).
Limits and usage notes
- Operations on partition, column, and rollup index cannot be performed in one ALTER TABLE statement.
- Column comments cannot be modified.
- One table can have only one ongoing schema change operation at a time. You cannot run two schema change commands on a table at the same time.
- Operations on bucket, column and rollup index are asynchronous operations. A success message is return immediately after the task is submitted. You can run the SHOW ALTER TABLE command to check the progress, and run the CANCEL ALTER TABLE command to cancel the operation.
- Operations on rename, comment, partition, bitmap index and swap are synchronous operations, and a command return indicates that the execution is finished.
Rename
Rename supports modification of table name, rollup index, and partition name.
Rename a table
ALTER TABLE <tbl_name> RENAME <new_tbl_name>
Rename a rollup index
ALTER TABLE [<db_name>.]<tbl_name>
RENAME ROLLUP <old_rollup_name> <new_rollup_name>
Rename a partition
ALTER TABLE [<db_name>.]<tbl_name>
RENAME PARTITION <old_partition_name> <new_partition_name>
Rename a column
From v3.3.2 onwards, StarRocks supports renaming columns.
ALTER TABLE [<db_name>.]<tbl_name>
RENAME COLUMN <old_col_name> [ TO ] <new_col_name>
- After renaming a column from A to B, adding a new column named A is not supported.
- Materialized views built on a renamed column will not take effect. You must rebuild them upon the column with the new name.
Alter table comment (from v3.1)
Syntax:
ALTER TABLE [<db_name>.]<tbl_name> COMMENT = "<new table comment>";
Currently, column comments cannot be modified.
Modify partition
ADD PARTITION(S)
You can choose to add range partitions or list partitions.
Syntax:
-
Range partitions
ALTER TABLE
ADD { single_range_partition | multi_range_partitions } [distribution_desc] ["key"="value"];
single_range_partition ::=
PARTITION [IF NOT EXISTS] <partition_name> VALUES partition_key_desc
partition_key_desc ::=
{ LESS THAN { MAXVALUE | value_list }
| [ value_list , value_list ) } -- Note that [ represents a left-closed interval.
value_list ::=
( <value> [, ...] )
multi_range_partitions ::=
{ PARTITIONS START ("<start_date_value>") END ("<end_date_value>") EVERY ( INTERVAL <N> <time_unit> )
| PARTITIONS START ("<start_integer_value>") END ("<end_integer_value>") EVERY ( <granularity> ) } -- The partition column values still need to be enclosed in double quotes even if the partition column values specified by START and END are integers. However, the interval values in the EVERY clause do not need to be enclosed in double quotes. -
List partitions
ALTER TABLE
ADD PARTITION <partition_name> VALUES IN (value_list) [distribution_desc] ["key"="value"];
value_list ::=
value_item [, ...]
value_item ::=
{ <value> | ( <value> [, ...] ) }
Parameters:
-
Partition-related parameters:
- For range partitions, you can add a single range partition (
single_range_partition
) or multiple range partitions in batch (multi_range_partitions
). - For list partitions, you can only add a single list partition.
- For range partitions, you can add a single range partition (
-
distribution_desc
:You can set the number of buckets for the new partition separately, but you cannot set the bucketing method separately.
-
"key"="value"
:You can set properties for the new partition. For details, see CREATE TABLE.
Examples:
-
Range partitions
-
If the partition column is specified as
event_day
at table creation, for examplePARTITION BY RANGE(event_day)
, and a new partition needs to be added after table creation, you can execute:ALTER TABLE site_access ADD PARTITION p4 VALUES LESS THAN ("2020-04-30");
-
If the partition column is specified as
datekey
at table creation, for examplePARTITION BY RANGE (datekey)
, and multiple partitions need to be added in batch after table creation, you can execute:ALTER TABLE site_access
ADD PARTITIONS START ("2021-01-05") END ("2021-01-10") EVERY (INTERVAL 1 DAY);
-
-
List partitions
-
If a single partition column is specified at table creation, for example
PARTITION BY LIST (city)
, and a new partition needs to be added after table creation, you can execute:ALTER TABLE t_recharge_detail2
ADD PARTITION pCalifornia VALUES IN ("Los Angeles","San Francisco","San Diego"); -
If multiple partition columns are specified at table creation, for example
PARTITION BY LIST (dt,city)
, and a new partition needs to be added after table creation, you can execute:ALTER TABLE t_recharge_detail4
ADD PARTITION p202204_California VALUES IN
(
("2022-04-01", "Los Angeles"),
("2022-04-01", "San Francisco"),
("2022-04-02", "Los Angeles"),
("2022-04-02", "San Francisco")
);
-
DROP PARTITION(S)
- Drop a single partition:
ALTER TABLE [<db_name>.]<tbl_name>
DROP PARTITION [ IF EXISTS ] <partition_name> [ FORCE ]
- Drop partitions in batch (Supported from v3.3.1):
ALTER TABLE [<db_name>.]<tbl_name>
DROP PARTITIONS [ IF EXISTS ] { partition_name_list | multi_range_partitions } [ FORCE ]
partition_name_list ::= ( <partition_name> [, ... ] )
multi_range_partitions ::=
{ START ("<start_date_value>") END ("<end_date_value>") EVERY ( INTERVAL <N> <time_unit> )
| START ("<start_integer_value>") END ("<end_integer_value>") EVERY ( <granularity> ) } -- The partition column values still need to be enclosed in double quotes even if the partition column values are integers. However, the interval values in the EVERY clause do not need to be enclosed in double quotes.
Notes for multi_range_partitions
:
-
It only applies to Range Partitioning.
-
The parameters involved is consistent with those in ADD PARTITION(S).
-
It only supports partitions with a single Partition Key.
-
Drop partitions with Common Partition Expression (Supported from v3.4.1):
ALTER TABLE [<db_name>.]<tbl_name>
DROP PARTITIONS WHERE <expr>
From v3.4.1 onwards, StarRocks supports dropping partitions using Common Partition Expression. You can specify a WHERE clause with an expression to filter the partitions to drop.
- The expression declares the partitions to be dropped. Partitions that meet the condition in the expression will be dropped in batch. Be cautious when proceeding.
- The expression can only contain partition columns and constants. Non-partition columns are not supported.
- Common Partition Expression applies to List partitions and Range partitions differently:
- For tables with List partitions, StarRocks supports deleting partitions filtered by the Common Partition Expression.
- For tables with Range partitions, StarRocks can only filter and delete partitions using the partition pruning capability of FE. Partitions correspond to predicates that are not supported by partition pruning cannot be filtered and deleted.
Example:
-- Drop the data earlier than the last three months. Column `dt` is the partition column of the table.
ALTER TABLE t1 DROP PARTITIONS WHERE dt < CURRENT_DATE() - INTERVAL 3 MONTH;
- Keep at least one partition for partitioned tables.
- If FORCE is not specified, you can recover the dropped partitions by using the RECOVER command within a specified period (1 day by default).
- If FORCE is specified, the partitions will be deleted directly regardless of whether there are any unfinished operations on the partitions, and they cannot be recovered. Thus, generally, this operation is not recommended.
Add a temporary partition
Syntax:
ALTER TABLE [<db_name>.]<tbl_name>
ADD TEMPORARY PARTITION [IF NOT EXISTS] <partition_name>
partition_desc ["key"="value"]
[DISTRIBUTED BY HASH (k1[,k2 ...]) [BUCKETS num]]
Use a temporary partition to replace the current partition
Syntax:
ALTER TABLE [<db_name>.]<tbl_name>
REPLACE PARTITION <partition_name>
partition_desc ["key"="value"]
WITH TEMPORARY PARTITION
partition_desc ["key"="value"]
[PROPERTIES ("key"="value", ...)]
Drop a temporary partition
Syntax:
ALTER TABLE [<db_name>.]<tbl_name>
DROP TEMPORARY PARTITION <partition_name>
Modify partition properties
Syntax
ALTER TABLE [<db_name>.]<tbl_name>
MODIFY PARTITION { <partition_name> | ( <partition1_name> [, <partition2_name> ...] ) | (*) }
SET ("key" = "value", ...);
Usages
-
The following properties of a partition can be modified:
- storage_medium
- storage_cooldown_ttl or storage_cooldown_time
- replication_num
-
For the table that has only one partition, the partition name is the same as the table name. If the table is divided into multiple partitions, you can use
(*)
to modify the properties of all partitions, which is more convenient. -
Execute
SHOW PARTITIONS FROM <tbl_name>
to view the partition properties after modification.
Modify the bucketing method and number of buckets (from v3.2)
Syntax:
ALTER TABLE [<db_name>.]<table_name>
[ partition_names ]
[ distribution_desc ]
partition_names ::=
(PARTITION | PARTITIONS) ( <partition_name> [, <partition_name> ...] )
distribution_desc ::=
DISTRIBUTED BY RANDOM [ BUCKETS <num> ] |
DISTRIBUTED BY HASH ( <column_name> [, <column_name> ...] ) [ BUCKETS <num> ]
Example:
For example, the original table is a Duplicate Key table where hash bucketing is used and the number of buckets is automatically set by StarRocks.
CREATE TABLE IF NOT EXISTS details (
event_time DATETIME NOT NULL COMMENT "datetime of event",
event_type INT NOT NULL COMMENT "type of event",
user_id INT COMMENT "id of user",
device_code INT COMMENT "device code",
channel INT COMMENT ""
)
DUPLICATE KEY(event_time, event_type)
PARTITION BY date_trunc('day', event_time)
DISTRIBUTED BY HASH(user_id);
-- Insert data of several days
INSERT INTO details (event_time, event_type, user_id, device_code, channel) VALUES
-- Data of November 26th
('2023-11-26 08:00:00', 1, 101, 12345, 2),
('2023-11-26 09:15:00', 2, 102, 54321, 3),
('2023-11-26 10:30:00', 1, 103, 98765, 1),
-- Data of November 27th
('2023-11-27 08:30:00', 1, 104, 11111, 2),
('2023-11-27 09:45:00', 2, 105, 22222, 3),
('2023-11-27 11:00:00', 1, 106, 33333, 1),
-- Data of November 28th
('2023-11-28 08:00:00', 1, 107, 44444, 2),
('2023-11-28 09:15:00', 2, 108, 55555, 3),
('2023-11-28 10:30:00', 1, 109, 66666, 1);
Modify the bucketing method only
NOTICE
- The modification is applied to all partitions in the table and cannot be applied to specific partitions only.
- Although only the bucketing method needs to be modified, the number of buckets still needs to be specified in the command using
BUCKETS <num>
. IfBUCKETS <num>
is not specified, it means that the number of buckets is automatically determined by StarRocks.
-
The bucketing method is modified to random bucketing from hash bucketing and the number of buckets remains automatically set by StarRocks.
ALTER TABLE details DISTRIBUTED BY RANDOM;
-
The keys for hash bucketing are modified to
user_id, event_time
fromevent_time, event_type
. And the number of buckets remains automatically set by StarRocks.ALTER TABLE details DISTRIBUTED BY HASH(user_id, event_time);
Modify the number of buckets only
NOTICE
Although only the number of buckets needs to be modified, the bucketing method still needs to be specified in the command, for example,
HASH(user_id)
.
-
Modify the number of buckets for all partitions to 10 from being automatically set by StarRocks.
ALTER TABLE details DISTRIBUTED BY HASH(user_id) BUCKETS 10;
-
Modify the number of buckets for specified partitions to 15 from being automatically set by StarRocks.
ALTER TABLE details PARTITIONS (p20231127, p20231128) DISTRIBUTED BY HASH(user_id) BUCKETS 15 ;
NOTE
Partition names can be viewed by executing
SHOW PARTITIONS FROM <table_name>;
.
Modify both the bucketing method and the number of buckets
NOTICE
The modification is applied to all partitions in the table and cannot be applied to specific partitions only.
-
Modify the bucketing method from hash bucketing to random bucketing, and change the number of buckets to 10 from being automatically set by StarRocks.
ALTER TABLE details DISTRIBUTED BY RANDOM BUCKETS 10;
-
Modify the key for hash bucketing, and change the number of buckets to 10 from being automatically set by StarRocks. The key used for hashing bucketing is modified to
user_id, event_time
from the originalevent_time, event_type
. The number of buckets is modified to 10 from automatically set by StarRocks.ALTER TABLE details DISTRIBUTED BY HASH(user_id, event_time) BUCKETS 10;
``
Modify columns (add/delete columns, change the order of columns)
Add a column to the specified location of the specified index
Syntax:
ALTER TABLE [<db_name>.]<tbl_name>
ADD COLUMN column_name column_type [KEY | agg_type] [DEFAULT "default_value"]
[AFTER column_name|FIRST]
[TO rollup_index_name]
[PROPERTIES ("key"="value", ...)]
Note:
- If you add a value column to an Aggregate table, you need to specify agg_type.
- If you add a key column to a non-Aggregate table (such as a Duplicate Key table), you need to specify the KEY keyword.
- You cannot add a column that already exists in the base index to the rollup index. (You can recreate a rollup index if needed.)
Add multiple columns to specified index
Syntax:
-
Add multiple columns
ALTER TABLE [<db_name>.]<tbl_name>
ADD COLUMN (column_name1 column_type [KEY | agg_type] DEFAULT "default_value", ...)
[TO rollup_index_name]
[PROPERTIES ("key"="value", ...)] -
Add multiple columns and use AFTER to specify locations of the added columns
ALTER TABLE [<db_name>.]<tbl_name>
ADD COLUMN column_name1 column_type [KEY | agg_type] DEFAULT "default_value" AFTER column_name,
ADD COLUMN column_name2 column_type [KEY | agg_type] DEFAULT "default_value" AFTER column_name
[, ...]
[TO rollup_index_name]
[PROPERTIES ("key"="value", ...)]
Note:
-
If you add a value column to an Aggregate table, you need to specify
agg_type
. -
If you add a key column to a non-Aggregate table, you need to specify the KEY keyword.
-
You cannot add a column that already exists in the base index to the rollup index. (You can create another rollup index if needed.)
Add a generated column (from v3.1)
Syntax:
ALTER TABLE [<db_name>.]<tbl_name>
ADD COLUMN col_name data_type [NULL] AS generation_expr [COMMENT 'string']
You can add a generated column and specify its expression. The generated column can be used to precompute and store the results of expressions, which significantly accelerates queries with the same complex expressions. Since v3.1, StarRocks supports generated columns.