IoTDB 数据导入全攻略：工具、自动加载与 Load SQL 详解

本文详细介绍了 IoTDB 支持的数据导入工具、TsFile 自动加载和Load SQL 导入三种数据导入方式，分别阐述了数据导入工具针对 CSV、SQL、TsFile 三种格式文件的参数配置、运行命令及异常处理方案，TsFile 自动加载功能的配置参数与注意事项，以及 Load SQL 导入 TsFile 的语法规则与属性参数设置，并结合具体示例说明不同导入方式的实操流程，旨在帮助使用者根据实际业务场景选择合适的导入方案，提升 IoTDB 时序数据导入的效率与稳定性。

1. 功能概述

IoTDB 支持三种方式进行数据导入：

• 数据导入工具 ：import-data.sh/bat 位于 tools 目录下，可以将 CSV、SQL、及TsFile（开源时序文件格式）的数据导入 IoTDB。
• TsFile 自动加载功能。
• Load SQL 导入 TsFile 。

文件格式	IoTDB工具	具体介绍
CSV	import-data.sh/bat	可用于单个或一个目录的 CSV 文件批量导入 IoTDB
SQL	import-data.sh/bat	可用于单个或一个目录的 SQL 文件批量导入 IoTDB
TsFile	import-data.sh/bat	可用于单个或一个目录的 TsFile 文件批量导入 IoTDB
TsFile	TsFile 自动加载	可以监听指定路径下新产生的 TsFile 文件，并将其加载进 IoTDB
TsFile	Load SQL	可用于单个或一个目录的 TsFile 文件批量导入 IoTDB

2. 数据导入工具

2.1 公共参数

参数缩写	参数全称	参数含义	是否为必填项	默认值
-ft	–file_type	导入文件的类型，可以选择：csv、sql、tsfile	√
-h	– host	主机名	否	127.0.0.1
-p	–port	端口号	否	6667
-u	–username	用户名	否	root
-pw	–password	密码	否	root
-s	–source	待加载的脚本文件(夹)的本地目录路径 如果为csv sql tsfile这三个支持的格式，直接导入 不支持的格式，报错提示The file name must end with "csv" or "sql"or "tsfile"!	√
-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>  [-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>  [-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>  [-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 -h 127.0.0.1 -p 6667 -u root -pw root -s /path/sql 
      -fd /path/failure/dir -lpf 100  -aligned true -ti "BOOLEAN=text,INT=long,FLOAT=double" 
      -tp ms -tz +08:00 -batch 5000  -tn 4
      
# 异常示例
> tools/import-data.sh -ft csv -s /non_path
error: Source file or directory /non_path does not exist

> tools/import-data.sh -ft csv -s /path/sql -tn 0
error: Invalid thread number '0'. Please set a positive integer.

2.3.4 导入说明

1. CSV 导入规范

• 特殊字符转义规则：若Text类型的字段中包含特殊字符（例如逗号,），需使用反斜杠（\）进行转义处理。
• 支持的时间格式：yyyy-MM-dd’T’HH:mm:ss， yyy-MM-dd HH:mm:ss， 或者 yyyy-MM-dd’T’HH:mm:ss.SSSZ。
• 时间戳列必须作为数据文件的首列存在。

1. CSV 文件示例

• 时间对齐

-- header 中不包含数据类型
  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",,

-- header 中包含数据类型（Text 类型数据支持加双引号和不加双引号）
Time,root.test.t1.str(TEXT),root.test.t2.str(TEXT),root.test.t2.var(INT32)
1970-01-01T08:00:00.001+08:00,"123hello world","123\,abc",100
1970-01-01T08:00:00.002+08:00,123,hello world,123
1970-01-01T08:00:00.003+08:00,"123",,
1970-01-01T08:00:00.004+08:00,123,,12

• 设备对齐

-- header 中不包含数据类型
  Time,Device,str,var
  1970-01-01T08:00:00.001+08:00,root.test.t1,"123hello world",
  1970-01-01T08:00:00.002+08:00,root.test.t1,"123",
  1970-01-01T08:00:00.001+08:00,root.test.t2,"123\,abc",100

-- header 中包含数据类型（Text 类型数据支持加双引号和不加双引号）
Time,Device,str(TEXT),var(INT32)
1970-01-01T08:00:00.001+08:00,root.test.t1,"123hello world",
1970-01-01T08:00:00.002+08:00,root.test.t1,"123",
1970-01-01T08:00:00.001+08:00,root.test.t2,"123\,abc",100
1970-01-01T08:00:00.002+08:00,root.test.t1,hello world,123

2.3 SQL 格式

2.2.1 运行命令

# Unix/OS X
> tools/import-data.sh -ft<format>  [-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>  [-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\import-data.bat -ft<format>  [-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.2.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.2.3 运行示例

# 正确示例
> tools/import-data.sh -ft sql -h 127.0.0.1 -p 6667 -u root -pw root -s /path/sql 
        -fd /path/failure/dir -lpf 500  -tz +08:00 
        -batch 100000  -tn 4
      
# 异常示例
> tools/import-data.sh -ft sql -s /path/sql -fd /non_path
error: Source file or directory /path/sql does not exist


> tools/import-data.sh -ft sql -s /path/sql -tn 0
error: Invalid thread number '0'. Please set a positive integer.

2.4 TsFile 格式

2.4.1 运行命令

# Unix/OS X
> tools/import-data.sh -ft <format> [-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> [-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> [-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 -h 127.0.0.1 -p 6667 -u root -pw root 
      -s /path/sql -os mv -of cp -sd /path/success/dir -fd /path/failure/dir 
      -tn 8 -tz +08:00 -tp ms
      
# 异常示例
> tools/import-data.sh -ft tsfile -s /path/sql -os mv -of cp 
           -fd /path/failure/dir  -tn 8 
error: Missing option --success_dir (or -sd) when --on_success is 'mv' or 'cp'

> tools/import-data.sh -ft tsfile -s /path/sql -os mv -of cp 
          -sd /path/success/dir -fd /path/failure/dir  -tn 0 
error: Invalid thread number '0'. Please set a positive integer.

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 （支持热装载）	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 注意事项

1. 如果待加载的文件中，存在 mods 文件，应优先将 mods 文件移动到监听目录下面，然后再移动 tsfile 文件，且 mods 文件应和对应的 tsfile 文件处于同一目录。防止加载到 tsfile 文件时，加载不到对应的 mods 文件
2. 禁止设置 Pipe 的 receiver 目录、存放数据的 data 目录等作为监听目录
3. 禁止 load_active_listening_fail_dir 与 load_active_listening_dirs 存在相同的目录，或者互相嵌套
4. 保证 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 运行示例

-- 准备待导入环境
IoTDB> show databases
+-------------+-----------------------+---------------------+-------------------+---------------------+
|     Database|SchemaReplicationFactor|DataReplicationFactor|TimePartitionOrigin|TimePartitionInterval|
+-------------+-----------------------+---------------------+-------------------+---------------------+
|root.__system|                      1|                    1|                  0|            604800000|
+-------------+-----------------------+---------------------+-------------------+---------------------+

-- 通过load sql 导入 tsfile
IoTDB> load '/home/dump1.tsfile' with ( 'on-success'='none')
Msg: The statement is executed successfully.

-- 验证数据导入成功
IoTDB> select * from root.testdb.**
+-----------------------------+------------------------------------+---------------------------------+-------------------------------+
|                         Time|root.testdb.device.model.temperature|root.testdb.device.model.humidity|root.testdb.device.model.status|
+-----------------------------+------------------------------------+---------------------------------+-------------------------------+
|2025-04-17T10:35:47.218+08:00|                                22.3|                             19.4|                           true|
+-----------------------------+------------------------------------+---------------------------------+-------------------------------+

5.总结

本文详细介绍了 IoTDB 三种核心数据导入方式的使用方法、参数配置及注意事项，分别为数据导入工具导入、TsFile 自动加载和Load SQL 导入，可满足不同场景下的时序数据导入需求。

1. 数据导入工具
   该工具支持 CSV、SQL、TsFile 三种格式文件的批量导入，通过 import-data.sh/bat 脚本执行操作。使用时需配置文件类型、数据源路径等必填参数，同时可根据需求调整线程数、批次大小、时区等可选参数。不同格式文件有专属私有参数，比如 TsFile 格式需指定成功与失败文件的处理策略，CSV 格式可设置类型推断和时间戳精度。操作时需注意路径有效性、线程数取值范围等问题，避免出现导入异常。
2. TsFile 自动加载
   该功能通过配置 iotdb-system.properties 文件开启，IoTDB 会主动监听指定目录下新增的 TsFile 文件并自动加载。配置过程中需合理设置监听目录、失败文件目录、最大线程数等参数，同时要遵循 mods 文件与 TsFile 文件同目录、禁止监听敏感目录等规则，以此保证自动加载功能稳定运行。
3. Load SQL 导入
   该方式适用于通过 CLI 直接导入 TsFile 文件，使用 load 语句并搭配灵活的属性参数，比如指定数据库级别、成功后文件处置方式、数据模型类型等。此方法无需依赖外部脚本，可直接在 IoTDB 客户端执行，适合少量 TsFile 文件的快速导入场景。

综上，批量导入多格式文件时优先选择数据导入工具，需要持续自动导入 TsFile 时推荐自动加载功能，而简单的 TsFile 导入需求可直接使用Load SQL，根据实际场景选择合适的导入方式，能够有效提升 IoTDB 数据导入的效率与稳定性。

🌐 附：IoTDB的各大版本

📄 Apache IoTDB 是一款工业物联网时序数据库管理系统，采用端边云协同的轻量化架构，支持一体化的物联网时序数据收集、存储、管理与分析 ，具有多协议兼容、超高压缩比、高通量读写、工业级稳定、极简运维等特点。

版本	IoTDB 二进制包	IoTDB 源代码	发布说明
2.0.5	- All-in-one - AINode - SHA512 - ASC	- 源代码 - SHA512 - ASC	release notes
1.3.5	- All-in-one - AINode - SHA512 - ASC	- 源代码 - SHA512 - ASC	release notes
0.13.4	- All-in-one - Grafana 连接器 - Grafana 插件 - SHA512 - ASC	- 源代码 - SHA512 - ASC	release notes

✨ 目前最新版本为2.0.6，去获取：https://archive.apache.org/dist/iotdb/

联系博主

    xcLeigh 博主，全栈领域优质创作者，博客专家，目前，活跃在CSDN、微信公众号、小红书、知乎、掘金、快手、思否、微博、51CTO、B站、腾讯云开发者社区、阿里云开发者社区等平台，全网拥有几十万的粉丝，全网统一IP为 xcLeigh。希望通过我的分享，让大家能在喜悦的情况下收获到有用的知识。主要分享编程、开发工具、算法、技术学习心得等内容。很多读者评价他的文章简洁易懂，尤其对于一些复杂的技术话题，他能通过通俗的语言来解释，帮助初学者更好地理解。博客通常也会涉及一些实践经验，项目分享以及解决实际开发中遇到的问题。如果你是开发领域的初学者，或者在学习一些新的编程语言或框架，关注他的文章对你有很大帮助。

    亲爱的朋友，无论前路如何漫长与崎岖，都请怀揣梦想的火种，因为在生活的广袤星空中，总有一颗属于你的璀璨星辰在熠熠生辉，静候你抵达。

     愿你在这纷繁世间，能时常收获微小而确定的幸福，如春日微风轻拂面庞，所有的疲惫与烦恼都能被温柔以待，内心永远充盈着安宁与慰藉。

    至此，文章已至尾声，而您的故事仍在续写，不知您对文中所叙有何独特见解？期待您在心中与我对话，开启思想的新交流。

---

     💞 关注博主 🌀 带你实现畅游前后端！

     🏰 大屏可视化 🌀 带你体验酷炫大屏！

     💯 神秘个人简介 🌀 带你体验不一样得介绍！

     🥇 从零到一学习Python 🌀 带你玩转Python技术流！

     🏆 前沿应用深度测评 🌀 前沿AI产品热门应用在线等你来发掘！

     💦 注：本文撰写于CSDN平台,作者：xcLeigh（所有权归作者所有） ，https://xcleigh.blog.csdn.net/，如果相关下载没有跳转，请查看这个地址，相关链接没有跳转，皆是抄袭本文，转载请备注本文原地址。

---

     📣 亲，码字不易，动动小手，欢迎 点赞 ➕ 收藏，如 🈶 问题请留言（或者关注下方公众号，看见后第一时间回复，还有海量编程资料等你来领！），博主看见后一定及时给您答复 💌💌💌