# CREATE TABLE
#### 概述
CREATE TABLE语句用于在当前或指定Catalog中注册表，定义表的结构（物理列、计算列、元数据列）、时间属性（Watermark）、约束（主键）和连接器配置（WITH子句）。注册后的表可在SQL查询中作为源表或结果表使用。AI DataLake支持Flink SQL标准建表语法，涵盖分区表、LIKE建表等核心能力。
#### 适用场景
- **数据接入**：通过CREATE TABLE定义外部数据源（如Kafka、HDFS）的映射表，实现数据读取与写入。
- **流式ETL**：定义带Watermark和计算列的源表，配合窗口函数完成实时数据转换。
- **分区管理**：使用PARTITIONED BY创建分区表，优化大数据量场景下的查询性能。
- **表结构复用**：通过LIKE子句基于已有表快速创建新表，减少重复定义。
 
#### 约束与限制
- AI DataLake不支持CREATE TEMPORARY TABLE语法，所有表均为持久化表。
- 主键约束声明为NOT ENFORCED，Flink不会校验数据唯一性，需依赖外部存储保证。
- 一个表只能定义一个Watermark，即只能声明一个事件时间字段。
- PARTITIONED BY仅支持在连接器支持分区的场景下使用（如Hive、Paimon等），Kafka等连接器不支持分区表。
- 计算列不能引用其他计算列，只能引用物理列和元数据列。
- 元数据列的可用性取决于连接器实现，不同连接器支持的元数据不同。
- LIKE子句的INCLUDING/EXCLUDING选项需与源表结构匹配，错误的组合会导致建表失败。
 
#### 语法结构
**完整语法**
```
CREATE TABLE [IF NOT EXISTS] [catalog_name.][db_name.]table_name (
  { <physical_column_definition> | <metadata_column_definition> | <computed_column_definition> }
  [ , ...n]
  [ <watermark_definition> ]
  [ <table_constraint> ]
  [ , ...n]
)
[COMMENT table_comment]
[PARTITIONED BY (partition_column_name1, partition_column_name2, ...)]
WITH (key1=val1, key2=val2, ...)
[ LIKE source_table [( <like_options> )] ]
```
**列定义语法**
```
-- 物理列
<physical_column_definition>:
  column_name column_type [ <column_constraint> ] [COMMENT column_comment]
<column_constraint>:
  [CONSTRAINT constraint_name] PRIMARY KEY NOT ENFORCED
-- 元数据列
<metadata_column_definition>:
  column_name column_type METADATA [ FROM metadata_key ] [ VIRTUAL ]
-- 计算列
<computed_column_definition>:
  column_name AS computed_column_expression [COMMENT column_comment]
```
**Watermark定义语法**
```
<watermark_definition>:
  WATERMARK FOR rowtime_column_name AS watermark_strategy_expression
```
**主键约束语法**
```
<table_constraint>:
  [CONSTRAINT constraint_name] PRIMARY KEY (column_name, ...) NOT ENFORCED
```
**LIKE选项语法**
```
<like_options>:
  {
    { INCLUDING | EXCLUDING } { ALL | CONSTRAINTS | PARTITIONS }
  | { INCLUDING | EXCLUDING | OVERWRITING } { GENERATED | OPTIONS | WATERMARKS }
  }[, ...]
```
#### 参数说明
**主句参数**
| 参数                       | 必填 | 说明                                                                     |
|:---|:---|:---|
| IF NOT EXISTS        | 否    | 指定当同名表已存在时不报错，直接跳过创建。未指定时若同名表存在则抛出异常。                               |
| catalog_name.db_name | 否 | 指定表所在的Catalog和数据库名。未指定时使用当前Catalog和数据库。                               |
| table_name              | 是  | 表名，在同一数据库内必须唯一。                                                        |
| COMMENT table_comment  | 否   | 为表添加注释说明。                                                           |
| PARTITIONED BY        | 否   | 指定分区列，将表按分区列值存储到不同目录。仅连接器支持分区时有效，分区列必须是表中已定义的物理列。                     |
| WITH (key1=val1, ...)  | 是   | 指定表的连接器配置项，以键值对形式提供。connector参数为必填项，决定数据来源或去向。                        |
| LIKE source_table       | 否    | 基于已有表的结构创建新表，支持INCLUDING/EXCLUDING/OVERWRITING控制结构继承策略。可复用表结构而避免重复定义。 |
   
**列类型参数**
| 列类型  | 关键字     | 说明                                                                                   |
|:---|:---|:---|
| 物理列 | 无特殊关键字  | 定义物理介质中存储数据的字段，是最常用的列定义方式。物理列的顺序与数据源中的字段顺序对应。                                         |
| 计算列  | AS       | 通过表达式生成的虚拟列，不物理存储在表中。常用于定义Processing Time（AS PROCTIME()）或派生字段。只能引用物理列和元数据列，不能引用其他计算列。 |
| 元数据列 | METADATA | 访问连接器数据源的元数据信息，如Kafka的timestamp、offset等。VIRTUAL标记表示该元数据仅读取不持久化。可用性取决于连接器实现。        |
   
**Watermark参数**
| 参数                            | 必填 | 说明                                                                                  |
|:---|:---|:---|
| rowtime_column_name         | 是   | 指定事件时间列，必须为TIMESTAMP(3)或TIMESTAMP_LTZ(3)类型。一个表只能定义一个Watermark。                     |
| watermark_strategy_expression | 是  | 水位线生成策略表达式，用于计算Watermark的时间戳。常用策略为rowtime_column - INTERVAL 'n' SECOND，表示允许最大n秒的乱序。 |
   
**主键约束参数**
| 参数               | 必填 | 说明                                                       |
|:---|:---|:---|
| constraint_name | 否 | 约束名称，可选。                                                 |
| column_name, ...  | 是    | 主键包含的一个或多个列，这些列不允许为NULL。                                   |
| NOT ENFORCED     | 是 | Flink不强制校验主键唯一性，需依赖外部存储保证。此关键字为必填，不可省略。主键用于upsert连接器的语义判断。 |
   
**LIKE选项参数**
| 选项          | 可选策略                                | 说明                                                                                                |
|:---|:---|:---|
| ALL            | INCLUDING / EXCLUDING                | 控制是否包含源表的所有特性。INCLUDING ALL表示全部继承，EXCLUDING ALL表示全部排除。                                          |
| CONSTRAINTS | INCLUDING / EXCLUDING                | 控制是否包含主键等约束。INCLUDING CONSTRAINTS继承约束，EXCLUDING CONSTRAINTS不继承。                                   |
| PARTITIONS     | INCLUDING / EXCLUDING                | 控制是否包含分区信息。INCLUDING PARTITIONS继承分区定义，EXCLUDING PARTITIONS不继承。                                    |
| GENERATED    | INCLUDING / EXCLUDING / OVERWRITING  | 控制计算列和元数据列的继承。INCLUDING继承，EXCLUDING排除，OVERWRITING用新定义覆盖源表计算列。                                    |
| OPTIONS      | INCLUDING / EXCLUDING / OVERWRITING | 控制WITH选项的继承。INCLUDING OPTIONS继承所有连接器配置，EXCLUDING OPTIONS不继承，OVERWRITING OPTIONS用新配置覆盖同名项。       |
| WATERMARKS     | INCLUDING / EXCLUDING / OVERWRITING | 控制Watermark定义的继承。INCLUDING WATERMARKS继承水位线，EXCLUDING WATERMARKS不继承，OVERWRITING WATERMARKS用新定义覆盖。 |
   
#### 使用示例
AI DataLake支持多种连接器，各连接器具有特定的使用示例，详情请参见[连接器的支持情况](https://support.huaweicloud.com/sqlref-flink-aidatalake/aidatalake_11_0002.html)查看各连接器文档中的使用示例。
