自动分区
更新时间：2025-08-21
使用场景
自动分区功能主要解决了用户预期基于某列对表进行分区操作，但该列的数据分布比较零散或者难以预测，在建表或调整表结构时难以准确创建所需分区，或者分区数量过多以至于手动创建过于繁琐的问题。
以时间类型分区列为例，在动态分区功能中，我们支持了按特定时间周期自动创建新分区以容纳实时数据。对于实时的用户行为日志等场景该功能基本能够满足需求。但在一些更复杂的场景下，例如处理非实时数据时，分区列与当前系统时间无关，且包含大量离散值。此时为提高效率我们希望依据此列对数据进行分区，但数据实际可能涉及的分区无法预先掌握，或者预期所需分区数量过大。这种情况下动态分区或者手动创建分区无法满足我们的需求，自动分区功能很好地覆盖了此类需求。
假设我们的表 DDL 如下：
SQL
1CREATE TABLE `DAILY_TRADE_VALUE`
2(
3 `TRADE_DATE` datev2 NOT NULL COMMENT '交易日期',
4 `TRADE_ID` varchar(40) NOT NULL COMMENT '交易编号',
5 ......
6)
7UNIQUE KEY(`TRADE_DATE`, `TRADE_ID`)
8PARTITION BY RANGE(`TRADE_DATE`)
9(
10 PARTITION p_2000 VALUES [('2000-01-01'), ('2001-01-01')),
11 PARTITION p_2001 VALUES [('2001-01-01'), ('2002-01-01')),
12 PARTITION p_2002 VALUES [('2002-01-01'), ('2003-01-01')),
13 PARTITION p_2003 VALUES [('2003-01-01'), ('2004-01-01')),
14 PARTITION p_2004 VALUES [('2004-01-01'), ('2005-01-01')),
15 PARTITION p_2005 VALUES [('2005-01-01'), ('2006-01-01')),
16 PARTITION p_2006 VALUES [('2006-01-01'), ('2007-01-01')),
17 PARTITION p_2007 VALUES [('2007-01-01'), ('2008-01-01')),
18 PARTITION p_2008 VALUES [('2008-01-01'), ('2009-01-01')),
19 PARTITION p_2009 VALUES [('2009-01-01'), ('2010-01-01')),
20 PARTITION p_2010 VALUES [('2010-01-01'), ('2011-01-01')),
21 PARTITION p_2011 VALUES [('2011-01-01'), ('2012-01-01')),
22 PARTITION p_2012 VALUES [('2012-01-01'), ('2013-01-01')),
23 PARTITION p_2013 VALUES [('2013-01-01'), ('2014-01-01')),
24 PARTITION p_2014 VALUES [('2014-01-01'), ('2015-01-01')),
25 PARTITION p_2015 VALUES [('2015-01-01'), ('2016-01-01')),
26 PARTITION p_2016 VALUES [('2016-01-01'), ('2017-01-01')),
27 PARTITION p_2017 VALUES [('2017-01-01'), ('2018-01-01')),
28 PARTITION p_2018 VALUES [('2018-01-01'), ('2019-01-01')),
29 PARTITION p_2019 VALUES [('2019-01-01'), ('2020-01-01')),
30 PARTITION p_2020 VALUES [('2020-01-01'), ('2021-01-01')),
31 PARTITION p_2021 VALUES [('2021-01-01'), ('2022-01-01'))
32)
33DISTRIBUTED BY HASH(`TRADE_DATE`) BUCKETS 10
34PROPERTIES (
35 "replication_num" = "1"
36);该表内存储了大量业务历史数据，依据交易发生的日期进行分区。可以看到在建表时，我们需要预先手动创建分区。如果分区列的数据范围发生变化，例如上表中增加了 2022 年的数据，则我们需要通过ALTER-TABLE-PARTITION对表的分区进行更改。如果这种分区需要变更，或者进行更细粒度的细分，修改起来非常繁琐。此时我们就可以使用 AUTO PARTITION 改写该表 DDL。
语法
建表时，使用以下语法填充CREATE-TABLE时的 partition_info 部分：
- AUTO RANGE PARTITION:
SQL
1 AUTO PARTITION BY RANGE (FUNC_CALL_EXPR)
2 ()其中
SQL
1 FUNC_CALL_EXPR ::= date_trunc ( <partition_column>, '<interval>' )- AUTO LIST PARTITION:
SQL
1 AUTO PARTITION BY LIST(`partition_col1`[, `partition_col2`, ...])
2 ()用法示例
- AUTO RANGE PARTITION
SQL
1 CREATE TABLE `date_table` (
2 `TIME_STAMP` datev2 NOT NULL
3 ) ENGINE=OLAP
4 DUPLICATE KEY(`TIME_STAMP`)
5 AUTO PARTITION BY RANGE (date_trunc(`TIME_STAMP`, 'month'))
6 (
7 )
8 DISTRIBUTED BY HASH(`TIME_STAMP`) BUCKETS 10
9 PROPERTIES (
10 "replication_allocation" = "tag.location.default: 1"
11 );- AUTO LIST PARTITION
SQL
1 CREATE TABLE `str_table` (
2 `str` varchar not null
3 ) ENGINE=OLAP
4 DUPLICATE KEY(`str`)
5 AUTO PARTITION BY LIST (`str`)
6 (
7 )
8 DISTRIBUTED BY HASH(`str`) BUCKETS 10
9 PROPERTIES (
10 "replication_allocation" = "tag.location.default: 1"
11 ); LIST 自动分区支持多个分区列，分区列写法同普通 LIST 分区一样： AUTO PARTITION BY LIST (col1, col2, ...)
约束
- 在 AUTO LIST PARTITION 中，分区名长度不得超过 50. 该长度来自于对应数据行上各分区列内容的拼接与转义，因此实际容许长度可能更短。
- 在 AUTO RANGE PARTITION 中，分区函数仅支持 date_trunc，分区列仅支持 DATE 或者 DATETIME 类型；
- 在 AUTO LIST PARTITION 中，不支持函数调用，分区列支持 BOOLEAN, TINYINT, SMALLINT, INT, BIGINT, LARGEINT, DATE, DATETIME, CHAR, VARCHAR 数据类型，分区值为枚举值。
- 在 AUTO LIST PARTITION 中，分区列的每个当前不存在对应分区的取值，都会创建一个独立的新 PARTITION。
NULL 值分区
当开启 session variable allow_partition_column_nullable 后：
- 对于 AUTO LIST PARTITION，可以使用 NULLABLE 列作为分区列，会正常创建对应的 NULL 值分区：
SQL
1 create table auto_null_list(
2 k0 varchar null
3 )
4 auto partition by list (k0)
5 (
6 )
7 DISTRIBUTED BY HASH(`k0`) BUCKETS 1
8 properties("replication_num" = "1");
9
10
11 insert into auto_null_list values (null);
12
13 select * from auto_null_list;
14 +------+
15 | k0 |
16 +------+
17 | NULL |
18 +------+
19
20 select * from auto_null_list partition(pX);
21 +------+
22 | k0 |
23 +------+
24 | NULL |
25 +------+- 对于 AUTO RANGE PARTITION，不支持 NULLABLE 列作为分区列。
SQL
1 CREATE TABLE `range_table_nullable` (
2 `k1` INT,
3 `k2` DATETIMEV2(3),
4 `k3` DATETIMEV2(6)
5 ) ENGINE=OLAP
6 DUPLICATE KEY(`k1`)
7 AUTO PARTITION BY RANGE (date_trunc(`k2`, 'day'))
8 (
9 )
10 DISTRIBUTED BY HASH(`k1`) BUCKETS 16
11 PROPERTIES (
12 "replication_allocation" = "tag.location.default: 1"
13 );
14ERROR 1105 (HY000): errCode = 2, detailMessage = AUTO RANGE PARTITION doesn't support NULL column场景示例
在使用场景一节中的示例，在使用 AUTO PARTITION 后，该表 DDL 可以改写为：
SQL
1CREATE TABLE `DAILY_TRADE_VALUE`
2(
3 `TRADE_DATE` datev2 NOT NULL,
4 `TRADE_ID` varchar(40) NOT NULL,
5 ......
6)
7UNIQUE KEY(`TRADE_DATE`, `TRADE_ID`)
8AUTO PARTITION BY RANGE (date_trunc(`TRADE_DATE`, 'year'))
9(
10)
11DISTRIBUTED BY HASH(`TRADE_DATE`) BUCKETS 10
12PROPERTIES (
13 "replication_num" = "1"
14);以此表只有两列为例，此时新表没有默认分区：
SQL
1show partitions from `DAILY_TRADE_VALUE`;
2Empty set (0.12 sec)经过插入数据后再查看，发现该表已经创建了对应的分区：
SQL
1insert into `DAILY_TRADE_VALUE` values ('2012-12-13', 1), ('2008-02-03', 2), ('2014-11-11', 3);
2
3show partitions from `DAILY_TRADE_VALUE`;
4+-------------+-----------------+----------------+---------------------+--------+--------------+--------------------------------------------------------------------------------+-----------------+---------+----------------+---------------+---------------------+---------------------+--------------------------+----------+------------+-------------------------+-----------+
5| PartitionId | PartitionName | VisibleVersion | VisibleVersionTime | State | PartitionKey | Range | DistributionKey | Buckets | ReplicationNum | StorageMedium | CooldownTime | RemoteStoragePolicy | LastConsistencyCheckTime | DataSize | IsInMemory | ReplicaAllocation | IsMutable |
6+-------------+-----------------+----------------+---------------------+--------+--------------+--------------------------------------------------------------------------------+-----------------+---------+----------------+---------------+---------------------+---------------------+--------------------------+----------+------------+-------------------------+-----------+
7| 180060 | p20080101000000 | 2 | 2023-09-18 21:49:29 | NORMAL | TRADE_DATE | [types: [DATEV2]; keys: [2008-01-01]; ..types: [DATEV2]; keys: [2009-01-01]; ) | TRADE_DATE | 10 | 1 | HDD | 9999-12-31 23:59:59 | | NULL | 0.000 | false | tag.location.default: 1 | true |
8| 180039 | p20120101000000 | 2 | 2023-09-18 21:49:29 | NORMAL | TRADE_DATE | [types: [DATEV2]; keys: [2012-01-01]; ..types: [DATEV2]; keys: [2013-01-01]; ) | TRADE_DATE | 10 | 1 | HDD | 9999-12-31 23:59:59 | | NULL | 0.000 | false | tag.location.default: 1 | true |
9| 180018 | p20140101000000 | 2 | 2023-09-18 21:49:29 | NORMAL | TRADE_DATE | [types: [DATEV2]; keys: [2014-01-01]; ..types: [DATEV2]; keys: [2015-01-01]; ) | TRADE_DATE | 10 | 1 | HDD | 9999-12-31 23:59:59 | | NULL | 0.000 | false | tag.location.default: 1 | true |
10+-------------+-----------------+----------------+---------------------+--------+--------------+--------------------------------------------------------------------------------+-----------------+---------+----------------+---------------+---------------------+---------------------+--------------------------+----------+------------+-------------------------+-----------+经过自动分区功能所创建的 PARTITION，与手动创建的 PARTITION 具有完全一致的功能性质。
与动态分区联用
PALO 支持自动分区和动态分区同时使用。此时，二者的功能都生效：
- 自动分区将会自动在数据导入过程中按需创建分区；
- 动态分区将会自动创建、回收、转储分区。
二者语法功能不存在冲突，同时设置对应的子句/属性即可。
最佳实践
需要对分区生命周期设限的场景，可以将 Dynamic Partition 的创建功能关闭，创建分区完全交由 Auto Partition 完成，通过 Dynamic Partition 动态回收分区的功能完成分区生命周期的管理：
SQL
1create table auto_dynamic(
2 k0 datetime(6) NOT NULL
3)
4auto partition by range (date_trunc(k0, 'year'))
5(
6)
7DISTRIBUTED BY HASH(`k0`) BUCKETS 2
8properties(
9 "dynamic_partition.enable" = "true",
10 "dynamic_partition.prefix" = "p",
11 "dynamic_partition.start" = "-50",
12 "dynamic_partition.end" = "0", --- Dynamic Partition 不创建分区
13 "dynamic_partition.time_unit" = "year",
14 "replication_num" = "1"
15);这样我们同时具有了 Auto Partition 的灵活性，且分区名上保持了一致性。
分区管理
当启用自动分区后，分区名可以通过 auto_partition_name 函数映射到分区。partitions 表函数可以通过分区名产生详细的分区信息。仍然以 DAILY_TRADE_VALUE 表为例，在我们插入数据后，查看其当前分区：
SQL
1select * from partitions("catalog"="internal","database"="optest","table"="DAILY_TRADE_VALUE") where PartitionName = auto_partition_name('range', 'year', '2008-02-03');
2+-------------+-----------------+----------------+---------------------+--------+--------------+--------------------------------------------------------------------------------+-----------------+---------+----------------+---------------+---------------------+---------------------+--------------------------+-----------+------------+-------------------------+-----------+--------------------+--------------+
3| PartitionId | PartitionName | VisibleVersion | VisibleVersionTime | State | PartitionKey | Range | DistributionKey | Buckets | ReplicationNum | StorageMedium | CooldownTime | RemoteStoragePolicy | LastConsistencyCheckTime | DataSize | IsInMemory | ReplicaAllocation | IsMutable | SyncWithBaseTables | UnsyncTables |
4+-------------+-----------------+----------------+---------------------+--------+--------------+--------------------------------------------------------------------------------+-----------------+---------+----------------+---------------+---------------------+---------------------+--------------------------+-----------+------------+-------------------------+-----------+--------------------+--------------+
5| 127095 | p20080101000000 | 2 | 2024-11-14 17:29:02 | NORMAL | TRADE_DATE | [types: [DATEV2]; keys: [2008-01-01]; ..types: [DATEV2]; keys: [2009-01-01]; ) | TRADE_DATE | 10 | 1 | HDD | 9999-12-31 23:59:59 | | \N | 985.000 B | 0 | tag.location.default: 1 | 1 | 1 | \N |
6+-------------+-----------------+----------------+---------------------+--------+--------------+--------------------------------------------------------------------------------+-----------------+---------+----------------+---------------+---------------------+---------------------+--------------------------+-----------+------------+-------------------------+-----------+--------------------+--------------+这样每个分区的 ID 和取值就可以精准地被筛选出，用于后续针对分区的具体操作（例如 insert overwrite partition）。
注意事项
- 如同普通分区表一样，AUTO LIST PARTITION 支持多列分区，语法并无区别。
- 在数据的插入或导入过程中如果创建了分区，而整个导入过程没有完成（失败或被取消），被创建的分区不会被自动删除。
- 使用 AUTO PARTITION 的表，只是分区创建方式上由手动转为了自动。表及其所创建分区的原本使用方法都与非 AUTO PARTITION 的表或分区相同。
- 为防止意外创建过多分区，我们通过FE 配置项中的max_auto_partition_num控制了一个 AUTO PARTITION 表最大容纳分区数。如有需要可以调整该值
- 向开启了 AUTO PARTITION 的表导入数据时，Coordinator 发送数据的轮询间隔与普通表有所不同。具体请见BE 配置项中的olap_table_sink_send_interval_auto_partition_factor。开启前移（enable_memtable_on_sink_node = true）后该变量不产生影响。
- 在使用insert-overwrite插入数据时 AUTO PARTITION 表的行为详见 INSERT OVERWRITE 文档。
- 如果导入创建分区时，该表涉及其他元数据操作（如 Schema Change、Rebalance），则导入可能失败。