数据导出

1. 功能概述

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

• 数据导出工具 ：export-data.sh/bat 位于 tools 目录下，能够将指定 SQL 的查询结果导出为 CSV、SQL 及 TsFile （开源时间序列文件格式）格式。
• 基于 PIPE 框架的 TsFileBackup：tsfile-backup.sh/bat位于 tools 目录下，能够使用 PIPE 将指定的数据文件导出为 TsFile 格式。
• Copy SQL 导出 TsFile：通过 SQL 将查询结果写回到指定路径的 TsFile 中。

文件格式	IoTDB工具	具体介绍
CSV	export-data.sh/bat	纯文本格式，存储格式化数据，需按照下文指定 CSV 格式进行构造
SQL		包含自定义 SQL 语句的文件
TsFile		开源时序数据文件格式
	tsfile-backup.sh/bat	开源时序数据文件格式，支持 Object 数据类型
	Copy SQL	开源时序数据文件格式

2. 数据导出工具

2.1 公共参数

参数缩写	参数全称	参数含义	是否为必填项	默认值
-ft	--file_type	导出文件的类型，可以选择：csv、sql、tsfile	√
-h	--host	主机名	否	127.0.0.1
-p	--port	端口号	否	6667
-u	--username	用户名	否	root
-pw	--password	密码，自 V2.0.9.1 起支持隐藏输入	否	TimechoDB@2021 (V2.0.6 版本之前为 root)
-sql_dialect	--sql_dialect	选择 server 是树模型还是表模型，当前支持 tree 和 table 类型	否	tree
-db	--database	​将要导出的目标数据库，只在-sql_dialect为 table 类型下生效。	-sql_dialect为 table 时必填	-
-table	--table	将要导出的目标表，只在-sql_dialect为 table 类型下生效。如果指定了-q参数则此参数不生效，如果导出类型为 tsfile/sql 则此参数必填。	​ 否	-
-start_time	--start_time	将要导出的数据起始时间，只有-sql_dialect为 table 类型时生效。如果填写了-q，则此参数不生效。支持的时间类型同-tf参数。	否	-
-end_time	--end_time	将要导出的数据的终止时间，只有-sql_dialect为 table 类型时生效。如果填写了-q，则此参数不生效。	否	-
-t	--target	指定输出文件的目标文件夹，如果路径不存在新建文件夹	√
-pfn	--prefix_file_name	指定导出文件的名称。例如：abc,生成的文件是abc_0.tsfile、abc_1.tsfile	否	dump_0.tsfile
-q	--query	要执行的查询语句。自 V2.0.8 起，SQL 语句中的分号将被自动移除，查询执行保持正常。	否	无
-timeout	--query_timeout	会话查询的超时时间(ms)	否	-1(V2.0.8 之前) Long.MAX_VALUE(V2.0.8 及之后) 范围：-1~Long.MAX_VALUE
-help	--help	显示帮助信息	否
-usessl	--use_ssl	使用 SSL 协议，自 V2.0.9.1 起支持	否	-
-ts	--trust_store	信任库。支持隐藏输入，自 V2.0.9.1 起支持	否	-
-tpw	--trust_store_password	信任库密码。支持隐藏输入，自 V2.0.9.1 起支持	否	-

2.2 CSV 格式

2.2.1 运行命令

# Unix/OS X
> tools/export-data.sh -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table>  
                [-start_time<start_time>] [-end_time<end_time>] [-h <host>] [-p <port>] [-u <username>] [-pw <password>] 
                -t <target_directory> [-pfn <prefix_file_name>] [-dt <datatype>] [-lpf <lines_per_file>] [-tf <time_format>] 
               [-tz <timezone>] [-q <query_command>] [-timeout <query_timeout>]
# Windows
# V2.0.4.x 版本之前
> tools\export-data.bat -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table>  
                [-start_time<start_time>] [-end_time<end_time>] [-h <host>] [-p <port>] [-u <username>] [-pw <password>] 
                -t <target_directory> [-pfn <prefix_file_name>] [-dt <datatype>] [-lpf <lines_per_file>] [-tf <time_format>] 
               [-tz <timezone>] [-q <query_command>] [-timeout <query_timeout>]
               
# V2.0.4.x 版本及之后 
> tools\windows\export-data.bat -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table>  
                [-start_time<start_time>] [-end_time<end_time>] [-h <host>] [-p <port>] [-u <username>] [-pw <password>] 
                -t <target_directory> [-pfn <prefix_file_name>] [-dt <datatype>] [-lpf <lines_per_file>] [-tf <time_format>] 
               [-tz <timezone>] [-q <query_command>] [-timeout <query_timeout>]

2.2.2 私有参数

参数缩写	参数全称	参数含义	是否为必填项	默认值
-dt	--datatype	是否在 CSV 文件的表头输出时间序列的数据类型，可以选择true或false	否	false
-lpf	--lines_per_file	每个转储文件的行数	否	10000 范围：0～Integer.Max=2147483647
-tf	--time_format	指定 CSV 文件中的时间格式。可以选择：1) 时间戳（数字、长整型）；2) ISO8601（默认）；3) 用户自定义模式，如yyyy-MM-dd HH:mm:ss（默认为ISO8601）。SQL 文件中的时间戳输出不受时间格式设置影响	否	ISO8601
-tz	--timezone	设置时区，例如+08:00或-01:00	否	本机系统时间

2.2.3 运行示例：

# 正确示例
> export-data.sh -ft csv -sql_dialect table -t /path/export/dir -db database1 -q "select * from table1"

# 异常示例
> export-data.sh -ft csv -sql_dialect table -t /path/export/dir -q "select * from table1"
Parse error: Missing required option: db

2.3 SQL 格式

2.3.1 运行命令

# Unix/OS X
> tools/export-data.sh -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table>  
                [-start_time<start_time>] [-end_time<end_time>] [-h <host>] [-p <port>] [-u <username>] [-pw <password>] 
          -t <target_directory> [-pfn <prefix_file_name>] [-aligned <export aligned insert sql>]
          -lpf <lines_per_file> - [-tf <time_format>] [-tz <timezone>] [-q <query_command>] [-timeout <query_timeout>]
      
# Windows
# V2.0.4.x 版本之前
> tools\export-data.bat -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table>  
                [-start_time<start_time>] [-end_time<end_time>] [-h <host> -p <port> -u <username> -pw <password>] 
          -t <target_directory> [-pfn <prefix_file_name>  -aligned <export aligned insert sql>  
          -lpf <lines_per_file> -tf <time_format> -tz <timezone> -q <query_command> -timeout <query_timeout>]
          
# V2.0.4.x 版本及之后  
> tools\windows\export-data.bat -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table>  
                [-start_time<start_time>] [-end_time<end_time>] [-h <host> -p <port> -u <username> -pw <password>] 
          -t <target_directory> [-pfn <prefix_file_name>  -aligned <export aligned insert sql>  
          -lpf <lines_per_file> -tf <time_format> -tz <timezone> -q <query_command> -timeout <query_timeout>]

2.3.2 私有参数

参数缩写	参数全称	参数含义	是否为必填项	默认值
-aligned	--use_aligned	是否导出为对齐的 SQL 格式	否	true
-lpf	--lines_per_file	每个转储文件的行数	否	10000 范围：0～Integer.Max=2147483647
-tf	--time_format	指定 CSV 文件中的时间格式。可以选择：1) 时间戳（数字、长整型）；2) ISO8601（默认）；3) 用户自定义模式，如yyyy-MM-dd HH:mm:ss（默认为ISO8601）。SQL 文件中的时间戳输出不受时间格式设置影响	否	ISO8601
-tz	--timezone	设置时区，例如+08:00或-01:00	否	本机系统时间

2.3.3 运行示例：

# 正确示例
> export-data.sh -ft sql -sql_dialect table -t /path/export/dir -db database1 -start_time 1

# 异常示例
> export-data.sh -ft sql -sql_dialect table -t /path/export/dir -start_time 1
Parse error: Missing required option: db

2.4 TsFile 格式

2.4.1 运行命令

# Unix/OS X
> tools/export-data.sh -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table>  
                [-start_time<start_time>] [-end_time<end_time>] [-h <host>] [-p <port>] [-u <username>] [-pw <password>]
        -t <target_directory> [-pfn <prefix_file_name>] [-q <query_command>] [-timeout <query_timeout>]
      
# Windows
# V2.0.4.x 版本之前
> tools\export-data.bat -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table>  
                [-start_time<start_time>] [-end_time<end_time>] [-h <host>] [-p <port>] [-u <username>] [-pw <password>]
        -t <target_directory> [-pfn <prefix_file_name>] [-q <query_command>] [-timeout <query_timeout>]
        
# V2.0.4.x 版本及之后 
> tools\windows\export-data.bat -ft<format> [-sql_dialect<sql_dialect>] -db<database> -table<table>  
                [-start_time<start_time>] [-end_time<end_time>] [-h <host>] [-p <port>] [-u <username>] [-pw <password>]
        -t <target_directory> [-pfn <prefix_file_name>] [-q <query_command>] [-timeout <query_timeout>]

2.4.2 私有参数

• 无

2.4.3 运行示例：

# 正确示例
> /tools/export-data.sh -ft tsfile -sql_dialect table -t /path/export/dir -db database1 -start_time 0

# 异常示例
> /tools/export-data.sh -ft tsfile -sql_dialect table -t /path/export/dir -start_time 0
Parse error: Missing required option: db

3. 基于 PIPE 框架的 TsFileBackup

IoTDB 自 V2.0.9.2 版本起支持 tsfile-backup.sh/bat 脚本，该脚本能够自动生成并向服务端发送 CREATE PIPE SQL 指令，将指定的数据文件导出为 TsFile 格式。

注意：

1. 使用该脚本需联系天谋团队获取相关的 jar 包（tsfile-remote-sink-<version>-jar-with-dependencies.jar），并放至 IoTDB 可访问的路径（例如所有数据节点主机）。
2. 该脚本支持 Object 类型数据导出为 TsFile 文件。

3.1 运行命令

# Unix/OS X
> tools/tsfile-backup.sh [-sql_dialect <sql_dialect>] [-h <host>] [-p <port>]
       [-u <username>] [-pw <password>] [-path <path>] [-db <db>] [-table
       <table>] [-s <start_time>] [-e <end_time>] [-t <target_directory>] 
       [-th <target_host>] [-tu <target_host_user>] [-tp <target_host_port>]
       [--rate_limit] [--plugin_jar] [-help]
# Windows
> tools\windows>tsfile-backup.bat [-sql_dialect <sql_dialect>] [-h <host>] [-p <port>]
       [-u <username>] [-pw <password>] [-path <path>]  [-db <db>] [-table
       <table>] [-s <start_time>] [-e <end_time>] [-t <target_directory>] 
       [-th <target_host>] [-tu <target_host_user>] [-tp <target_host_port>]
       [--rate_limit] [--plugin_jar] [-help]

3.2 脚本参数

参数缩写	参数全称	参数含义	是否为必填项	默认值
-sql_dialect	--sql_dialect	指定数据模型类型，可选值：tree(树模型) 或table(表模型)。	是	-
-h	--host	本地主机地址。指当前数据所在的 IoTDB 实例 IP。	否	127.0.0.1
-p	--port	端口号，IoTDB RPC 服务端口。	否	6667
-u	--user	用户名，用于登录 IoTDB 验证。	否	root
-pw	--password	密码，对应用户的IoTDB密码，支持隐藏输入。	否	root
-t	--target	导出目标目录。在 SCP 模式下，此路径指远程服务器上的绝对物理路径。TsFile 和关联的 Object 目录将导出至此。	是	-
-db	--database	数据库名称 (表模型可选)	否	.*
-table	--table	表名 (表模型可选)	否	.*
-s	--start_time	起始时间。支持 ISO8601 格式（如 2026-01-01T00:00:00）或毫秒时间戳。仅导出该时间点及之后的数据。	否	-
-e	--end_time	截止时间。格式同上。仅导出该时间点之前的数据。	否	-
-th	--target_host	远程目标主机 IP，默认自动识别启动脚本的IP。指定此参数后，脚本将自动配置 Pipe 使用 SCP 模式进行数据传输。	否	-
-tu	--target_host_user	远程主机用户名。用于 SSH/SCP 登录目标服务器。	否	-
-tpw	--target_host_pw	远程主机密码。用于远程身份验证，支持隐藏输入。	否	-
-tp	--target_host_port	远程 SSH 端口。	否	22
--rate_limit	--rate_limit	发送速率限制。单位：字节/秒 (Bytes/s)。防止导出任务占用过多网络带宽。	否	-
--plugin_jar	--plugin_jar	指定 Pipe 插件的Jar包路径	否	-
--object-parallelism	--object-parallelism	指定object文件发送最大并行度	否	-
--object-batch-size	--object-batch-size	限制每个对象文件上传批次的总字节数，用于控制内存占用和单次 SCP 传输大小	否	-
-help	--help	查看帮助	否	-

3.3 运行示例

示例一：SCP 远程导出（将数据发送到另一台服务器）

./tsfile-backup.sh -sql_dialect table -db test_db -t /remote/archive/ -th 192.168.1.100 -tu backup_user -tpw ComplexPass123!

示例二：带限速的远程 Object 数据导出

./tsfile-backup.sh -sql_dialect table -t /mnt/backup/ -th 10.0.0.5 -tu iot_admin -tpw Admin@2026 --rate_limit 5242880

示例三：指定 Pipe jar 目录

./tsfile-backup.sh -sql_dialect table -db test  -table .* -tu luoluoyuyu -tpw  -t /tmp/backup --plugin_jar /local/lib/tsfile-remote-sink-2.0.8-SNAPSHOT-jar-with-dependencies.jar

注意：SCP 模式导出 Object 类型数据时，为避免出现握手异常、连接失败或 Pipe 频繁启停问题，建议采取以下任一措施：

• 适当调低配置参数 object-parallelism
• 按需调大目标机的 MaxStartups，修改后执行 sshd reload 或 sshd restart 使配置生效

4. Copy SQL

注意：该功能自 V2.0.11.1 版本起支持。

4.1 运行命令

// ---------------------------------------- Copy Statement ---------------------------------------------------------
copyToStatement
    : COPY '(' query ')' TO fileName=string ((WITH)? copyToStatementOptions)?
    | COPY tableName=qualifiedName ('(' tableColumns=identifierList ')')? TO fileName=string ((WITH)? copyToStatementOptions)?
    ;

copyToStatementOptions
    : '(' copyToStatementOption (',' copyToStatementOption)* ')'
    ;

copyToStatementOption
    : FORMAT identifier
    | TABLE identifier
    | TAGS '(' identifierList ')'
    | TIME identifier
    | MEMORY_THRESHOLD memory=INTEGER_VALUE
    ;

参数介绍

名称	说明	默认值
FORMAT	导出格式，当前仅有 TsFile	TsFile
TABLE	指定生成的 TsFile 中的 Table 名称	如果查询 SQL 仅涉及一个 table，使用这个 table 名，否则使用 default
TIME	指定使用结果集中的哪一列作为 TIME 列。 手动指定时：列类型非 TIMESTAMP、找不到指定列均会报错； 未手动指定时：若存在列名 time 但类型非 TIMESTAMP 也会报错。 按以下优先级构造 time 列： 1. 查询仅涉及的一个 table 中的 time 列名称相同的列 2. 寻找列名为 "time" 且类型为 TIMESTAMP 的列作为时间列 3. 使用对应 device 写入的当前行数作为 time 生成时间列，列名为 "time"	-
TAGS	指定哪些列为 TAG 列，有多个 TAG 列时，最终生成的 table 内的顺序和指定的顺序一致。 手动指定时：列不存在、列类型非 STRING、存在重复列名均会报错。 如果查询仅涉及一个 table，且 table 所有 tag 列在查询结果集中可以找到，则推断为这个 table 的 tag 列，否则默认值为空列表，即除了 TIME 列以外其余所有列都被视为 FIELD 列	空列表
MEMORY_THRESHOLD	用于在生成 TsFile 时进行内存控制（单位：byte），手动指定数值小于等于 0 时将报错	32MB

结果集说明

列名	数据类型	说明
path	STRING	生成的目标文件的绝对路径
row_count	INT64	总写入行数
device_count	INT64	生成的设备数量
size_in_bytes	INT64	生成的目标文件大小
table_name	STRING	目标文件中的表名，如果是自动生成的，会通过 (auto_gen) 进行标记
time_column	STRING	目标文件中的表的 time 列名，如果是自动生成的，会通过 (auto_gen) 进行标记
tag_columns	STRING	目标文件中的表的 tag 列名，以 , 分隔

其他注意事项

• 对于文件生成位置：
  • 如果指定的是文件名，生成的 TsFile 保存在客户端直连的 DataNode 的 ${dn_data_dirs}/copy_to 下，配置多个目录时，按照配置项 dn_multi_dir_strategy 的策略生成；
  • 如果指定的是一个路径，则放在指定的路径下。
• 执行过程中可能出现的异常：
  • 按照给定的 schema 写入 TsFile，存在乱序时间戳时报错
  • 非法文件名或目标文件已存在时报错
  • 查询结果中存在重复列名
  • 磁盘空间不足

4.2 运行示例

以示例数据中 table1 为例

1. 通过 select 语句将 table1 中的全部数据导出到文件 copysql1.tsfile

TimechoDB:database1> copy (select * from table1) to 'copysql1.tsfile'
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-----------------------------+
|                                                 path|row_count|device_count|size_in_bytes|table_name|time_column|                  tag_columns|
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-----------------------------+
|/timechodb/data/datanode/data/copy_to/copysql1.tsfile|       18|           6|         4636|    table1|       time|[region, plant_id, device_id]|
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-----------------------------+
Total line number = 1
It costs 0.336s

2. 通过表名将 table1 中的全部数据导出到文件 copysql2.tsfile

TimechoDB:database1> copy table1 to 'copysql2.tsfile'
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-----------------------------+
|                                                 path|row_count|device_count|size_in_bytes|table_name|time_column|                  tag_columns|
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-----------------------------+
|/timechodb/data/datanode/data/copy_to/copysql2.tsfile|       18|           6|         4636|    table1|       time|[region, plant_id, device_id]|
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-----------------------------+
Total line number = 1
It costs 0.048s

3. 通过表名(列)的方式将 table1 中的部分数据导出到文件 copysql3.tsfile

TimechoDB:database1> copy table1 (device_id,temperature) to 'copysql3.tsfile'
+-----------------------------------------------------+---------+------------+-------------+----------+--------------+-----------+
|                                                 path|row_count|device_count|size_in_bytes|table_name|   time_column|tag_columns|
+-----------------------------------------------------+---------+------------+-------------+----------+--------------+-----------+
|/timechodb/data/datanode/data/copy_to/copysql3.tsfile|       18|           1|          558|    table1|time(auto_gen)|         []|
+-----------------------------------------------------+---------+------------+-------------+----------+--------------+-----------+
Total line number = 1
It costs 0.064s

4. 通过 select 语句将 table1 中部分数据的聚合结果导出到文件 copysql4.tsfile

TimechoDB:database1> copy (select count(temperature), count(humidity) from table1 group by device_id) to 'copysql4.tsfile'
+-----------------------------------------------------+---------+------------+-------------+----------+--------------+-----------+
|                                                 path|row_count|device_count|size_in_bytes|table_name|   time_column|tag_columns|
+-----------------------------------------------------+---------+------------+-------------+----------+--------------+-----------+
|/timechodb/data/datanode/data/copy_to/copysql4.tsfile|        2|           1|          543|    table1|time(auto_gen)|         []|
+-----------------------------------------------------+---------+------------+-------------+----------+--------------+-----------+
Total line number = 1
It costs 0.155s

5. 通过 select 语句将 table1 中的部分数据导出到文件 copysql5.tsfile ，并指定目标表、time列及 tag 列

TimechoDB:database1> copy (select time,region,device_id,temperature from table1 order by time) to 'copysql5.tsfile' (TABLE copytable, TIME time, TAGS (region,device_id))
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-------------------+
|                                                 path|row_count|device_count|size_in_bytes|table_name|time_column|        tag_columns|
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-------------------+
|/timechodb/data/datanode/data/copy_to/copysql5.tsfile|       18|           4|         1199| copytable|       time|[region, device_id]|
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-------------------+
Total line number = 1
It costs 0.047s