數據導入
大約 11 分鐘
數據導入
1. 功能概述
IoTDB 支持三種方式進行數據導入：
- 數據導入工具 ：
import-data.sh/bat位于tools目錄下，可以將CSV、SQL、及TsFile（開源時序文件格式）的數據導入IoTDB。 TsFile自動加載功能。Load SQL導入TsFile。
| 文件格式 | IoTDB工具 | 具體介紹 |
|---|---|---|
| CSV | import-data.sh/bat | 可用于單個或一個目錄的 CSV 文件批量導入 IoTDB |
| SQL | 可用于單個或一個目錄的 SQL 文件批量導入 IoTDB | |
| TsFile | 可用于單個或一個目錄的 TsFile 文件批量導入 IoTDB | |
| TsFile 自動加載 | 可以監聽指定路徑下新產生的 TsFile 文件，并將其加載進 IoTDB | |
| 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 | 密碼 | 否 | TimechoDB@2021 (V2.0.6.x 版本之前為 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 TimechoDB@2021 -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.
# 注意：V2.0.6.x 版本之前 -pw 參數值默認值為 root2.3.4 導入說明
- CSV 導入規范
- 特殊字符轉義規則：若Text類型的字段中包含特殊字符（例如逗號,），需使用反斜杠（\）?進行轉義處理。
- 支持的時間格式：yyyy-MM-dd'T'HH:mm:ss， yyy-MM-dd HH:mm:ss， 或者 yyyy-MM-dd'T'HH:mm:ss.SSSZ。
- 時間戳列?必須作為數據文件的首列存在。
- 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,1232.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 TimechoDB@2021 -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.
# 注意：V2.0.6.x 版本之前 -pw 參數值默認值為 root2.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 TimechoDB@2021
-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.
# 注意：V2.0.6.x 版本之前 -pw 參數值默認值為 root3. 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 注意事項
- 如果待加載的文件中，存在 mods 文件，應優先將 mods 文件移動到監聽目錄下面，然后再移動 tsfile 文件，且 mods 文件應和對應的 tsfile 文件處于同一目錄。防止加載到 tsfile 文件時，加載不到對應的 mods 文件
- 禁止設置 Pipe 的 receiver 目錄、存放數據的 data 目錄等作為監聽目錄
- 禁止
load_active_listening_fail_dir與load_active_listening_dirs存在相同的目錄，或者互相嵌套 - 保證
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|
+-----------------------------+------------------------------------+---------------------------------+-------------------------------+