docs: document V2.0.12 TsFile load fallback

src/UserGuide/Master/Tree/Tools-System/Data-Import-Tool_apache.md

@@ -319,4 +319,36 @@ IoTDB> select * from root.testdb.**
 +-----------------------------+------------------------------------+---------------------------------+-------------------------------+
 |2025-04-17T10:35:47.218+08:00|                                22.3|                             19.4|                           true|
 +-----------------------------+------------------------------------+---------------------------------+-------------------------------+
-```
+```
+
+### 4.3 File Import with Fallback
+
+Starting from V2.0.12, tree-model Load supports fault tolerance for localized file corruption when converting a TsFile into Tablets for writing. It converts and writes as much readable data as possible to reduce data loss caused by localized corruption.
+
+#### 4.3.1 Scope and Trigger Conditions
+
+- This capability applies to **the Load-to-Tablet conversion path for tree-model TsFiles**, including aligned and non-aligned devices.
+- The file must have already entered the Tablet conversion path. Entry points such as small-file conversion and conversion after a Load analysis exception still follow their respective conditions. This process is not forced for every Load failure.
+- If an exception eligible for fallback occurs during sequential scan initialization or reading, query fallback is triggered automatically. No additional fault-tolerance switch is required.
+- `convert-on-type-mismatch` controls conversion when data types do not match; it is not a separate switch for this capability.
+
+#### 4.3.2 Fallback Process
+
+1. **Parse with a sequential scan under normal conditions**: The system scans the TsFile sequentially, assembles the parsed data into Tablets, and writes them in batches.
+2. **Switch to queries if the sequential scan fails**: When a parsing exception eligible for fallback occurs, the system generates query tasks from the TsFile metadata. It continues reading unfinished measurements in the current device and subsequent devices, using the progress of data already emitted to reduce duplicate reads.
+3. **Split measurement groups if a query fails**: When a query task involving multiple measurements fails, the system progressively splits the measurement group and attempts to read each group separately. If a single measurement still cannot be read, the system skips the unread portion of that task and continues with other measurements and devices.
+4. **Attempt to commit data already converted**: Data successfully committed is retained. If a parsing exception prevents further processing and is not retryable, the system attempts to commit converted data pending writing before returning an error. Whether that data is written depends on the commit result.
+
+#### 4.3.3 Typical Scenarios
+
+| **File Condition** | **Behavior** | **Expected Result** |
+| :--- | :--- | :--- |
+| A measurement in an intermediate device is corrupted | Fall back to queries and split measurement groups if necessary | Retain earlier data where possible and continue importing other measurements in the same device and subsequent devices |
+| A measurement in the first non-aligned device is corrupted | Attempt to query other measurements in the first device and subsequent devices | Avoid abandoning subsequent readable data solely because of localized corruption in the first device |
+| Individual measurements in a wide aligned device are corrupted | Split the queried measurement list and skip unreadable single-measurement tasks | Import as much data from uncorrupted measurements as possible |
+| Corruption is encountered after some measurements have been completed | Resume queries based on completed measurements and timestamps of data already emitted | Reduce duplicate reads of data already emitted |
+| Metadata is also corrupted, preventing fallback tasks from being created | Return a failure and attempt to commit converted data pending writing | Retain committed data; whether pending data is written depends on the commit result |
+
+For example, a non-aligned file contains three devices in order: `d0`, `d1`, and `d2`. Each device has two measurements, `s0` and `s1`. If a data chunk in `d1.s1` is corrupted, the system retains previously committed data where possible, attempts to read the remaining data in `d1`, and continues importing `d2`. Unreadable portions of `d1.s1` may be missing; the amount of data recovered depends on the actual location of the corruption.
+
+**A successful return means that conversion and writing have completed under the current fault-tolerance rules. It does not mean that all data in the corrupted file has been imported.**

src/UserGuide/latest/Tools-System/Data-Import-Tool_apache.md

@@ -319,4 +319,36 @@ IoTDB> select * from root.testdb.**
 +-----------------------------+------------------------------------+---------------------------------+-------------------------------+
 |2025-04-17T10:35:47.218+08:00|                                22.3|                             19.4|                           true|
 +-----------------------------+------------------------------------+---------------------------------+-------------------------------+
-```
+```
+
+### 4.3 File Import with Fallback
+
+Starting from V2.0.12, tree-model Load supports fault tolerance for localized file corruption when converting a TsFile into Tablets for writing. It converts and writes as much readable data as possible to reduce data loss caused by localized corruption.
+
+#### 4.3.1 Scope and Trigger Conditions
+
+- This capability applies to **the Load-to-Tablet conversion path for tree-model TsFiles**, including aligned and non-aligned devices.
+- The file must have already entered the Tablet conversion path. Entry points such as small-file conversion and conversion after a Load analysis exception still follow their respective conditions. This process is not forced for every Load failure.
+- If an exception eligible for fallback occurs during sequential scan initialization or reading, query fallback is triggered automatically. No additional fault-tolerance switch is required.
+- `convert-on-type-mismatch` controls conversion when data types do not match; it is not a separate switch for this capability.
+
+#### 4.3.2 Fallback Process
+
+1. **Parse with a sequential scan under normal conditions**: The system scans the TsFile sequentially, assembles the parsed data into Tablets, and writes them in batches.
+2. **Switch to queries if the sequential scan fails**: When a parsing exception eligible for fallback occurs, the system generates query tasks from the TsFile metadata. It continues reading unfinished measurements in the current device and subsequent devices, using the progress of data already emitted to reduce duplicate reads.
+3. **Split measurement groups if a query fails**: When a query task involving multiple measurements fails, the system progressively splits the measurement group and attempts to read each group separately. If a single measurement still cannot be read, the system skips the unread portion of that task and continues with other measurements and devices.
+4. **Attempt to commit data already converted**: Data successfully committed is retained. If a parsing exception prevents further processing and is not retryable, the system attempts to commit converted data pending writing before returning an error. Whether that data is written depends on the commit result.
+
+#### 4.3.3 Typical Scenarios
+
+| **File Condition** | **Behavior** | **Expected Result** |
+| :--- | :--- | :--- |
+| A measurement in an intermediate device is corrupted | Fall back to queries and split measurement groups if necessary | Retain earlier data where possible and continue importing other measurements in the same device and subsequent devices |
+| A measurement in the first non-aligned device is corrupted | Attempt to query other measurements in the first device and subsequent devices | Avoid abandoning subsequent readable data solely because of localized corruption in the first device |
+| Individual measurements in a wide aligned device are corrupted | Split the queried measurement list and skip unreadable single-measurement tasks | Import as much data from uncorrupted measurements as possible |
+| Corruption is encountered after some measurements have been completed | Resume queries based on completed measurements and timestamps of data already emitted | Reduce duplicate reads of data already emitted |
+| Metadata is also corrupted, preventing fallback tasks from being created | Return a failure and attempt to commit converted data pending writing | Retain committed data; whether pending data is written depends on the commit result |
+
+For example, a non-aligned file contains three devices in order: `d0`, `d1`, and `d2`. Each device has two measurements, `s0` and `s1`. If a data chunk in `d1.s1` is corrupted, the system retains previously committed data where possible, attempts to read the remaining data in `d1`, and continues importing `d2`. Unreadable portions of `d1.s1` may be missing; the amount of data recovered depends on the actual location of the corruption.
+
+**A successful return means that conversion and writing have completed under the current fault-tolerance rules. It does not mean that all data in the corrupted file has been imported.**

src/zh/UserGuide/Master/Tree/Tools-System/Data-Import-Tool_apache.md

@@ -324,4 +324,36 @@ IoTDB> select * from root.testdb.**
 +-----------------------------+------------------------------------+---------------------------------+-------------------------------+
 |2025-04-17T10:35:47.218+08:00|                                22.3|                             19.4|                           true|
 +-----------------------------+------------------------------------+---------------------------------+-------------------------------+
-```
+```
+
+### 4.3 文件降级导入
+
+自 V2.0.12 起，树模型 Load 在将 TsFile 转换为 Tablet 写入时，支持对文件局部损坏进行容错处理，尽可能将仍可读取的数据转换为 Tablet 并写入，减少局部损坏造成的数据损失。
+
+#### 4.3.1 适用范围与触发条件
+
+- 适用于**树模型 TsFile 的 Load 转 Tablet 路径**，包括对齐设备和非对齐设备。
+- 本能力以文件已经进入 Tablet 转换路径为前提。小文件转换、Load 分析异常后的转换等入口仍遵循各自的判断条件，不能理解为任意 Load 失败都会强制执行本流程。
+- 在顺序扫描的初始化或读取过程中遇到可尝试降级处理的异常时，会自动触发查询回退，无需额外开启容错开关。
+- `convert-on-type-mismatch` 控制类型不一致时的转换行为，并非本功能的独立开关。
+
+#### 4.3.2 降级处理流程
+
+1. **正常情况下使用顺序扫描解析**：系统顺序扫描 TsFile，将解析得到的数据组成 Tablet 并批量写入。
+2. **顺序扫描失败后切换为查询方式**：发生可降级处理的解析异常时，系统根据 TsFile 元数据生成查询任务，继续读取当前设备尚未完成的测点和后续设备，并根据已输出进度减少重复读取。
+3. **查询失败后拆分测点组**：多测点查询任务失败时，系统逐步拆分测点组，分别尝试读取。单个测点仍无法读取时，跳过该任务尚未读取的部分，继续其他测点和设备。
+4. **尽量提交已经转换的数据**：已正常提交的数据会保留。遇到无法继续处理且不属于可重试类别的解析异常时，系统会在返回错误前尝试提交已转换的待写入数据，是否写入取决于提交结果。
+
+#### 4.3.3 典型场景
+
+| **文件情况** | **处理行为** | **预期结果** |
+| :--- | :--- | :--- |
+| 中间设备的某个测点损坏 | 回退为查询方式，必要时拆分测点组 | 尽量保留此前数据，继续同设备其他测点及后续设备的导入 |
+| 首个非对齐设备的某个测点损坏 | 尝试查询首个设备的其他测点和后续设备 | 不因首个设备的局部损坏直接放弃后续可读取数据 |
+| 宽对齐设备中个别测点损坏 | 拆分查询的测点列表，跳过无法读取的单测点任务 | 尽量导入未损坏测点的数据 |
+| 已完成部分测点后才发生损坏 | 根据已完成测点和输出时间戳衔接查询 | 减少对已经输出数据的重复读取 |
+| 元数据也损坏，无法建立回退任务 | 返回失败，并尝试提交已转换的待写入数据 | 已提交的数据保留，待写入数据是否写入取决于提交结果 |
+
+例如，一个非对齐文件依次包含 `d0`、`d1`、`d2` 三个设备，每个设备有 `s0`、`s1` 两个测点。如果 `d1.s1` 的数据块损坏，系统会尽量保留此前已提交的数据，尝试读取 `d1` 的剩余数据，并继续导入 `d2`。`d1.s1` 无法读取的部分可能缺失，具体恢复范围取决于实际损坏位置。
+
+**返回成功表示转换和写入流程按当前容错规则完成，不表示损坏文件中的全部数据均已导入。**

src/zh/UserGuide/latest/Tools-System/Data-Import-Tool_apache.md

@@ -324,3 +324,35 @@ IoTDB> select * from root.testdb.**
 |2025-04-17T10:35:47.218+08:00|                                22.3|                             19.4|                           true|
 +-----------------------------+------------------------------------+---------------------------------+-------------------------------+
 ```
+
+### 4.3 文件降级导入
+
+自 V2.0.12 起，树模型 Load 在将 TsFile 转换为 Tablet 写入时，支持对文件局部损坏进行容错处理，尽可能将仍可读取的数据转换为 Tablet 并写入，减少局部损坏造成的数据损失。
+
+#### 4.3.1 适用范围与触发条件
+
+- 适用于**树模型 TsFile 的 Load 转 Tablet 路径**，包括对齐设备和非对齐设备。
+- 本能力以文件已经进入 Tablet 转换路径为前提。小文件转换、Load 分析异常后的转换等入口仍遵循各自的判断条件，不能理解为任意 Load 失败都会强制执行本流程。
+- 在顺序扫描的初始化或读取过程中遇到可尝试降级处理的异常时，会自动触发查询回退，无需额外开启容错开关。
+- `convert-on-type-mismatch` 控制类型不一致时的转换行为，并非本功能的独立开关。
+
+#### 4.3.2 降级处理流程
+
+1. **正常情况下使用顺序扫描解析**：系统顺序扫描 TsFile，将解析得到的数据组成 Tablet 并批量写入。
+2. **顺序扫描失败后切换为查询方式**：发生可降级处理的解析异常时，系统根据 TsFile 元数据生成查询任务，继续读取当前设备尚未完成的测点和后续设备，并根据已输出进度减少重复读取。
+3. **查询失败后拆分测点组**：多测点查询任务失败时，系统逐步拆分测点组，分别尝试读取。单个测点仍无法读取时，跳过该任务尚未读取的部分，继续其他测点和设备。
+4. **尽量提交已经转换的数据**：已正常提交的数据会保留。遇到无法继续处理且不属于可重试类别的解析异常时，系统会在返回错误前尝试提交已转换的待写入数据，是否写入取决于提交结果。
+
+#### 4.3.3 典型场景
+
+| **文件情况** | **处理行为** | **预期结果** |
+| :--- | :--- | :--- |
+| 中间设备的某个测点损坏 | 回退为查询方式，必要时拆分测点组 | 尽量保留此前数据，继续同设备其他测点及后续设备的导入 |
+| 首个非对齐设备的某个测点损坏 | 尝试查询首个设备的其他测点和后续设备 | 不因首个设备的局部损坏直接放弃后续可读取数据 |
+| 宽对齐设备中个别测点损坏 | 拆分查询的测点列表，跳过无法读取的单测点任务 | 尽量导入未损坏测点的数据 |
+| 已完成部分测点后才发生损坏 | 根据已完成测点和输出时间戳衔接查询 | 减少对已经输出数据的重复读取 |
+| 元数据也损坏，无法建立回退任务 | 返回失败，并尝试提交已转换的待写入数据 | 已提交的数据保留，待写入数据是否写入取决于提交结果 |
+
+例如，一个非对齐文件依次包含 `d0`、`d1`、`d2` 三个设备，每个设备有 `s0`、`s1` 两个测点。如果 `d1.s1` 的数据块损坏，系统会尽量保留此前已提交的数据，尝试读取 `d1` 的剩余数据，并继续导入 `d2`。`d1.s1` 无法读取的部分可能缺失，具体恢复范围取决于实际损坏位置。
+
+**返回成功表示转换和写入流程按当前容错规则完成，不表示损坏文件中的全部数据均已导入。**