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