ALTER TABLE

ALTER TABLE 用于修改现有表，包括：

• 重命名表、分区、索引或者列
• 修改表注释
• 修改分区（添加/删除分区和修改分区属性）
• 修改分桶方式和分桶数量
• 修改列（添加/删除列和更改列的顺序）
• 创建/删除 Rollup 索引
• 修改 Bitmap 索引
• 修改表属性
• 原子交换
• 手动数据版本合并
• 删除主键持久化索引

提示

该操作需要目标表的 ALTER 权限。

语法

ALTER TABLE [<db_name>.]<tbl_name>
alter_clause1[, alter_clause2, ...]

alter_clause 可以进行以下操作：重命名、注释、分区、分桶、列、Rollup 索引、Bitmap 索引、表属性、交换和合并。

• rename: 重命名表、Rollup 索引、分区或列（从 v3.3.2 版本开始支持）。
• comment: 修改表的注释（从 v3.1 版本开始支持）。
• partition: 修改分区属性、删除分区或添加分区。
• bucket: 修改分桶方式和分桶数量。
• column: 添加、删除、重新排序列或修改列类型。
• rollup index: 创建或删除 Rollup 索引。
• bitmap index: 修改索引（仅可以修改 Bitmap 索引）。
• swap: 原子交换两张表。
• compaction: 执行手动合并以合并已加载数据的版本（从 v3.1 版本开始支持）。
• drop persistent index: 在共享数据集群中删除 Primary Key 表的持久化索引。从 v3.3.9 版本开始支持。

限制和使用注意事项

• 不能在同一个 ALTER TABLE 语句中执行对分区、列和 Rollup 索引的操作。
• 列注释不能被修改。
• 一张表在同一时间只能有一个正在进行的 Schema Change 操作。不能同时在一张表上运行两个 Schema Change 命令。
• 对分桶、列和 Rollup 索引的操作是异步操作。任务提交后会立即返回成功消息。您可以运行 SHOW ALTER TABLE 命令来检查进度，并运行 CANCEL ALTER TABLE 命令来取消操作。
• 重命名、注释、分区、Bitmap 索引和交换的操作是同步操作，命令返回表示执行完成。

重命名

重命名支持修改表名、Rollup 索引和分区名称。

重命名表

ALTER TABLE <tbl_name> RENAME <new_tbl_name>

重命名 Rollup 索引

ALTER TABLE [<db_name>.]<tbl_name>
RENAME ROLLUP <old_rollup_name> <new_rollup_name>

重命名分区

ALTER TABLE [<db_name>.]<tbl_name>
RENAME PARTITION <old_partition_name> <new_partition_name>

重命名列

从 v3.3.2 版本开始，StarRocks 支持重命名列。

ALTER TABLE [<db_name>.]<tbl_name>
RENAME COLUMN <old_col_name> [ TO ] <new_col_name>

注意

• 将列从 A 重命名为 B 后，不支持添加名为 A 的新列。
• 基于重命名列构建的物化视图将不会生效。您必须在新名称的列上重建它们。

修改表注释（从 v3.1 开始）

语法

ALTER TABLE [<db_name>.]<tbl_name> COMMENT = "<new table comment>";

提示

目前，列注释不能被修改。

修改分区

ADD PARTITION(S)

您可以选择添加范围分区或列表分区。不支持添加表达式分区。

语法：

• 范围分区

  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.

• 列表分区

  ALTER TABLE
      ADD PARTITION <partition_name> VALUES IN (value_list) [distribution_desc] ["key"="value"];
  
  value_list ::=
      value_item [, ...]
  
  value_item ::=
      { <value> | ( <value> [, ...] ) }

参数

• 分区相关参数

  • 对于范围分区，您可以添加单个范围分区（single_range_partition）或批量添加多个范围分区（multi_range_partitions）。
  • 对于列表分区，您只能添加单个列表分区。

• distribution_desc:

  您可以单独设置新分区的桶数，但不能单独设置分桶方式。

• "key"="value":

  您可以为新分区设置属性。有关详细信息，请参阅 CREATE TABLE。

示例

• 范围分区

  • 如果在创建表时分区列被指定为 event_day，例如 PARTITION BY RANGE(event_day)，并且需要在创建表后添加新分区，您可以执行

    ALTER TABLE site_access ADD PARTITION p4 VALUES LESS THAN ("2020-04-30");

  • 如果在创建表时分区列被指定为 datekey，例如 PARTITION BY RANGE (datekey)，并且需要在创建表后批量添加多个分区，您可以执行

    ALTER TABLE site_access
        ADD PARTITIONS START ("2021-01-05") END ("2021-01-10") EVERY (INTERVAL 1 DAY);

• 列表分区

  • 如果在创建表时指定了单个分区列，例如 PARTITION BY LIST (city)，并且需要在创建表后添加新分区，您可以执行

    ALTER TABLE t_recharge_detail2
    ADD PARTITION pCalifornia VALUES IN ("Los Angeles","San Francisco","San Diego");

  • 如果在创建表时指定了多个分区列，例如 PARTITION BY LIST (dt,city)，并且需要在创建表后添加新分区，您可以执行

    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)

• 删除单个分区

ALTER TABLE [<db_name>.]<tbl_name>
DROP PARTITION [ IF EXISTS ] <partition_name> [ FORCE ]

• 批量删除分区（从 v3.4.0 开始支持）

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.

multi_range_partitions 的注意事项

• 它仅适用于范围分区。

• 涉及的参数与 ADD PARTITION(S) 中的参数一致。

• 它仅支持具有单个分区键的分区。

• 使用公共分区表达式删除分区（从 v3.5.0 开始支持）

ALTER TABLE [<db_name>.]<tbl_name>
DROP PARTITIONS WHERE <expr>

从 v3.5.0 版本开始，StarRocks 支持使用公共分区表达式删除分区。您可以指定带有表达式的 WHERE 子句来过滤要删除的分区。

• 该表达式声明要删除的分区。满足表达式条件的分区将被批量删除。请谨慎操作。
• 表达式只能包含分区列和常量。不支持非分区列。
• 通用分区表达式对 List 分区和 Range 分区的应用方式不同
  • 对于具有 List 分区的表，StarRocks 支持删除通过通用分区表达式过滤的分区。
  • 对于具有 Range 分区的表，StarRocks 只能使用 FE 的分区裁剪功能来过滤和删除分区。与分区裁剪不支持的谓词对应的分区无法被过滤和删除。

示例

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

注意

• 为分区表至少保留一个分区。
• 如果未指定 FORCE，您可以在指定的时间段内（默认 1 天）使用 RECOVER 命令恢复已删除的分区。
• 如果指定 FORCE，则无论分区上是否有任何未完成的操作，都将直接删除分区，并且无法恢复。因此，通常不建议使用此操作。

添加临时分区

语法

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

使用临时分区替换当前分区

语法

ALTER TABLE [<db_name>.]<tbl_name>
REPLACE PARTITION <partition_name>
partition_desc ["key"="value"]
WITH TEMPORARY PARTITION
partition_desc ["key"="value"]
[PROPERTIES ("key"="value", ...)]

删除临时分区

语法

ALTER TABLE [<db_name>.]<tbl_name>
DROP TEMPORARY PARTITION <partition_name>

修改分区属性

语法

ALTER TABLE [<db_name>.]<tbl_name>
MODIFY PARTITION { <partition_name> | ( <partition1_name> [, <partition2_name> ...] ) | (*) }
SET ("key" = "value", ...);

用法

• 可以修改分区的以下属性

  • storage_medium
  • storage_cooldown_ttl 或 storage_cooldown_time
  • replication_num

• 对于只有一个分区的表，分区名称与表名相同。如果表被分成多个分区，您可以使用 (*) 来修改所有分区的属性，这更方便。

• 执行 SHOW PARTITIONS FROM <tbl_name> 查看修改后的分区属性。

修改分桶方式和分桶数量（从 v3.2 开始）

语法

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

示例

例如，原始表是一个 Duplicate Key 表，其中使用哈希分桶，并且桶数由 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);

仅修改分桶方式

注意

• 该修改应用于表中的所有分区，不能仅应用于特定分区。
• 虽然只需要修改分桶方式，但仍需要在命令中使用 BUCKETS <num> 指定桶数。如果未指定 BUCKETS <num>，则表示桶数由 StarRocks 自动确定。

• 分桶方式从哈希分桶修改为随机分桶，并且桶数保持由 StarRocks 自动设置。

  ALTER TABLE details DISTRIBUTED BY RANDOM;

• 哈希分桶的键从 event_time, event_type 修改为 user_id, event_time。并且桶数保持由 StarRocks 自动设置。

  ALTER TABLE details DISTRIBUTED BY HASH(user_id, event_time);

仅修改桶数

注意

虽然只需要修改桶数，但仍需要在命令中指定分桶方式，例如，HASH(user_id)。

• 将所有分区的桶数从由 StarRocks 自动设置修改为 10。

  ALTER TABLE details DISTRIBUTED BY HASH(user_id) BUCKETS 10;

• 将指定分区的桶数从由 StarRocks 自动设置修改为 15。

  ALTER TABLE details PARTITIONS (p20231127, p20231128) DISTRIBUTED BY HASH(user_id) BUCKETS 15 ;

  注意

  可以通过执行 SHOW PARTITIONS FROM <table_name>; 查看分区名称。

同时修改分桶方式和桶数

注意

该修改应用于表中的所有分区，不能仅应用于特定分区。

• 将分桶方式从哈希分桶修改为随机分桶，并将桶数从由 StarRocks 自动设置更改为 10。

  ALTER TABLE details DISTRIBUTED BY RANDOM BUCKETS 10;

• 修改哈希分桶的键，并将桶数从由 StarRocks 自动设置更改为 10。用于哈希分桶的键从原始的 event_time, event_type 修改为 user_id, event_time。桶数从由 StarRocks 自动设置修改为 10。

  ALTER TABLE details DISTRIBUTED BY HASH(user_id, event_time) BUCKETS 10;
  ``

修改列（添加/删除列，更改列的顺序）

将列添加到指定索引的指定位置

语法

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", ...)]

注意

1. 如果您将值列添加到 Aggregate 表，则需要指定 agg_type。
2. 如果您将键列添加到非 Aggregate 表（例如 Duplicate Key 表），则需要指定 KEY 关键字。
3. 您不能将已经存在于基本索引中的列添加到 Rollup 索引。（如果需要，您可以重新创建 Rollup 索引。）

将多个列添加到指定索引

语法

• 添加多个列

  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", ...)]

• 添加多个列并使用 AFTER 指定添加的列的位置

  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", ...)]

注意

1. 如果您将值列添加到 Aggregate 表，则需要指定 agg_type。

2. 如果您将键列添加到非 Aggregate 表，则需要指定 KEY 关键字。

3. 您不能将已经存在于基本索引中的列添加到 Rollup 索引。（如果需要，您可以创建另一个 Rollup 索引。）

添加生成列（从 v3.1 开始）

语法

ALTER TABLE [<db_name>.]<tbl_name>
ADD COLUMN col_name data_type [NULL] AS generation_expr [COMMENT 'string']

您可以添加生成列并指定其表达式。生成列 可以用于预计算和存储表达式的结果，这可以显著加速具有相同复杂表达式的查询。从 v3.1 开始，StarRocks 支持生成列。

从指定索引中删除列

语法

ALTER TABLE [<db_name>.]<tbl_name>
DROP COLUMN column_name
[FROM rollup_index_name];

注意

1. 您不能删除分区列。
2. 如果从基本索引中删除了列，则如果它包含在 Rollup 索引中，也会被删除。

修改指定索引的列类型和列位置

语法

ALTER TABLE [<db_name>.]<tbl_name>
MODIFY COLUMN column_name column_type [KEY | agg_type] [NULL | NOT NULL] [DEFAULT "default_value"]
[AFTER column_name|FIRST]
[FROM rollup_index_name]
[PROPERTIES ("key"="value", ...)]

注意

1. 如果您修改聚合模型中的值列，则需要指定 agg_type。

2. 如果您修改非聚合模型中的键列，则需要指定 KEY 关键字。

3. 只能修改列的类型。列的其他属性保持不变。（即，其他属性需要根据原始属性显式地写入语句中，请参阅 列 部分的示例 8）。

4. 不能修改分区列。

5. 目前支持以下类型的转换（精度损失由用户保证）。

   • 将 TINYINT/SMALLINT/INT/BIGINT 转换为 TINYINT/SMALLINT/INT/BIGINT/DOUBLE。
   • 将 TINYINT/SMALLINT/INT/BIGINT/LARGEINT/FLOAT/DOUBLE/DECIMAL 转换为 VARCHAR。VARCHAR 支持修改最大长度。
   • 将 VARCHAR 转换为 TINYINT/SMALLINT/INT/BIGINT/LARGEINT/FLOAT/DOUBLE。
   • 将 VARCHAR 转换为 DATE（当前支持六种格式："%Y-%m-%d"、"%y-%m-%d"、"%Y%m%d"、"%y%m%d"、"%Y/%m/%d"、"%y/%m/%d"）
   • 将 DATETIME 转换为 DATE（仅保留年-月-日信息，即 2019-12-09 21:47:05 <--> 2019-12-09）
   • 将 DATE 转换为 DATETIME（将小时、分钟、秒设置为零，例如：2019-12-09 <--> 2019-12-09 00:00:00）
   • 将 FLOAT 转换为 DOUBLE
   • 将 INT 转换为 DATE（如果 INT 数据转换失败，则原始数据保持不变）

6. 不支持从 NULL 转换为 NOT NULL。

重新排序指定索引的列

语法

ALTER TABLE [<db_name>.]<tbl_name>
ORDER BY (column_name1, column_name2, ...)
[FROM rollup_index_name]
[PROPERTIES ("key"="value", ...)]

注意

• 必须写入索引中的所有列。
• 值列在键列之后列出。

修改排序列

从 v3.0 开始，可以修改 Primary Key 表的排序列。v3.3 将此支持扩展到 Duplicate Key 表、Aggregate 表和 Unique Key 表。

Duplicate Key 表和 Primary Key 表中的排序列可以是任何排序的列的组合。Aggregate 表和 Unique Key 表中的排序列必须包含所有键列，但列的顺序不需要与键列相同。

语法

ALTER TABLE [<db_name>.]<table_name>
[ order_desc ]

order_desc ::=
    ORDER BY <column_name> [, <column_name> ...]

示例：修改 Primary Key 表中的排序列。

例如，原始表是一个 Primary Key 表，其中排序列和主键是耦合的，即 dt, order_id。

create table orders (
    dt date NOT NULL,
    order_id bigint NOT NULL,
    user_id int NOT NULL,
    merchant_id int NOT NULL,
    good_id int NOT NULL,
    good_name string NOT NULL,
    price int NOT NULL,
    cnt int NOT NULL,
    revenue int NOT NULL,
    state tinyint NOT NULL
) PRIMARY KEY (dt, order_id)
PARTITION BY date_trunc('day', dt)
DISTRIBUTED BY HASH(order_id);

将排序列与主键解耦，并将排序列修改为 dt, revenue, state。

ALTER TABLE orders ORDER BY (dt, revenue, state);

修改 STRUCT 列以添加或删除字段

Beta 功能

Beta 功能使用建议

从 v3.2.10 和 v3.3.2 版本开始，StarRocks 支持修改 STRUCT 列以添加或删除字段，可以是嵌套的，也可以在 ARRAY 类型中。

语法

-- Add a field
ALTER TABLE [<db_name>.]<tbl_name> MODIFY COLUMN <column_name>
ADD FIELD field_path field_desc

-- Drop a field
ALTER TABLE [<db_name>.]<tbl_name> MODIFY COLUMN <column_name>
DROP FIELD field_path

field_path ::= [ { <field_name>. | [*]. } [ ... ] ]<field_name>

  -- Note that here `[*]` as a whole is a pre-defined symbol and represents all elements in the ARRAY field 
  -- when adding or removing a field in a STRUCT type nested within an ARRAY type.
  -- For detailed information, see the parameter description and examples of `field_path`.

field_desc ::= <field_type> [ AFTER <prior_field_name> | FIRST ]

参数

• field_path：要添加或删除的字段。这可以是一个简单的字段名称，表示顶层维度字段，例如，new_field_name，或者是一个列访问路径，表示嵌套字段，例如，lv1_k1.lv2_k2.[*].new_field_name。
• [*]：当 STRUCT 类型嵌套在 ARRAY 类型中时，[*] 表示 ARRAY 字段中的所有元素。它用于在 ARRAY 字段下嵌套的所有 STRUCT 元素中添加或删除字段。
• prior_field_name：新添加字段之前的字段。与 AFTER 关键字一起使用以指定新字段的顺序。如果使用 FIRST 关键字，则不需要指定此参数，表示新字段应该是第一个字段。prior_field_name 的维度由 field_path 确定（具体来说，是 new_field_name 之前的部分，即 level1_k1.level2_k2.[*]），不需要显式指定。

field_path 的示例

• 在嵌套在 STRUCT 列中的 STRUCT 字段中添加或删除子字段。

  假设有一个列 fx stuct<c1 int, c2 struct <v1 int, v2 int>>。在 c2 下添加 v3 字段的语法是

  ALTER TABLE tbl MODIFY COLUMN fx ADD FIELD c2.v3 INT

  操作后，列变为 fx stuct<c1 int, c2 struct <v1 int, v2 int, v3 int>>。

• 在嵌套在 ARRAY 字段中的每个 STRUCT 字段中添加或删除子字段。

  假设有一个列 fx struct<c1 int, c2 array<struct <v1 int, v2 int>>>。字段 c2 是一个 ARRAY 类型，其中包含一个带有两个字段 v1 和 v2 的 STRUCT。将 v3 字段添加到嵌套 STRUCT 的语法是

  ALTER TABLE tbl MODIFY COLUMN fx ADD FIELD c2.[*].v3 INT

  操作后，列变为 fx struct<c1 int, c2 array<struct <v1 int, v2 int, v3 int>>>。

有关更多用法说明，请参阅 示例 - 列 -14。

注意

• 目前，此功能仅在共享无集群中受支持。
• 表必须启用 fast_schema_evolution 属性。
• 不支持修改 STRUCT 类型中 MAP 子字段的 Value 类型，无论 Value 类型是 ARRAY、STRUCT 还是 MAP。
• 新添加的字段不能具有默认值或 Nullable 等属性。它们默认为 Nullable，默认值为 null。
• 使用此功能后，不允许将集群直接降级到不支持此功能的版本。

修改 Rollup 索引

创建 Rollup 索引

语法

ALTER TABLE [<db_name>.]<tbl_name> 
ADD ROLLUP rollup_name (column_name1, column_name2, ...)
[FROM from_index_name]
[PROPERTIES ("key"="value", ...)]

PROPERTIES：支持设置超时时间，默认超时时间为一天。

示例

ALTER TABLE [<db_name>.]<tbl_name> 
ADD ROLLUP r1(col1,col2) from r0;

批量创建 Rollup 索引

语法

ALTER TABLE [<db_name>.]<tbl_name>
ADD ROLLUP [rollup_name (column_name1, column_name2, ...)
[FROM from_index_name]
[PROPERTIES ("key"="value", ...)],...];

示例

ALTER TABLE [<db_name>.]<tbl_name>
ADD ROLLUP r1(col1,col2) from r0, r2(col3,col4) from r0;

注意

1. 如果未指定 from_index_name，则默认从基本索引创建。
2. Rollup 表中的列必须是 from_index 中现有的列。
3. 在属性中，用户可以指定存储格式。有关详细信息，请参阅 CREATE TABLE。

删除 Rollup 索引

语法

ALTER TABLE [<db_name>.]<tbl_name>
DROP ROLLUP rollup_name [PROPERTIES ("key"="value", ...)];

示例

ALTER TABLE [<db_name>.]<tbl_name> DROP ROLLUP r1;

批量删除 Rollup 索引

语法

ALTER TABLE [<db_name>.]<tbl_name>
DROP ROLLUP [rollup_name [PROPERTIES ("key"="value", ...)],...];

示例

ALTER TABLE [<db_name>.]<tbl_name> DROP ROLLUP r1, r2;

注意：您不能删除基本索引。

修改 Bitmap 索引

Bitmap 索引支持以下修改

创建 Bitmap 索引

语法

ALTER TABLE [<db_name>.]<tbl_name>
ADD INDEX index_name (column [, ...],) [USING BITMAP] [COMMENT 'balabala'];

注意

1. Bitmap index is only supported for the current version.
2. A BITMAP index is created only in a single column.

删除 Bitmap 索引

语法

DROP INDEX index_name;

修改表属性

语法

ALTER TABLE [<db_name>.]<tbl_name>
SET ("key" = "value")

目前，StarRocks 支持修改以下表属性

• replication_num
• default.replication_num
• default.storage_medium
• 动态分区相关属性
• enable_persistent_index
• bloom_filter_columns
• colocate_with
• bucket_size（从 3.2 开始支持）
• base_compaction_forbidden_time_ranges（从 v3.2.13 开始支持）

注意

• 在大多数情况下，您一次只允许修改一个属性。只有当这些属性具有相同的前缀时，您才能一次修改多个属性。目前，仅支持 dynamic_partition. 和 binlog.。
• 您还可以通过合并到上述列操作来修改属性。请参阅以下示例。

交换

交换支持原子交换两张表。

语法

ALTER TABLE [<db_name>.]<tbl_name>
SWAP WITH <tbl_name>;

注意

• OLAP 表之间的 Unique Key 和 Foreign Key 约束将在交换期间进行验证，以确保要交换的两张表的约束一致。如果检测到不一致，将返回错误。如果未检测到不一致，Unique Key 和 Foreign Key 约束将自动交换。
• 依赖于被交换表的物化视图将自动设置为非活动状态，并且其 Unique Key 和 Foreign Key 约束将被删除且不再可用。

手动合并（从 3.1 开始）

StarRocks 使用合并机制来合并已加载数据的不同版本。此功能可以将小文件合并为大文件，从而有效地提高查询性能。

在 v3.1 之前，合并以两种方式执行

• 系统自动合并：合并在后台的 BE 级别执行。用户不能指定数据库或表进行合并。
• 用户可以通过调用 HTTP 接口来执行合并。

从 v3.1 开始，StarRocks 提供了一个 SQL 接口，用户可以通过运行 SQL 命令手动执行合并。他们可以选择特定的表或分区进行合并。这为合并过程提供了更大的灵活性和控制。

共享数据集群从 v3.3.0 开始支持此功能。

注意

从 v3.2.13 开始，您可以使用属性 base_compaction_forbidden_time_ranges 禁止在特定时间范围内进行 Base Compaction。

语法

ALTER TABLE <tbl_name> [ BASE | CUMULATIVE ] COMPACT [ <partition_name> | ( <partition1_name> [, <partition2_name> ...] ) ]

即

-- Perform compaction on the entire table.
ALTER TABLE <tbl_name> COMPACT

-- Perform compaction on a single partition.
ALTER TABLE <tbl_name> COMPACT <partition_name>

-- Perform compaction on multiple partitions.
ALTER TABLE <tbl_name> COMPACT (<partition1_name>[,<partition2_name>,...])

-- Perform cumulative compaction.
ALTER TABLE <tbl_name> CUMULATIVE COMPACT (<partition1_name>[,<partition2_name>,...])

-- Perform base compaction.
ALTER TABLE <tbl_name> BASE COMPACT (<partition1_name>[,<partition2_name>,...])

information_schema 数据库中的 be_compactions 表记录了合并结果。您可以运行 SELECT * FROM information_schema.be_compactions; 查询合并后的数据版本。

删除 Primary Key 持久化索引（从 3.3.9 开始）

语法

ALTER TABLE [<db_name>.]<tbl_name>
DROP PERSISTENT INDEX ON TABLETS(<tablet_id>[, <tablet_id>, ...]);

注意

StarRocks 仅支持删除共享数据集群中云原生 Primary Key 表的持久化索引。

示例

表

1. 修改表的默认副本数，用作新添加分区的默认副本数。

   ALTER TABLE example_db.my_table
   SET ("default.replication_num" = "2");

2. 修改单分区表的实际副本数。

   ALTER TABLE example_db.my_table
   SET ("replication_num" = "3");

3. 修改副本之间的数据写入和复制模式。

   ALTER TABLE example_db.my_table
   SET ("replicated_storage" = "false");

   此示例将副本之间的数据写入和复制模式设置为“无领导者复制”，这意味着数据同时写入多个副本，而不区分主副本和辅助副本。有关更多信息，请参阅 CREATE TABLE 中的 replicated_storage 参数。

分区

1. 添加分区并使用默认分桶模式。现有分区是 [MIN, 2013-01-01)。添加的分区是 [2013-01-01, 2014-01-01)。

   ALTER TABLE example_db.my_table
   ADD PARTITION p1 VALUES LESS THAN ("2014-01-01");

2. 添加分区并使用新的桶数。

   ALTER TABLE example_db.my_table
   ADD PARTITION p1 VALUES LESS THAN ("2015-01-01")
   DISTRIBUTED BY HASH(k1);

3. 添加分区并使用新的副本数。

   ALTER TABLE example_db.my_table
   ADD PARTITION p1 VALUES LESS THAN ("2015-01-01")
   ("replication_num"="1");

4. 更改分区的副本数。

   ALTER TABLE example_db.my_table
   MODIFY PARTITION p1 SET("replication_num"="1");

5. 批量更改指定分区的副本数。

   ALTER TABLE example_db.my_table
   MODIFY PARTITION (p1, p2, p4) SET("replication_num"="1");

6. 批量更改所有分区的存储介质。

   ALTER TABLE example_db.my_table
   MODIFY PARTITION (*) SET("storage_medium"="HDD");

7. 删除分区。

   ALTER TABLE example_db.my_table
   DROP PARTITION p1;

8. 添加具有上下边界的分区。

   ALTER TABLE example_db.my_table
   ADD PARTITION p1 VALUES [("2014-01-01"), ("2014-02-01"));

Rollup 索引

1. 基于基本索引 (k1,k2,k3,v1,v2) 创建 Rollup 索引 example_rollup_index。使用基于列的存储。

   ALTER TABLE example_db.my_table
   ADD ROLLUP example_rollup_index(k1, k3, v1, v2)
   PROPERTIES("storage_type"="column");

2. 基于 example_rollup_index(k1,k3,v1,v2) 创建索引 example_rollup_index2。

   ALTER TABLE example_db.my_table
   ADD ROLLUP example_rollup_index2 (k1, v1)
   FROM example_rollup_index;

3. 基于基本索引 (k1, k2, k3, v1) 创建索引 example_rollup_index3。Rollup 超时时间设置为一小时。

   ALTER TABLE example_db.my_table
   ADD ROLLUP example_rollup_index3(k1, k3, v1)
   PROPERTIES("storage_type"="column", "timeout" = "3600");

4. 删除索引 example_rollup_index2。

   ALTER TABLE example_db.my_table
   DROP ROLLUP example_rollup_index2;

列

1. 在 example_rollup_index 的 col1 列之后添加键列 new_col（非聚合列）。

   ALTER TABLE example_db.my_table
   ADD COLUMN new_col INT KEY DEFAULT "0" AFTER col1
   TO example_rollup_index;

2. 在 example_rollup_index 的 col1 列之后添加值列 new_col（非聚合列）。

   ALTER TABLE example_db.my_table
   ADD COLUMN new_col INT DEFAULT "0" AFTER col1
   TO example_rollup_index;

3. 在 example_rollup_index 的 col1 列之后添加键列 new_col（聚合列）。

   ALTER TABLE example_db.my_table
   ADD COLUMN new_col INT DEFAULT "0" AFTER col1
   TO example_rollup_index;

4. 在 example_rollup_index 的 col1 列之后添加值列 new_col SUM（聚合列）。

   ALTER TABLE example_db.my_table
   ADD COLUMN new_col INT SUM DEFAULT "0" AFTER col1
   TO example_rollup_index;

5. 将多个列添加到 example_rollup_index（聚合）。

   ALTER TABLE example_db.my_table
   ADD COLUMN (col1 INT DEFAULT "1", col2 FLOAT SUM DEFAULT "2.3")
   TO example_rollup_index;

6. 将多个列添加到 example_rollup_index（聚合）并使用 AFTER 指定添加的列的位置。

   ALTER TABLE example_db.my_table
   ADD COLUMN col1 INT DEFAULT "1" AFTER `k1`,
   ADD COLUMN col2 FLOAT SUM AFTER `v2`,
   TO example_rollup_index;

7. 从 example_rollup_index 中删除列。

   ALTER TABLE example_db.my_table
   DROP COLUMN col2
   FROM example_rollup_index;

8. 将基本索引的 col1 的列类型修改为 BIGINT，并将其放在 col2 之后。

   ALTER TABLE example_db.my_table
   MODIFY COLUMN col1 BIGINT DEFAULT "1" AFTER col2;

9. 将基本索引的 val1 列的最大长度修改为 64。原始长度为 32。

   ALTER TABLE example_db.my_table
   MODIFY COLUMN val1 VARCHAR(64) REPLACE DEFAULT "abc";

10. 重新排序 example_rollup_index 中的列。原始列顺序为 k1、k2、k3、v1、v2。

    ALTER TABLE example_db.my_table
    ORDER BY (k3,k1,k2,v2,v1)
    FROM example_rollup_index;

11. 一次执行两个操作（ADD COLUMN 和 ORDER BY）。

    ALTER TABLE example_db.my_table
    ADD COLUMN v2 INT MAX DEFAULT "0" AFTER k2 TO example_rollup_index,
    ORDER BY (k3,k1,k2,v2,v1) FROM example_rollup_index;

12. 更改表的 bloomfilter 列。

    ALTER TABLE example_db.my_table
    SET ("bloom_filter_columns"="k1,k2,k3");

    此操作也可以合并到上述列操作中（请注意，多个子句的语法略有不同）。

    ALTER TABLE example_db.my_table
    DROP COLUMN col2
    PROPERTIES ("bloom_filter_columns"="k1,k2,k3");

13. 在单个语句中修改多个列的数据类型。

    ALTER TABLE example_db.my_table
    MODIFY COLUMN k1 VARCHAR(100) KEY NOT NULL,
    MODIFY COLUMN v2 DOUBLE DEFAULT "1" AFTER v1;

14. 在 STRUCT 类型数据中添加和删除字段。

    前提条件：创建一个表并插入一行数据。

    CREATE TABLE struct_test(
        c0 INT,
        c1 STRUCT<v1 INT, v2 STRUCT<v4 INT, v5 INT>, v3 INT>,
        c2 STRUCT<v1 INT, v2 ARRAY<STRUCT<v3 INT, v4 STRUCT<v5 INT, v6 INT>>>>
    )
    DUPLICATE KEY(c0)
    DISTRIBUTED BY HASH(`c0`) BUCKETS 1
    PROPERTIES (
        "fast_schema_evolution" = "true"
    );
    INSERT INTO struct_test VALUES (
        1, 
        ROW(1, ROW(2, 3), 4), 
        ROW(5, [ROW(6, ROW(7, 8)), ROW(9, ROW(10, 11))])
    );

    mysql> SELECT * FROM struct_test\G
    *************************** 1. row ***************************
    c0: 1
    c1: {"v1":1,"v2":{"v4":2,"v5":3},"v3":4}
    c2: {"v1":5,"v2":[{"v3":6,"v4":{"v5":7,"v6":8}},{"v3":9,"v4":{"v5":10,"v6":11}}]}
    • 将新字段添加到 STRUCT 类型列。

    ALTER TABLE struct_test MODIFY COLUMN c1 ADD FIELD v4 INT AFTER v2;

    mysql> SELECT * FROM struct_test\G
    *************************** 1. row ***************************
    c0: 1
    c1: {"v1":1,"v2":{"v4":2,"v5":3},"v4":null,"v3":4}
    c2: {"v1":5,"v2":[{"v3":6,"v4":{"v5":7,"v6":8}},{"v3":9,"v4":{"v5":10,"v6":11}}]}
    • 将新字段添加到嵌套 STRUCT 类型。

    ALTER TABLE struct_test MODIFY COLUMN c1 ADD FIELD v2.v6 INT FIRST;

    mysql> SELECT * FROM struct_test\G
    *************************** 1. row ***************************
    c0: 1
    c1: {"v1":1,"v2":{"v6":null,"v4":2,"v5":3},"v4":null,"v3":4}
    c2: {"v1":5,"v2":[{"v3":6,"v4":{"v5":7,"v6":8}},{"v3":9,"v4":{"v5":10,"v6":11}}]}
    • 将新字段添加到数组中的 STRUCT 类型。

    ALTER TABLE struct_test MODIFY COLUMN c2 ADD FIELD v2.[*].v7 INT AFTER v3;

    mysql> SELECT * FROM struct_test\G
    *************************** 1. row ***************************
    c0: 1
    c1: {"v1":1,"v2":{"v6":null,"v4":2,"v5":3},"v4":null,"v3":4}
    c2: {"v1":5,"v2":[{"v3":6,"v7":null,"v4":{"v5":7,"v6":8}},{"v3":9,"v7":null,"v4":{"v5":10,"v6":11}}]}
    • 从 STRUCT 类型列中删除字段。

    ALTER TABLE struct_test MODIFY COLUMN c1 DROP FIELD v3;

    mysql> SELECT * FROM struct_test\G
    *************************** 1. row ***************************
    c0: 1
    c1: {"v1":1,"v2":{"v6":null,"v4":2,"v5":3},"v4":null}
    c2: {"v1":5,"v2":[{"v3":6,"v7":null,"v4":{"v5":7,"v6":8}},{"v3":9,"v7":null,"v4":{"v5":10,"v6":11}}]}
    • 从嵌套 STRUCT 类型中删除字段。

    ALTER TABLE struct_test MODIFY COLUMN c1 DROP FIELD v2.v4;

    mysql> SELECT * FROM struct_test\G
    *************************** 1. row ***************************
    c0: 1
    c1: {"v1":1,"v2":{"v6":null,"v5":3},"v4":null}
    c2: {"v1":5,"v2":[{"v3":6,"v7":null,"v4":{"v5":7,"v6":8}},{"v3":9,"v7":null,"v4":{"v5":10,"v6":11}}]}
    • 从数组中的 STRUCT 类型中删除字段。

    ALTER TABLE struct_test MODIFY COLUMN c2 DROP FIELD v2.[*].v3;

    mysql> SELECT * FROM struct_test\G
    *************************** 1. row ***************************
    c0: 1
    c1: {"v1":1,"v2":{"v6":null,"v5":3},"v4":null}
    c2: {"v1":5,"v2":[{"v7":null,"v4":{"v5":7,"v6":8}},{"v7":null,"v4":{"v5":10,"v6":11}}]}

表属性

1. 更改表的 Colocate 属性。

   ALTER TABLE example_db.my_table
   SET ("colocate_with" = "t1");

2. 更改表的动态分区属性。

   ALTER TABLE example_db.my_table
   SET ("dynamic_partition.enable" = "false");

   如果需要向未配置动态分区属性的表中添加动态分区属性，则需要指定所有动态分区属性。

   ALTER TABLE example_db.my_table
   SET (
       "dynamic_partition.enable" = "true",
       "dynamic_partition.time_unit" = "DAY",
       "dynamic_partition.end" = "3",
       "dynamic_partition.prefix" = "p",
       "dynamic_partition.buckets" = "32"
       );

3. 更改表的存储介质属性。

   ALTER TABLE example_db.my_table SET("default.storage_medium"="SSD");

重命名

1. 将 table1 重命名为 table2。

   ALTER TABLE table1 RENAME table2;

2. 将 example_table 的 Rollup 索引 rollup1 重命名为 rollup2。

   ALTER TABLE example_table RENAME ROLLUP rollup1 rollup2;

3. 将 example_table 的分区 p1 重命名为 p2。

   ALTER TABLE example_table RENAME PARTITION p1 p2;

位图索引

1. 在 table1 的 siteid 列上创建位图索引。

   ALTER TABLE table1
   ADD INDEX index_1 (siteid) [USING BITMAP] COMMENT 'balabala';

2. 删除 table1 中 siteid 列的位图索引。

   ALTER TABLE table1
   DROP INDEX index_1;

交换

table1 和 table2 之间的原子交换。

ALTER TABLE table1 SWAP WITH table2

手动 Compaction

CREATE TABLE compaction_test( 
    event_day DATE,
    pv BIGINT)
DUPLICATE KEY(event_day)
PARTITION BY date_trunc('month', event_day)
DISTRIBUTED BY HASH(event_day) BUCKETS 8
PROPERTIES("replication_num" = "3");

INSERT INTO compaction_test VALUES
('2023-02-14', 2),
('2033-03-01',2);
{'label':'insert_734648fa-c878-11ed-90d6-00163e0dcbfc', 'status':'VISIBLE', 'txnId':'5008'}

INSERT INTO compaction_test VALUES
('2023-02-14', 2),('2033-03-01',2);
{'label':'insert_85c95c1b-c878-11ed-90d6-00163e0dcbfc', 'status':'VISIBLE', 'txnId':'5009'}

ALTER TABLE compaction_test COMPACT;

ALTER TABLE compaction_test COMPACT p203303;

ALTER TABLE compaction_test COMPACT (p202302,p203303);

ALTER TABLE compaction_test CUMULATIVE COMPACT (p202302,p203303);

ALTER TABLE compaction_test BASE COMPACT (p202302,p203303);

删除主键持久化索引

在共享数据集群中，删除主键表 db1.test_tbl 的 Tablets 100 和 101 上的持久化索引。

ALTER TABLE db1.test_tbl DROP PERSISTENT INDEX ON TABLETS (100, 101);

参考

• CREATE TABLE
• SHOW CREATE TABLE
• SHOW TABLES
• SHOW ALTER TABLE
• DROP TABLE