1. 背景

我们在从一些数据源（比如关系型数据库）批量导入数据前，我们可能需批量创建出所需子表。TDengine 引擎从 v3.3.3.0 版本开始，提供了通过 CSV 文件批量创建子表的功能，使用者只要按约定的格式生成 CSV 文件，使用 CSV 批量建表语句，便可自动从 CSV 中轻松创建出海量子表。

2. SQL 命令

批量建表语句仍然使用 CREATE TABLE 语句实现，并扩展了新命令关键词，语法如下：

CREATE TABLE [IF NOT EXISTS] USING stb_name (field1_name [, field2_name] ...) FILE csv_file_path;

1. if not exists：

   1. 如不指定，如果尝试建立已经存在的表会导致该命令报错并退出

   2. 若指定，如果尝试建立已经存在的表将忽略错误并继续执行

   3. 默认不指定

2. stb_name：引用的超级表名称

   1. 依据该超级表的 schema 创建子表

   2. 该超级表必须已经建立

3. field_name：表名和一个或多个标签名的列表

   1. 列表顺序与 CSV 文件各列内容顺序一致

   2. 列表中 不允许存在重复项，否则报错并退出

   3. 列表中 必须包含 tbname，否则报错并退出

   4. 列表中可包含零个或多个标签列，但必须是所引用的超级表中已经存在的标签列

   5. 未包含在该列表中的标签，其值将被设置为 NULL

4. csv_file_path：csv 文件路径

3. CSV 文件格式

1. CSV 文件中每行必须包含与 SQL 语名中的字段列表中所指定的数量相同的列，由 ',' 分隔，如果列数不匹配则报错退出

2. CSV 文件中的注释行会被自动忽略，不做处理

3. CSV 文件各字段的值与所对应的标签的类型必须匹配，否则报错并退出。

   1. 字符串类型值 需使用 单引号 ' 或 双引号 " 引用

   2. 布尔类型值 可匹配 0/1、true/false、以及 ‘true’/'false' 等常见值

4. CSV 文件中对应 tbname 的值必须符合 TDengine 表名命名规则

4. 使用场景

4.1 三种组合八个场景

场景	数据行含 普通列	数据行含 子表名列	数据行含 标签列	说明	状态
场景一	是	是	是	导入时序数据 通过 SQL 语句指定超级表名 如果子表存在，不更新标签值 如果子表不存在，创建子表，标签值取子表的第一行数据	INSERT INTO tablename file ... 已支持
场景二	是	是	否	导入时序数据 通过 SQL 语句指定超级表名 如果子表存在，不更新标签值 如果子表不存在，创建子表，标签值设置为 NULL	INSERT INTO tablename file ... 已支持
场景三	是	否	是	-	不支持
场景四	是	否	否	导入时序数据 通过 SQL 语句指定子表名 如果子表存在，不更新标签值 如果子表不存在，创建子表，标签值设置为 NULL	INSERT INTO tablename file ... 已支持
场景五	否	是	是	不导入时序数据，仅建表 通过 SQL 语句指定超级表名 如果子表存在，不做任何处理 如果子表不存在，创建子表，标签值取子表的第一行数据	本功能支持
场景六	否	是	否	不导入时序数据，仅建表 通过 SQL 语句指定超级表名 如果子表存在，不做任何处理 如果子表不存在，创建子表，标签值设置为 NULL	本功能支持
场景七	否	否	是	-	不支持
场景八	否	否	否	-	-

4.2 场景示例

示例超级表结构如下：

CREATE TABLE meters (ts timestamp, current float, voltage int, phase float) TAGS (location varchar(64), groupId int);

场景一：

CSV 数据：

导入命令：

INSERT INTO meters (ts, current, voltage, phase, location, groupId, tbname) FILE 'auto1.csv';

场景二：

CSV 数据：

导入命令：

INSERT INTO meters (ts, current, voltage, phase, tbname) FILE 'auto2.csv';

场景三（不支持）

场景四：

CSV 数据：

导入命令：

INSERT INTO d1001 (ts, current, voltage, phase) FILE 'auto4.csv';

场景五：

CSV 数据：

导入命令：

CREATE TABLE USING meters (location, groupId, tbname)  FILE 'auto5.csv';

场景六：

CSV 数据：

导入命令：

CREATE TABLE USING meters (tbname)  FILE 'auto6.csv';

5. 约束和限制

配置文件中的maxInsertBatchRows ，可控制每批次从 csv 文件中解析的行数，同时影响本功能向 server 端发送的数据包的大小。

若导入过程中遭遇 DB error: Invalid message len，需减小该参数大小。

名称	功能	默认值	参考值
maxInsertBatchRows	每批次从 csv 文件中解析的行数	1 000 000	maxInsertBatchRows * 平均行数据量 / nVgroup < 1M