DDL语法说明

创建表

当使用Paimon catalog后，用户可以创建Paimon表。在Paimon Catalog中创建的表由Catalog管理，当表从Catalog中删除时，其表文件也会被删除。

CREATE TABLE my_table (
    user_id BIGINT,
    item_id BIGINT,
    behavior STRING,
    dt STRING,
    hh STRING
)
PARTITIONED BY (dt, hh)
TBLPROPERTIES (
    'primary-key' = 'dt,hh,user_id',
    'bucket' = '2'
)
LOCATION 'obs://{bucket}/path/to/table';

• PARTITIONED BY：分区配置。
• LOCATION '(fully-qualified-uri)'：设置表位置。指定LOCATION时创建的是外部表，删除时仅移除元数据，不删除数据文件。如果指定位置已存在数据，可以不指定字段、分区和属性，新表将从已有表的元数据中继承所有信息。
• bucket：分桶配置。分桶（Bucket）是Paimon表读写操作的最小单元。非分区表的所有数据以及分区表每个分区的数据，都会被进一步划分到不同的分桶中，以便多个并发同时进行读写，提高数据读写性能。用户可以通过bucket-key指定分桶列，如果未指定则使用主键作为Bucket Key。
• COMMENT 'table documentation'：设置表描述。
• TBLPROPERTIES ('key'='value', ...)：设置表配置。
• primary-key：主键字段。
  • 创建表时指定主键（Primary Key），则创建的表为主键表；主键由列组成，且主键值须唯一。主键表支持insert、update、delete操作。在存储桶内Paimon数据按主键排序后保存，过滤查询主键时查询性能高。主键表使用LSM树结构存储数据，支持高效读写。
  • 创建表时没有指定主键（Primary Key），则创建的为Paimon Append Only表。与主键表相比，Append Only表仅支持INSERT操作，不能产生changelog变更日志，只能追加数据，适合不需要流式更新的场景。

CTAS语法

Paimon支持将 CTAS（CREATE TABLE ... AS SELECT）作为原子操作执行。

通过CTAS操作生成的新表，不会继承SELECT语句所指定的源表中集成分区规范和表属性。如果需要为该新建表配置分区规范或表属性，可在CTAS语句中通过PARTITIONED BY 子句明确声明分区规范，通过TBLPROPERTIES子句自定义表属性。

-- 基本CTAS
CREATE TABLE my_table_as USING paimon AS SELECT * FROM my_table;  
-- 指定分区和主键
CREATE TABLE my_table_all_as USING paimon PARTITIONED BY (dt) TBLPROPERTIES ('primary-key' = 'dt,hh') AS SELECT * FROM my_table_all; 

注意事项

对于Append表（无主键表），如果指定了bucket属性，必须同时指定bucket-key属性。

RTAS语法

Paimon支持将 RTAS（REPLACE TABLE ... AS SELECT）作为原子操作执行。原子性表替换会基于 SELECT 查询的结果创建新快照，同时保留表的历史记录。

--基本RTAS
REPLACE TABLE paimon.db.sample USING paimon AS SELECT ...;  
CREATE OR REPLACE TABLE paimon.db.sample USING paimon AS SELECT ...;
-- 指定分区和分桶
REPLACE TABLE paimon.db.sample  USING paimon  PARTITIONED BY (pt)  TBLPROPERTIES ('bucket' = '2', 'bucket-key' = 'id')  AS SELECT ...;  

删除表

DROP TABLE my_table;

• 管理表（MANAGED）：删除元数据和OBS数据。
• 外部表（EXTERNAL）：仅删除元数据，不删除OBS数据。

ALTER TABLE

Paimon支持以下ALTER TABLE操作：

设置/移除表属性

ALTER TABLE my_table SET TBLPROPERTIES ('write-buffer-size' = '256 MB'); ALTER TABLE my_table UNSET TBLPROPERTIES ('write-buffer-size'); 

设置/移除表注释

ALTER TABLE my_table SET TBLPROPERTIES ('comment' = 'table comment'); ALTER TABLE my_table UNSET TBLPROPERTIES ('comment'); 

重命名表

ALTER TABLE my_table RENAME TO my_table_new; 

注意：使用对象存储（如OBS）时请谨慎使用此语法，因为对象存储的重命名操作不是原子的。

新增列

ALTER TABLE my_table ADD COLUMNS (c1 INT, c2 STRING);  
-- 新增嵌套列到struct类型
ALTER TABLE my_table ADD COLUMN v.f3 STRING;  
-- 新增嵌套列到array的struct元素
ALTER TABLE my_table ADD COLUMN v.element.f3 STRING;  
-- 新增嵌套列到map的value struct
ALTER TABLE my_table ADD COLUMN v.value.f3 STRING; 

指定列位置

ALTER TABLE my_table ADD COLUMN c INT FIRST; ALTER TABLE my_table ADD COLUMN c INT AFTER b; 

重命名列

ALTER TABLE my_table RENAME COLUMN c0 TO c1;  
-- 重命名嵌套列
ALTER TABLE my_table RENAME COLUMN v.f1 to f100; 
ALTER TABLE my_table RENAME COLUMN v.element.f1 to f100; 
ALTER TABLE my_table RENAME COLUMN v.value.f1 to f100; 

删除列

ALTER TABLE my_table DROP COLUMNS (c1, c2);  
-- 删除嵌套列
ALTER TABLE my_table DROP COLUMN v.f2; 
ALTER TABLE my_table DROP COLUMN v.element.f2;
ALTER TABLE my_table DROP COLUMN v.value.f2; 

删除分区

ALTER TABLE my_table DROP PARTITION (`id` = 1, `name` = 'paimon'); 

修改列注释

ALTER TABLE my_table ALTER COLUMN buy_count COMMENT 'buy count'; 

修改列位置

ALTER TABLE my_table ALTER COLUMN col_a FIRST; ALTER TABLE my_table ALTER COLUMN col_a AFTER col_b; 

修改列类型（widening）

ALTER TABLE my_table ALTER COLUMN col_a TYPE DOUBLE;  
-- 修改嵌套列类型
ALTER TABLE my_table ALTER COLUMN v.f2 TYPE BIGINT; 
ALTER TABLE my_table ALTER COLUMN v.element.f2 TYPE BIGINT; 
ALTER TABLE my_table ALTER COLUMN v.value.f2 TYPE BIGINT; 

Tag管理

创建Tag

-- 基于最新快照创建Tag
ALTER TABLE T CREATE TAG `TAG-1`;  
-- 如果不存在则创建
ALTER TABLE T CREATE TAG IF NOT EXISTS `TAG-1`;  
-- 创建并保留7天
ALTER TABLE T CREATE TAG `TAG-2` RETAIN 7 DAYS;  
-- 基于指定快照创建
ALTER TABLE T CREATE TAG `TAG-3` AS OF VERSION 1;  
-- 创建或替换
ALTER TABLE T CREATE OR REPLACE TAG `TAG-5` AS OF VERSION 2 RETAIN 24 HOURS; 

删除Tag

ALTER TABLE T DELETE TAG `TAG-1`; 
ALTER TABLE T DELETE TAG IF EXISTS `TAG-1`; 
ALTER TABLE T DELETE TAG `TAG-1,TAG-2`; 

重命名Tag

ALTER TABLE T RENAME TAG `TAG-1` TO `TAG-2`; 

查看Tag

SHOW TAGS T;