# 三条路进IoTDB：CSV批处理、自动加载与Load SQL的选型指南

**处理时序数据接入，选对导入方式比调优更重要**。某风电企业曾因每天千份TsFile手动导入耗费2小时，换用自动加载后，**运维介入降为0**；另一工业互联网团队误用CSV工具批量灌入万张表，因未配类型推断导致半数数据错位。

IoTDB目前开放**三条并行数据通道**：**import-data脚本适用于CSV/SQL文本、自动加载面向TsFile持续接入、Load SQL满足单次/批量TsFile注入**。选哪条路，取决于源文件格式与数据抵达模式。

## 路径一：import-data工具——CSV与SQL的通用摆渡船

这是覆盖场景最宽的路。**支持单文件/文件夹批量处理**，自动识别`.csv`/`.sql`后缀。某车企将千万级车载日志转为CSV灌入，**8线程并行、10万行/批写入，45分钟完成1.2TB迁移**。

**核心参数必须记牢**：

```bash

# 典型生产命令（对齐序列+类型推断+失败隔离）

tools/import-data.sh -ft csv \

-h 192.168.1.100 -p 6667 -u root -pw root \

-s /data/csv_batch/ \

-fd /data/failed/ \

-aligned true \

-batch 100000 \

-tp ms \

-ti "boolean=text,float=double,int=long" \

-tn 8

```

- **`-aligned true`**：对齐序列模板，多测点同时采样时**空间效率提升40%**

- **`-ti`类型推断**：源数据类型向目标类型映射，**避免布尔读成文本、整数溢出**

- **`-fd`失败目录**：格式错误行自动落盘为`.failed`文件，**不中断整体导入**

**CSV硬约束**：时间戳必须首列；Text内逗号需`\`转义；Header可带`(INT32)`类型声明。**不满足则报错隔离，不会污染已入库数据**。

## 路径二：TsFile自动加载——让目录变成“入口管道”

**这是运维负担最轻的路**。配置监听目录后，IoTDB进程**实时扫描新落地的TsFile，自动拉取入库**。某电力调度系统每天凌晨生成300个设备级TsFile，**原方案需定时任务+人工确认；换用自动加载后，文件抵达即入，延时小于5秒**。

**启用方式**（`iotdb-common.properties`）：

```properties

###### 自动加载模块 #######

enable_auto_load_tsfile=true

auto_load_tsfile_dir=/iotdb/incoming/

auto_load_tsfile_fail_dir=/iotdb/failed/

```

- **零脚本、零调用**，目录即接口

- **失败文件自动转移**，不影响后续写入

- **支持多级目录打平采集**，文件名保留溯源信息

适用画像：**上游持续生成TsFile、希望“放入即同步”的场景**。需注意：若同时开启写入负载，监控JVM内存水位。

## 路径三：Load SQL——TsFile的精准注射器

**这是颗粒度最细的路**。通过Cli或JDBC执行`load`指令，**单文件/文件夹均可，且附带三层校验开关**。

```sql

-- 单文件加载 + 关闭元数据校验（提速50%）

load '/iotdb/export/1678901234567-1-0.tsfile' verify=false

<"w7.p5k3.org.cn"><"g9.p5k3.org.cn"><"q2.p5k3.org.cn">

-- 批量加载 + 指定Database层级 + 保留源文件

load '/iotdb/daily_backup/' sglevel=1 >

```

**三个控制柄价值分明**：

- **`verify`**：默认true，校验序列数据类型；**确信一致时设为false，加载耗时减半**

- **`sglevel`**：自动创建Database的路径层级；**迁移无元数据文件时必填，否则数据“悬浮”**

- **`onSuccess`**：成功后的源文件处置；**生产建议`none`保留，回滚有凭据**

适用画像：**数据治理工程师单次交付、跨集群迁移、事故恢复**。配合`export-tsfile`导出的备份集，形成闭环。

## 三路对比：选型只需回答两个问题

|------|-------------|---------|----------|

| **批量能力** | 文件夹✅ | 文件夹✅ | 文件夹✅ |

| **类型推断** | `-ti`支持 | 无 | 无 |

**决策树**：

1. **源文件是CSV/SQL** → 唯一路径：`import-data`

2. **源文件是TsFile + 持续流入** → 自动加载

3. **源文件是TsFile + 单次/批量任务** → Load SQL

## 两个坑与两份保险

**坑一：CSV类型“悄悄转型”**

未配置`-ti`且Header无声明时，IoTDB按首行数据推断类型。某团队灌入风电功率（0.0~1.5）全部转成`INT32`，小数被截断。**解决方案：显式声明`-ti float=double`，或Header带`(FLOAT)`** 。

**坑二：自动加载与写入并发争内存**

高频写入集群开启自动加载，**大文件到达时触发Full GC风险**。**对策：调度错峰，或独立Consumer实例专司加载** 。

**保险：`.failed`文件复盘**

无论哪条路，**被拒绝的数据都应被视为“待治理清单”而非垃圾**。`import-data`的`-lpf`参数控制单失败文件行数，方便分片排查。

**时序数据入仓从未有银弹，但IoTDB给足了备胎**。CSV/SQL交给`import-data`，持续TsFile交给自动加载，备份恢复交给`load`——**选对路，数据自会流向正确的地方**。