数据导入
1. 功能概述
IoTDB 支持三种方式进行数据导入：
- 数据导入工具 ：
import-data.sh/bat位于tools目录下，可以将CSV、SQL、及TsFile（开源时序文件格式）的数据导入IoTDB。 TsFile自动加载功能。Load SQL导入TsFile。
- 表模型 TsFile 导入暂时只支持本地导入。
2. 数据导入工具
2.1 公共参数
| 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 |
|---|---|---|---|---|
| -ft | --file_type | 导入文件的类型，可以选择：csv、sql、tsfile | √ | |
| -h | -- host | 主机名 | 否 | 127.0.0.1 |
| -p | --port | 端口号 | 否 | 6667 |
| -u | --username | 用户名 | 否 | root |
| -pw | --password | 密码 | 否 | TimechoDB@2021 (V2.0.6 版本之前为 root) |
| -s | --source | 待加载的脚本文件(夹)的本地目录路径 如果为 csv sql tsfile 这三个支持的格式，直接导入 不支持的格式，报错提示 The file name must end with "csv" or "sql"or "tsfile"! | √ | |
| -sql_dialect | --sql_dialect | 选择 server 是树模型还是表模型，当前支持 tree 和 table 类型 | 否 | tree |
| -db | --database | 数据将要导入的目标库，只在 -sql_dialect 为 table 类型下生效。 | -sql_dialect 为 table 时必填 | - |
| -table | --table | 数据将要导入的目标表，只在 -sql_dialect 为 table 类型且文件类型为 csv 条件下生效且必填。 | 否 | - |
| -tn | --thread_num | 最大并行线程数 | 否 | 8 范围：0～Integer.Max=2147483647 |
| -tz | --timezone | 时区设置，例如+08:00或-01:00 | 否 | 本机系统时间 |
| -help | --help | 显示帮助信息,支持分开展示和全部展示-help或-help csv | 否 |
2.2 CSV 格式
2.2.1 运行命令
# Unix/OS X > tools/import-data.sh -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table> [-h <host>] [-p <port>] [-u <username>] [-pw <password>] -s <source> [-fd <fail_dir>] [-lpf <lines_per_failed_file>] [-aligned <use the aligned interface>] [-ti <type_infer>] [-tp <timestamp precision (ms/us/ns)>] [-tz <timezone>] [-batch <batch_size>] [-tn <thread_num>] # Windows # V2.0.4.x 版本之前 > tools\import-data.bat -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table> [-h <host>] [-p <port>] [-u <username>] [-pw <password>] -s <source> [-fd <fail_dir>] [-lpf <lines_per_failed_file>] [-aligned <use the aligned interface>] [-ti <type_infer>] [-tp <timestamp precision (ms/us/ns)>] [-tz <timezone>] [-batch <batch_size>] [-tn <thread_num>] # V2.0.4.x 版本及之后 > tools\windows\import-data.bat -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table> [-h <host>] [-p <port>] [-u <username>] [-pw <password>] -s <source> [-fd <fail_dir>] [-lpf <lines_per_failed_file>] [-aligned <use the aligned interface>] [-ti <type_infer>] [-tp <timestamp precision (ms/us/ns)>] [-tz <timezone>] [-batch <batch_size>] [-tn <thread_num>]
2.2.2 私有参数
| 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 |
|---|---|---|---|---|
| -fd | --fail_dir | 指定保存失败文件的目录 | 否 | YOUR_CSV_FILE_PATH |
| -lpf | --lines_per_failed_file | 指定失败文件最大写入数据的行数 | 否 | 100000 范围：0～Integer.Max=2147483647 |
| -aligned | --use_aligned | 是否导入为对齐序列 | 否 | false |
| -batch | --batch_size | 指定每调用一次接口处理的数据行数（最小值为1，最大值为Integer.MAX_VALUE） | 否 | 100000 范围：0～Integer.Max=2147483647 |
| -ti | --type_infer | 通过选项定义类型信息，例如"boolean=text,int=long, ..." | 否 | 无 |
| -tp | --timestamp_precision | 时间戳精度 | 否： 1. ms（毫秒） 2. us（微秒） 3. ns（纳秒） | ms |
|
2.2.3 运行示例
# 正确示例 > tools/import-data.sh -ft csv -sql_dialect table -s ./csv/dump0_0.csv -db database1 -table table1 # 异常示例 > tools/import-data.sh -ft csv -sql_dialect table -s ./csv/dump0_1.csv -table table1 Parse error: Missing required option: db > tools/import-data.sh -ft csv -sql_dialect table -s ./csv/dump0_1.csv -db database1 -table table5 There are no tables or the target table table5 does not exist
2.2.4 导入说明
- CSV 导入规范
- 特殊字符转义规则：若Text类型的字段中包含特殊字符（例如逗号
,），需使用反斜杠（\）进行转义处理。 - 支持的时间格式：
yyyy-MM-dd'T'HH:mm:ss，yyy-MM-dd HH:mm:ss， 或者yyyy-MM-dd'T'HH:mm:ss.SSSZ。 - 时间戳列必须作为数据文件的首列存在。
- CSV 文件示例
time,region,device,model,temperature,humidity 1970-01-01T08:00:00.001+08:00,"上海","101","F",90.0,35.2 1970-01-01T08:00:00.002+08:00,"上海","101","F",90.0,34.8
2.3 SQL 格式
2.3.1 运行命令
# Unix/OS X > tools/import-data.sh -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table> [-h <host>] [-p <port>] [-u <username>] [-pw <password>] -s<source> [-fd <fail_dir>] [-lpf <lines_per_failed_file>] [-tz <timezone>] [-batch <batch_size>] [-tn <thread_num>] # Windows # V2.0.4.x 版本之前 > tools\import-data.bat -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table> [-h <host>] [-p <port>] [-u <username>] [-pw <password>] -s<source> [-fd <fail_dir>] [-lpf <lines_per_failed_file>] [-tz <timezone>] [-batch <batch_size>] [-tn <thread_num>] # V2.0.4.x 版本及之后 > tools\windows\import-data.bat -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table> [-h <host>] [-p <port>] [-u <username>] [-pw <password>] -s<source> [-fd <fail_dir>] [-lpf <lines_per_failed_file>] [-tz <timezone>] [-batch <batch_size>] [-tn <thread_num>]
2.3.2 私有参数
| 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 |
|---|---|---|---|---|
| -fd | --fail_dir | 指定保存失败文件的目录 | 否 | YOUR_CSV_FILE_PATH |
| -lpf | --lines_per_failed_file | 指定失败文件最大写入数据的行数 | 否 | 100000 范围：0～Integer.Max=2147483647 |
| -batch | --batch_size | 指定每调用一次接口处理的数据行数（最小值为1，最大值为Integer.MAX_VALUE） | 否 | 100000 范围：0～Integer.Max=2147483647 |
2.3.3 运行示例
# 正确示例 > tools/import-data.sh -ft sql -sql_dialect table -s ./sql/dump0_0.sql -db database1 # 异常示例 > tools/import-data.sh -ft sql -sql_dialect table -s ./sql/dump1_1.sql -db database1 Source file or directory ./sql/dump1_1.sql does not exist # 目标表存在但是元数据不适配/数据异常：生成.failed异常文件记录该条信息，日志打印错误信息如下 Fail to insert measurements '[column.name]' caused by [data type is not consistent, input '[column.value]', registered '[column.DataType]']
2.4 TsFile 格式
2.4.1 运行命令
# Unix/OS X > tools/import-data.sh -ft <format> [-sql_dialect<sql_dialect>] -db<database> -table<table> [-h <host>] [-p <port>] [-u <username>] [-pw <password>] -s <source> -os <on_success> [-sd <success_dir>] -of <on_fail> [-fd <fail_dir>] [-tn <thread_num> ] [-tz <timezone>] [-tp <timestamp precision (ms/us/ns)>] # Windows # V2.0.4.x 版本之前 > tools\import-data.bat -ft <format> [-sql_dialect<sql_dialect>] -db<database> -table<table> [-h <host>] [-p <port>] [-u <username>] [-pw <password>] -s <source> -os <on_success> [-sd <success_dir>] -of <on_fail> [-fd <fail_dir>] [-tn <thread_num> ] [-tz <timezone>] [-tp <timestamp precision (ms/us/ns)>] # V2.0.4.x 版本及之后 > tools\windows\import-data.bat -ft <format> [-sql_dialect<sql_dialect>] -db<database> -table<table> [-h <host>] [-p <port>] [-u <username>] [-pw <password>] -s <source> -os <on_success> [-sd <success_dir>] -of <on_fail> [-fd <fail_dir>] [-tn <thread_num> ] [-tz <timezone>] [-tp <timestamp precision (ms/us/ns)>]
2.4.2 私有参数
| 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 |
|---|---|---|---|---|
| -os | --on_succcess | 1. none：不删除 2. mv：移动成功的文件到目标文件夹 3. cp：硬连接（拷贝）成功的文件到目标文件夹 4. delete：删除 | √ | |
| -sd | --success_dir | 当--on_succcess为 mv 或 cp 时，mv 或 cp 的目标文件夹。文件的文件名变为文件夹打平后拼接原有文件名 | 当--on_succcess为mv或cp时需要填写 | ${EXEC_DIR}/success |
| -of | --on_fail | 1. none：跳过 2. mv：移动失败的文件到目标文件夹 3. cp：硬连接（拷贝）失败的文件到目标文件夹 4. delete：删除 | √ | |
| -fd | --fail_dir | 当--on_fail指定为 mv 或 cp 时，mv 或 cp 的目标文件夹。文件的文件名变为文件夹打平后拼接原有文件名 | 当--on_fail指定为 mv 或 cp 时需要填写 | ${EXEC_DIR}/fail |
| -tp | --timestamp_precision | 时间戳精度 tsfile 非远程导入：-tp 指定 tsfile 文件的时间精度 手动校验和服务器的时间戳是否一致 不一致返回报错信息 远程导入：-tp 指定 tsfile 文件的时间精度 pipe 自动校验时间戳精度是否一致 不一致返回 pipe 报错信息 | 否： 1. ms（毫秒） 2. us（微秒） 3. ns（纳秒） | ms |
2.4.3 运行示例
# 正确示例 > tools/import-data.sh -ft tsfile -sql_dialect table -s ./tsfile -db database1 -os none -of none # 异常示例 > tools/import-data.sh -ft tsfile -sql_dialect table -s ./tsfile -db database1 Parse error: Missing required options: os, of
3. TsFile 自动加载功能
本功能允许 IoTDB 主动监听指定目录下的新增 TsFile，并将 TsFile 自动加载至 IoTDB 中。通过此功能，IoTDB 能自动检测并加载 TsFile，无需手动执行任何额外的加载操作。
3.1 配置参数
可通过从配置文件模版 iotdb-system.properties.template 中找到下列参数，添加到 IoTDB 配置文件 iotdb-system.properties 中开启 TsFile 自动加载功能。完整配置如下：
| 配置参数 | 参数说明 | value 取值范围 | 是否必填 | 默认值 | 加载方式 |
|---|---|---|---|---|---|
| load_active_listening_enable | 是否开启 DataNode 主动监听并且加载 tsfile 的功能（默认开启）。 | Boolean: true，false | 选填 | true | 热加载 |
| load_active_listening_dirs | 需要监听的目录（自动包括目录中的子目录），如有多个使用 “，“ 隔开； 默认的目录为 ext/load/pending；支持热装载； 注意：表模型中，文件所在的目录名会作为 database； | String: 一个或多个文件目录 | 选填 | ext/load/pending | 热加载 |
| load_active_listening_fail_dir | 执行加载 tsfile 文件失败后将文件转存的目录，只能配置一个 | String: 一个文件目录 | 选填 | ext/load/failed | 热加载 |
| load_active_listening_max_thread_num | 同时执行加载 tsfile 任务的最大线程数，参数被注释掉时的默值为 max(1, CPU 核心数 / 2)，当用户设置的值不在这个区间[1, CPU核心数 /2]内时，会设置为默认值 (1, CPU 核心数 / 2) | Long: [1, Long.MAX_VALUE] | 选填 | max(1, CPU 核心数 / 2) | 重启后生效 |
| load_active_listening_check_interval_seconds | 主动监听轮询间隔，单位秒。主动监听 tsfile 的功能是通过轮询检查文件夹实现的。该配置指定了两次检查 load_active_listening_dirs 的时间间隔，每次检查完成 load_active_listening_check_interval_seconds 秒后，会执行下一次检查。当用户设置的轮询间隔小于 1 时，会被设置为默认值 5 秒 | Long: [1, Long.MAX_VALUE] | 选填 | 5 | 重启后生效 |
3.2 示例说明
load_active_listening_dir/ ├─sensors/ │ ├─temperature/ │ │ └─temperature-table.TSFILE
- 表模型 TsFile
temperature-table.TSFILE: 会被导入到temperaturedatabase 下(因为它位于sensors/temperature/目录下)
3.3 注意事项
- 如果待加载的文件中，存在 mods 文件，应优先将 mods 文件移动到监听目录下面，然后再移动 tsfile 文件，且 mods 文件应和对应的 tsfile 文件处于同一目录。防止加载到 tsfile 文件时，加载不到对应的 mods 文件
- 禁止设置 Pipe 的 receiver 目录、存放数据的 data 目录等作为监听目录
- 禁止
load_active_listening_fail_dir与load_active_listening_dirs存在相同的目录，或者互相嵌套 - 保证
load_active_listening_dirs目录有足够的权限，在加载成功之后，文件将会被删除，如果没有删除权限，则会重复加载
4. Load SQL
IoTDB 支持通过 CLI 执行 SQL 直接将存有时间序列的一个或多个 TsFile 文件导入到另外一个正在运行的 IoTDB 实例中。
4.1 运行命令
load '<path/dir>' with ( 'attribute-key1'='attribute-value1', 'attribute-key2'='attribute-value2', )
<path/dir>：文件本身，或是包含若干文件的文件夹路径<attributes>：可选参数，具体如下表所示
| Key | Key 描述 | Value 类型 | Value 取值范围 | Value 是否必填 | Value 默认值 |
|---|---|---|---|---|---|
database-level | 当 tsfile 对应的 database 不存在时，可以通过 database-level参数的值来制定 database 的级别，默认为iotdb-common.properties中设置的级别。例如当设置 level 参数为 1 时表明此 tsfile 中所有时间序列中层级为1的前缀路径是 database。 | Integer | [1: Integer.MAX_VALUE] | 否 | 1 |
on-success | 表示对于成功载入的 tsfile 的处置方式:默认为delete，即tsfile 成功加载后将被删除;none 表明 tsfile 成功加载之后依然被保留在源文件夹, | String | delete / none | 否 | delete |
model | 指定写入的 tsfile 是表模型还是树模型 | String | tree / table | 否 | 与-sql_dialect一致 |
database-name | 仅限表模型有效: 文件导入的目标 database，不存在时会自动创建，database-name中不允许包括"root."前缀，如果包含，将会报错。 | String | - | 否 | null |
convert-on-type-mismatch | 加载 tsfile 时，如果数据类型不一致，是否进行转换 | Boolean | true / false | 否 | true |
verify | 加载 tsfile 前是否校验 schema | Boolean | true / false | 否 | true |
tablet-conversion-threshold | 转换为 tablet 形式的 tsfile 大小阈值，针对小文件 tsfile 加载，采用将其转换为 tablet 形式进行写入:默认值为 -1，即任意大小 tsfile 都不进行转换 | Integer | [-1,0 :Integer.MAX_VALUE] | 否 | -1 |
async | 是否开启异步加载 tsfile，将文件移到 active load 目录下面，所有的 tsfile 都 load 到database-name下. | Boolean | true / false | 否 | false |
4.2 运行示例
-- 准备目标数据库 database2 IoTDB> create database database2 Msg: The statement is executed successfully. IoTDB> use database2 Msg: The statement is executed successfully. IoTDB:database2> show tables details +---------+-------+------+-------+ |TableName|TTL(ms)|Status|Comment| +---------+-------+------+-------+ +---------+-------+------+-------+ Empty set. --通过执行load sql 导入tsfile IoTDB:database2> load '/home/dump0.tsfile' with ( 'on-success'='none', 'database-name'='database2') Msg: The statement is executed successfully. -- 验证数据导入成功 IoTDB:database2> select * from table2 +-----------------------------+------+--------+---------+-----------+--------+------+-----------------------------+ | time|region|plant_id|device_id|temperature|humidity|status| arrival_time| +-----------------------------+------+--------+---------+-----------+--------+------+-----------------------------+ |2024-11-30T00:00:00.000+08:00| 上海| 3002| 101| 90.0| 35.2| true| null| |2024-11-29T00:00:00.000+08:00| 上海| 3001| 101| 85.0| 35.1| null|2024-11-29T10:00:13.000+08:00| |2024-11-27T00:00:00.000+08:00| 北京| 1001| 101| 85.0| 35.1| true|2024-11-27T16:37:01.000+08:00| |2024-11-29T11:00:00.000+08:00| 上海| 3002| 100| null| 45.1| true| null| |2024-11-28T08:00:00.000+08:00| 上海| 3001| 100| 85.0| 35.2| false|2024-11-28T08:00:09.000+08:00| |2024-11-26T13:37:00.000+08:00| 北京| 1001| 100| 90.0| 35.1| true|2024-11-26T13:37:34.000+08:00| +-----------------------------+------+--------+---------+-----------+--------+------+-----------------------------+