表管理

在表模型中，推荐一张表对应一类设备，用于管理该类设备的时序数据。同类设备通常具有相同或相近的测点集合，例如同一类风机、车辆、生产设备或监控对象。

1. 基础概念

1.1 表

表通常用于承载同一类设备的时序数据。建模时可以将设备的标识信息设计为 TAG 列，将设备的静态描述设计为 ATTRIBUTE 列，将随时间变化的采集值设计为 FIELD 列。

1.2 时间列、标签列、属性列和测点列

表模型中的表结构通常如上图所示，其中的列按照用途可分为以下几类：

概念	说明
时间列（TIME）	每张表必须包含一个时间列，数据类型为 TIMESTAMP，用于记录数据点对应的时间。
标签列（TAG）	用于标识设备，可作为设备的联合主键，通常存放区域、场站、设备编号等用于定位设备的信息。标签列的值通常不随时间变化。
属性列（ATTRIBUTE）	用于描述设备的静态属性，例如型号、厂商、维护信息等。属性列不随时间变化，可新增或更新。
测点列（FIELD）	用于存储设备采集的物理量或指标，值随时间变化，例如温度、湿度、电流、电压、状态等。

在查询筛选效率上，通常可理解为：时间列和标签列优先，其次是属性列，最后是测点列。

1.3 设备与测点

在表模型中，一个设备由一张表内全部 TAG 列的取值组合唯一标识。例如表中包含 region、plant_id、device_id 三个 TAG 列，则 region + plant_id + device_id 的每一种唯一组合表示一个独立设备。

测点对应表中的 FIELD 列。一个设备的一列 FIELD 会随着时间产生多个数据点，这些按时间排列的数据点构成一条时间序列。

因此，表模型下单表测点数可按以下公式理解：单表测点数 = device 数量 x FIELD 列数量。

1.4 表级 TTL

表的 TTL 默认为其所在数据库的 TTL。如果表单独设置了 TTL，则以表级 TTL 为准。合理使用表级 TTL 可以对不同业务表设置不同的数据保留周期。

关于 TTL 更详细的功能介绍可查阅：数据保留时间

如需进一步了解 IoTDB 树表孪生模型、模型选择方式及典型建模方案，可参考建模方案设计。

2. 表管理

2.1 创建表

Create 语句用于在当前数据库中创建表，也可以对任何指定数据库创建表，格式为“数据库名.表名”。

语法：

createTableStatement
    : CREATE TABLE (IF NOT EXISTS)? qualifiedName
        '(' (columnDefinition (',' columnDefinition)*)? ')'
        charsetDesc?
        comment?
        (WITH properties)?
     ;

charsetDesc
    : DEFAULT? (CHAR SET | CHARSET | CHARACTER SET) EQ? identifierOrString
    ;

columnDefinition
    : identifier columnCategory=(TAG | ATTRIBUTE | TIME) charsetName? comment?
    | identifier type (columnCategory=(TAG | ATTRIBUTE | TIME | FIELD))? charsetName? comment?
    ;

charsetName
    : CHAR SET identifier
    | CHARSET identifier
    | CHARACTER SET identifier
    ;

comment
    : COMMENT string
    ;

说明：

在创建表时，可以不指定时间列（TIME），IoTDB会自动添加该列并命名为“time”，且顺序上位于第一列。其他所有列可以通过在数据库配置时启用enable_auto_create_schema选项，或通过 session 接口自动创建或修改表的语句来添加。
自 V2.0.8 版本起，支持创建表时自定义命名时间列，自定义时间列在表中的顺序由创建 SQL 中的顺序决定。相关约束如下：

当列分类（columnCategory）设为 TIME 时，数据类型（dataType）必须为 TIMESTAMP。
每张表最多允许定义 1个时间列（columnCategory = TIME）。
当未显式定义时间列时，不允许其他列使用 time 作为名称，否则会与系统默认时间列命名冲突。

列的类别可以省略，默认为FIELD。当列的类别为TAG或ATTRIBUTE时，数据类型需为STRING（可省略）。
表的TTL默认为其所在数据库的TTL。如果使用默认值，可以省略此属性，或将其设置为default。
<TABLE_NAME>表名称，具有以下特性：
- 大小写不敏感，创建成功后，统一显示为小写
- 名称可包含特殊字符，如 ~!"%` 等
- 包含特殊字符或中文字符的表名创建时必须用双引号 "" 括起来。
  - 注意：SQL中特殊字符或中文表名需加双引号。原生API中无需额外添加，否则表名会包含引号字符。
- 当为表命名时，最外层的双引号（""）不会在实际创建的表名中出现。
- ```
 -- SQL 中
 "a""b" --> a"b
 """""" --> ""
 -- API 中
 "a""b" --> "a""b"
```
columnDefinition 列名称与表名称具有相同特性，并且可包含特殊字符.。
COMMENT 给表添加注释。

示例:

CREATE TABLE table1 (
  time TIMESTAMP TIME,
  region STRING TAG,
  plant_id STRING TAG,
  device_id STRING TAG,
  model_id STRING ATTRIBUTE,
  maintenance STRING ATTRIBUTE COMMENT 'maintenance',
  temperature FLOAT FIELD COMMENT 'temperature',
  humidity FLOAT FIELD COMMENT 'humidity',
  status Boolean FIELD COMMENT 'status',
  arrival_time TIMESTAMP FIELD COMMENT 'arrival_time'
) COMMENT 'table1' WITH (TTL=31536000000);

注意：若您使用的终端不支持多行粘贴（例如 Windows CMD），请将 SQL 语句调整为单行格式后再执行。

2.2 查看表

用于查看该数据库中或指定数据库中的所有表和表库的属性信息。

语法：

SHOW TABLES (DETAILS)? ((FROM | IN) database_name)?

说明：

在查询中指定了FROM或IN子句时，系统将展示指定数据库内的所有表。
如果未指定FROM或IN子句，系统将展示当前选定数据库中的所有表。如果用户未使用（use）某个数据库空间，系统将报错。
请求显示详细信息（指定DETAILS），系统将展示表的当前状态，包括：
- USING：表示表处于正常可用状态。
- PRE_CREATE：表示表正在创建中或创建失败，此时表不可用。
- PRE_DELETE：表示表正在删除中或删除失败，此类表将永久不可用。

示例:

SHOW TABLES DETAILS FROM database1;

+---------------+-----------+------+-------+
|      TableName|    TTL(ms)|Status|Comment|
+---------------+-----------+------+-------+
|         table1|31536000000| USING| table1|
+---------------+-----------+------+-------+

2.3 查看表的列

用于查看表的列名、数据类型、类别、状态。

语法：

(DESC | DESCRIBE) <TABLE_NAME> (DETAILS)?

说明：

如果设置了DETAILS选项，系统将展示列的详细状态信息，包括：
- USING：表示列目前处于正常使用状态。
- PRE_DELETE：表示列正在被删除或删除操作失败，该列将永久无法使用。

示例:

DESC table1 DETAILS;

+------------+---------+---------+------+------------+
|  ColumnName| DataType| Category|Status|     Comment|
+------------+---------+---------+------+------------+
|        time|TIMESTAMP|     TIME| USING|        null|
|      region|   STRING|      TAG| USING|        null|
|    plant_id|   STRING|      TAG| USING|        null|
|   device_id|   STRING|      TAG| USING|        null|
|    model_id|   STRING|ATTRIBUTE| USING|        null|
| maintenance|   STRING|ATTRIBUTE| USING| maintenance|
| temperature|    FLOAT|    FIELD| USING| temperature|
|    humidity|    FLOAT|    FIELD| USING|    humidity|
|      status|  BOOLEAN|    FIELD| USING|      status|
|arrival_time|TIMESTAMP|    FIELD| USING|arrival_time|
+------------+---------+---------+------+------------+

2.4 查看表的创建信息

用于获取表模型下表或视图的完整定义语句。该功能会自动补全创建时省略的所有默认值，因此结果集中所展示的语句可能与原始创建语句不同。

V2.0.5 起支持该功能

语法：

SHOW CREATE TABLE <TABLE_NAME>

说明：

该语句不支持对系统表的查询

示例:

SHOW CREATE TABLE table1;

+------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Table|                                                                                                                                                                                                                                                                     Create Table|
+------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|table1|CREATE TABLE "table1" ("region" STRING TAG,"plant_id" STRING TAG,"device_id" STRING TAG,"model_id" STRING ATTRIBUTE,"maintenance" STRING ATTRIBUTE,"temperature" FLOAT FIELD,"humidity" FLOAT FIELD,"status" BOOLEAN FIELD,"arrival_time" TIMESTAMP FIELD) WITH (ttl=31536000000)|
+------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

2.5 修改表

用于修改表，包括添加列、删除列以及设置表的属性。

语法：

#addColumn;
ALTER TABLE (IF EXISTS)? tableName=qualifiedName ADD COLUMN (IF NOT EXISTS)? column=columnDefinition COMMENT 'column_comment';
#dropColumn;
ALTER TABLE (IF EXISTS)? tableName=qualifiedName DROP COLUMN (IF EXISTS)? column=identifier; 
#setTableProperties;                  
// set TTL can use this;
ALTER TABLE (IF EXISTS)? tableName=qualifiedName SET PROPERTIES propertyAssignments;  
              
COMMENT ON TABLE tableName=qualifiedName IS 'table_comment';
COMMENT ON COLUMN tableName.column IS 'column_comment';

说明：

SET PROPERTIES操作目前仅支持对表的 TTL 属性进行配置。
删除列功能，仅支持删除属性列(ATTRIBUTE)和物理量列(FIELD)，标识列(TAG)不支持删除。
修改后的 comment 会覆盖原有注释，如果指定为 null，则会擦除之前的 comment。

示例:

表 table1 增加 tag 列 a

ALTER TABLE table1 ADD COLUMN IF NOT EXISTS a TAG COMMENT 'a';

表 table1 增加 field 列 b

ALTER TABLE table1 ADD COLUMN IF NOT EXISTS b FLOAT FIELD COMMENT 'b';

修改表 table1 的 TTL

ALTER TABLE table1 set properties TTL=3600;

表 table1 增加注释

COMMENT ON TABLE table1 IS 'table1';

表 table1 的 a 列去掉注释

COMMENT ON COLUMN table1.a IS null;

2.6 删除表

用于删除表。

语法：

DROP TABLE (IF EXISTS)? <TABLE_NAME>;

示例:

DROP TABLE table1;