跳至主要內容

数据导出

2025/4/3大约 8 分钟

数据导出

1. 功能概述

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

  • 数据导出工具 ：export-data.sh/bat 位于 tools 目录下，能够将指定 SQL 的查询结果导出为 CSV、SQL 及 TsFile （开源时间序列文件格式）格式。
  • Copy SQL 导出 TsFile：通过 SQL 将查询结果写回到指定路径的 TsFile 中。
文件格式IoTDB工具具体介绍
CSVexport-data.sh/bat纯文本格式，存储格式化数据，需按照下文指定 CSV 格式进行构造
SQL包含自定义 SQL 语句的文件
TsFile开源时序数据文件格式
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.10 起支持隐藏输入否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.10 起支持否-
-ts--trust_store信任库。支持隐藏输入，自 V2.0.10 起支持否-
-tpw--trust_store_password信任库密码。支持隐藏输入，自 V2.0.10 起支持否-

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. Copy SQL

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

3.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导出格式，当前仅有 TsFileTsFile
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

结果集说明

列名数据类型说明
pathSTRING生成的目标文件的绝对路径
row_countINT64总写入行数
device_countINT64生成的设备数量
size_in_bytesINT64生成的目标文件大小
table_nameSTRING目标文件中的表名，如果是自动生成的，会通过 (auto_gen) 进行标记
time_columnSTRING目标文件中的表的 time 列名，如果是自动生成的，会通过 (auto_gen) 进行标记
tag_columnsSTRING目标文件中的表的 tag 列名，以 , 分隔

其他注意事项

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

3.2 运行示例

以示例数据中 table1 为例

  1. 通过 select 语句将 table1 中的全部数据导出到文件 copysql1.tsfile
IoTDB:database1> copy (select * from table1) to 'copysql1.tsfile'
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-----------------------------+
|                                                 path|row_count|device_count|size_in_bytes|table_name|time_column|                  tag_columns|
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-----------------------------+
|    /iotdb/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
  1. 通过表名将 table1 中的全部数据导出到文件 copysql2.tsfile
IoTDB:database1> copy table1 to 'copysql2.tsfile'
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-----------------------------+
|                                                 path|row_count|device_count|size_in_bytes|table_name|time_column|                  tag_columns|
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-----------------------------+
|    /iotdb/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
  1. 通过表名(列)的方式将 table1 中的部分数据导出到文件 copysql3.tsfile
IoTDB:database1> copy table1 (device_id,temperature) to 'copysql3.tsfile'
+-----------------------------------------------------+---------+------------+-------------+----------+--------------+-----------+
|                                                 path|row_count|device_count|size_in_bytes|table_name|   time_column|tag_columns|
+-----------------------------------------------------+---------+------------+-------------+----------+--------------+-----------+
|    /iotdb/data/datanode/data/copy_to/copysql3.tsfile|       18|           1|          558|    table1|time(auto_gen)|         []|
+-----------------------------------------------------+---------+------------+-------------+----------+--------------+-----------+
Total line number = 1
It costs 0.064s
  1. 通过 select 语句将 table1 中部分数据的聚合结果导出到文件 copysql4.tsfile
IoTDB: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|
+-----------------------------------------------------+---------+------------+-------------+----------+--------------+-----------+
|    /iotdb/data/datanode/data/copy_to/copysql4.tsfile|        2|           1|          543|    table1|time(auto_gen)|         []|
+-----------------------------------------------------+---------+------------+-------------+----------+--------------+-----------+
Total line number = 1
It costs 0.155s
  1. 通过 select 语句将 table1 中的部分数据导出到文件 copysql5.tsfile ，并指定目标表、time列及 tag 列
IoTDB: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|
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-------------------+
|    /iotdb/data/datanode/data/copy_to/copysql5.tsfile|       18|           4|         1199| copytable|       time|[region, device_id]|
+-----------------------------------------------------+---------+------------+-------------+----------+-----------+-------------------+
Total line number = 1
It costs 0.047s

版权所有 © 2026 Apache软件基金会。 Apache IoTDB，IoTDB，Apache，Apache 羽毛标志和 Apache IoTDB 项目标志是 Apache 软件基金会在所有国家的注册商标或商标

有问题吗？ 在 QQ、微信或 Slack 上联系我们。 立即加入社区