# IoTDB 数据导入全攻略：工具、自动加载与 Load SQL 详解
在物联网时序数据规模化应用的今天，如何高效、稳定地将海量数据导入IoTDB，是每个使用者都会面对的问题。IoTDB提供了多种数据导入方式，适配不同场景需求。本文从实操角度出发，详解数据导入工具、TsFile自动加载功能和Load SQL三种方式，帮助读者根据实际场景选择合适方案。
## 三大导入方式概览
IoTDB支持的数据导入方式主要分为三类：
| 导入方式 | 支持格式 | 适用场景 |
|---------|---------|---------|
| 数据导入工具 (import-data) | CSV、SQL、TsFile | 手动批量导入，适合离线数据迁移 |
| TsFile自动加载功能 | TsFile | 实时监听目录，适合流式数据接入 |
| Load SQL | TsFile | 通过SQL命令灵活加载，适合运维操作 |
## 方式一：数据导入工具（import-data）
import-data脚本是IoTDB最通用的数据导入工具，位于`tools`目录下，支持CSV、SQL和TsFile三种格式。
### CSV格式导入
CSV是最常用的数据交换格式。使用import-data.sh导入CSV的基本命令如下：
```bash
# Unix/OS X
tools/import-data.sh -ft csv -h 127.0.0.1 -p 6667 -u root -pw root -s /path/to/data.csv
# Windows
tools\import-data.bat -ft csv -h 127.0.0.1 -p 6667 -u root -pw root -s D:\data\data.csv
```
CSV文件需要遵循特定规范：
- 时间戳列必须作为文件首列
- 支持的时间格式：`yyyy-MM-dd HH:mm:ss`或`yyyy-MM-dd'T'HH:mm:ss.SSSZ`
- Text类型中的特殊字符（如逗号）需用反斜杠`\`转义
以下是一个标准的CSV文件示例：
```csv
Time,root.test.t1.str,root.test.t2.str,root.test.t2.var
1970-01-01T08:00:00.001+08:00,"123hello world","123\,abc",100
1970-01-01T08:00:00.002+08:00,"123",,
```
对于大规模导入，可以通过参数优化性能：
```bash
tools/import-data.sh -ft csv -s ./data/ -fd ./failed/ -aligned true -batch 100000 -tp ms -tn 4
```
关键参数说明：
- `-aligned true`：导入为对齐序列
- `-batch 100000`：每批处理10万行数据
- `-tp ms`：指定时间戳精度为毫秒
- `-tn 4`：启用4个并行线程
- `-fd ./failed/`：指定失败记录存放目录
### SQL格式导入
对于已经导出为SQL文件的数据，import-data工具同样支持：
```bash
tools/import-data.sh -ft sql -s /path/to/data.sql -fd ./failed/ -batch 100000
```
SQL文件中应包含标准的IoTDB插入语句，如：
```sql
insert into root.test.t1(timestamp, str) values(1625097600000, "hello");
insert into root.test.t2(timestamp, str, var) values(1625097601000, "world", 100);
```
## 方式二：TsFile自动加载功能
TsFile是IoTDB的原生文件格式，自动加载功能是v1.3.3版本引入的重要特性。它允许DataNode主动监听指定目录，当新TsFile文件生成时自动加载到数据库中。
### 配置自动加载
在`iotdb-datanode.properties`中配置监听目录：
<"bfd.a8k1.org.cn"><"iky.a8k1.org.cn"><"ynh.a8k1.org.cn">
```properties
# 启用自动加载
data_node_tsfile_auto_load_enable=true
# 监听的目录路径
data_node_tsfile_auto_load_dir=/data/tsfile/incoming
# 加载成功后的处理方式：delete、move或none
data_node_tsfile_auto_load_on_success=move
# 成功文件移动目标目录
data_node_tsfile_auto_load_success_dir=/data/tsfile/success
```
配置完成后重启DataNode，系统即开始自动监听指定目录。这种方式特别适合与数据采集系统集成，采集端将TsFile写入指定目录，IoTDB自动完成加载。
### 结合远程加载
对于分布式场景，IoTDB 0.13.5及以上版本支持通过HTTP协议远程加载TsFile：
```sql
-- 远程加载文件
load 'http://192.168.1.100:8000/data/1575028885956-101-0.tsfile'
```
这需要在源机器上启动HTTP服务，例如使用Python：
```bash
cd /data/tsfile/export
python -m http.server 8000
```
## 方式三：Load SQL导入
Load SQL是最灵活的TsFile导入方式，用户可以通过Cli工具或JDBC直接执行加载命令。
### 基础用法
```sql
-- 加载单个TsFile文件
load '/Users/Desktop/data/1575028885956-101-0.tsfile'
-- 批量加载目录下所有TsFile
load '/Users/Desktop/data'
-- 加载时指定存储组级别
load '/Users/Desktop/data' sglevel=1
<"nyr.a8k1.org.cn"><"ytn.a8k1.org.cn"><"rtg.a8k1.org.cn">
-- 加载后删除源文件
load '/Users/Desktop/data' >
```
### 参数详解
v1.3版本中Load SQL支持以下参数：
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `sglevel` | 自动创建Database的路径层级 | iotdb-common.properties中配置 |
| `verify` | 是否进行元数据校验 | true |
| `onSuccess` | 成功后的处理方式(delete/none) | delete |
开启元数据校验时，若待加载文件中的时间序列与现有序列数据类型不一致，加载会失败；关闭校验可提升加载速度，但需自行保证数据一致性。
### 脚本方式加载
除SQL命令外，IoTDB也提供了独立的加载脚本：
```bash
# Linux/Unix
./load-tsfile.sh -f /data/tsfile/batch -h 192.168.0.101 -p 6667 -u root -pw root --verify=false -->
# Windows
.\load-tsfile.bat -f D:\data\tsfile -h 192.168.0.101 -p 6667 -u root -pw root
```
## 场景化选择建议
面对不同的业务场景，可以选择最合适的导入方式：
- **历史数据批量迁移**：推荐使用import-data工具导入CSV或SQL文件，支持断点续传和失败重试。
- **实时数据流接入**：启用TsFile自动加载功能，采集端持续写入TsFile，IoTDB自动监听加载。
- **跨集群数据同步**：使用export-tsfile导出后再用Load SQL导入，支持完整的时序数据语义。
- **运维临时操作**：直接使用Load SQL命令，灵活快捷。
## 常见问题处理
### 1. 导入失败文件处理
使用import-data时，可通过`-fd`参数指定失败文件存放目录。失败文件以`.failed`为后缀，可检查后修正数据重新导入。
### 2. 数据类型不一致
导入CSV时可通过`-typeInfer`参数指定类型映射：
```bash
-typeInfer boolean=text,float=double,int=long
```
### 3. 内存溢出
对于超大文件导入，适当调低`-batch`参数值，避免单次处理数据量过大。
## 结语
IoTDB丰富的数据导入方式，覆盖了从离线批量到实时流式、从本地文件到远程加载的全场景需求。import-data工具简单通用，自动加载功能解放运维，Load SQL灵活可控。掌握这三种方式，即可根据业务特点选择最优方案，让时序数据接入更加高效顺畅。