docs: update application docs

docs/zh/25-application/_03-immigrate.md → docs/zh/25-application/03-immigrate.md

@@ -170,11 +170,110 @@ TDengine 支持标准的 JDBC 3.0 接口操纵数据库，你也可以使用其
 
 ### 1、使用工具自动迁移数据
 
-为了方便历史数据的迁移工作，我们为数据同步工具 DataX 提供了插件，能够将数据自动写入到 TDengine 中，需要注意的是 DataX 的自动化数据迁移只能够支持单值模型的数据迁移过程。
-
-DataX 具体的使用方式及如何使用 DataX 将数据写入 TDengine 请参见[基于 DataX 的 TDengine 数据迁移工具](https://www.taosdata.com/engineering/16401.html)。
-
-在对 DataX 进行迁移实践后，我们发现通过启动多个进程，同时迁移多个 metric 的方式，可以大幅度的提高迁移历史数据的效率，下面是迁移过程中的部分记录，希望这些能为应用迁移工作带来参考。
+为了方便历史数据的迁移工作，我们为数据同步工具 DataX 提供了适配 TDengine 3.0 的插件，能够将数据自动写入到 TDengine 中，需要注意的是 DataX 的自动化数据迁移只能够支持单值模型的数据迁移过程。
+
+#### 1.0 插件功能介绍
+1. TDengine30Reader 提供的功能：
+   1. 支持通过 SQL 进行数据筛选；
+   2. 根据时间间隔进行任务切分；
+   3. 支持 TDengine 的全部数据类型；
+   4. 支持批量读取，通过 batchSize 参数控制批量拉取结果集的大小，提高读取性能。
+2. TDengine30Writer 支持的功能：
+   1. 支持 OpenTSDB 的 json 格式的行协议，使用 TDengine 的 schemaless 方式写入 TDengine。
+   2. 支持批量写入，通过 batchSize 参数控制批量写入的数量，提高写入性能。
+
+#### 1.1 DataX 安装环境准备
+1. 需要安装 TDengine 客户端
+2. 需要安装 JDK 1.8 环境（运行 DataX）
+3. 需要安装 Python 环境（运行 DataX）
+4. 需要 maven 编译环境（如果不编译 DataX 则可以不安装 maven）
+
+#### 1.2 安装
+1. 下载源码
+~~~
+git clone https://github.com/taosdata/DataX.git
+~~~
+2. 编译打包
+~~~
+cd DataX
+mvn -U clean package assembly:assembly -Dmaven.test.skip=true
+~~~
+3. 安装
+~~~
+cp target/datax.tar.gz your_install_dir
+cd your_install_dir
+tar -zxvf dataX.tar.gz
+~~~
+
+#### 1.3 数据迁移 Job 的配置
+以一个从 OpenTSDB 到 TDengine 3.0 版本的数据迁移任务为例，配置文件 opentsdb2tdengine.json 如下：
+~~~
+{
+   "job":{
+     "content":[{
+       "reader": {
+         "name": "opentsdbreader",
+         "parameter": {
+           "endpoint": "http://192.168.1.180:4242",
+           "column": ["weather_temperature"],
+           "beginDateTime": "2021-01-01 00:00:00",
+           "endDateTime": "2021-01-01 01:00:00"
+         }
+       },
+     "writer": {
+       "name": "tdengine30writer",
+       "parameter": {
+            "username": "root",
+            "password": "taosdata",
+            "connection": [
+              {
+                "table": [
+                  "matric1"
+                ],
+                "jdbcUrl": "jdbc:TAOS://192.168.1.101:6030/test?timestampFormat=TIMESTAMP"
+              }
+            ],
+            "batchSize": 1000,
+            "ignoreTagsUnmatched": true
+          }
+       }
+     }],
+     "setting": {
+       "speed": {
+         "channel": 1
+       }
+     }
+   }
+ } 
+~~~
+配置说明：
+1. 上面的配置表示，从 192.168.1.180 的 OpenTSDB，到 192.168.1.101 的 TDengine 的迁移。迁移 metric 为 weather_temperature，时间从 2021-01-01 00:00:00 开始，到 2021-01-01 01:00:00 结束的数据。
+2. reader 使用 datax 的 opentsdbreader，parameter 的配置请参考：[opentsdbreader.md#配置参数](https://github.com/taosdata/DataX/blob/master/opentsdbreader/doc/opentsdbreader.md)
+3. tdengine30writer 的 parameter 中，user，password 为必须项，没有默认值。batchSize 不是必须项，默认值为 1。详细参考：[tdengine30writer.md#配置参数](https://github.com/taosdata/DataX/blob/master/tdengine30writer/doc/tdengine30writer-CN.md)
+4. TDengine 中，如果 dbname 指定的 database 不存在，则需要在迁移前创建数据库。
+
+#### 1.4 执行迁移任务
+~~~
+python bin/datax.py job/opentsdb2tdengine.json
+~~~
+
+#### 1.5 限制条件
+1. 目前，DataX 自带的 opentsdbreader 仅支持 OpenTSDB-2.3.X 版本。详细参考：[opentsdbreader#约束限制](https://github.com/alibaba/DataX/blob/master/opentsdbreader/doc/opentsdbreader.md#5-%E7%BA%A6%E6%9D%9F%E9%99%90%E5%88%B6)
+2. 数据迁移工具依赖 TDengine 客户端中的 `libtaos.so/taos.dll/libtaos.dylib`，需要与服务端对应版本的 TDengine-client。
+
+#### 1.6 其他
+1. FAQ
+   1. 如何估算一个数据迁移任务所需要的资源
+   DataX 的每个 reader 按照自己的 task 切分策略进行任务划分，具体请参考 DataX 的任务调度规则。在估算资源是，需要按照数据迁移的数据量，任务切分规则和网络带宽限制等综合考虑，最好以实际数据迁移测试结果为准。
+   2. TDengine30Writer 的 batchSize 设置多大效率最高？
+   batchSize 是控制批量写入的参数，在获取 batchSize 行纪录后，TDengineWriter 会向 TDengine 发送一次写入请求，这减少了与 TDengine 交互次数，从而提高了性能。从测试结果来看，batchSize 在 500-1000 范围内效率最高。
+   3. job 的配置中 channel 数为多少合适？
+   job 中的 channel 数为流量控制的参数，每个 channel 都需要开辟一块内存，用来缓存数据。如果 channel 设置过大，会引起 OOM，所以 channel 数并不是越大越好。增加 channel 数后，需要提高 JVM 内存大小。从测试结果来看，channel 在 1～6 的范围内都是合适，能够保证 DataX 的流量最大化即可。
+   4. java.sql.SQLException: TDengine ERROR (8000060b): Invalid client value
+   配置文件中 column 中没有配置 tbname，此时会触发行协议数据写入（行协议写入只会自动创建子表名，但需要提前创建好超级表），行协议写入的情况下不支持 TAG 数据类型为非 NCHAR，所以此种情况有两种解决方案：1.将 TAG 全部修改为 NCHAR 类型；2.在 Column 中配置好表名称这样不会触发行协议写入。
+   5. java.sql.SQLException: TDengine ERROR (8000060b): Timestamp data out of range
+   配置文件中 column 中没有配置 tbname，此时会触发行协议数据写入，且 TAG 全部为 NCHAR 类型，此时需要保证时间戳的一列名称为 _ts，而不能是其他名称（行协议写入下，默认将最后的时间戳写入到 _ts 一列，且不能随意命名）。若想避免请使用 tbname 指定表名以避免触发行协议写入。
+2. 在对 DataX 进行迁移实践后，我们发现通过启动多个进程，同时迁移多个 metric 的方式，可以大幅度的提高迁移历史数据的效率，下面是迁移过程中的部分记录，希望这些能为应用迁移工作带来参考。
 
 | DataX 实例个数 (并发进程个数) | 迁移记录速度 （条/秒) |
 | ----------------------------- | --------------------- |