[GitHub] [incubator-doris] EmmyMiao87 commented on a change in pull request #967: Add routine load manual

[GitBox <gi...@apache.org>]

EmmyMiao87 commented on a change in pull request #967: Add routine load manual
URL: https://github.com/apache/incubator-doris/pull/967#discussion_r276898366
 
 

 ##########
 File path: docs/documentation/cn/administrator-guide/load-data/routine-load-manual.md
 ##########
 @@ -0,0 +1,138 @@
+# 例行导入使用手册
+
+例行导入（Routine Load）功能为用户提供了一种自动从指定数据源进行数据导入的功能。本文档主要介绍该功能的实现原理、使用方式以及最佳实践。
+
+## 名词解释
+
+* FE：Frontend，Doris 的前端节点。负责元数据管理和请求接入。
+* BE：Backend，Doris 的后端节点。负责查询执行和数据存储。
+* RoutineLoadJob：用户提交的一个例行导入作业。
+* JobScheduler：例行导入作业调度器，用于调度和拆分一个 RoutineLoadJob 为多个 Task。
+* Task：RoutineLoadJob 被 JobScheduler 根据规则拆分的子任务。
+* TaskScheduler：任务调度器。用于调度 Task 的执行。
+
+## 原理
+
+```              
+         +---------+
+         |  Client |
+         +----+----+
+              |
++-----------------------------+
+| FE          |               |
+| +-----------v------------+  |
+| |                        |  |
+| |   Routine Load Job     |  |
+| |                        |  |
+| +---+--------+--------+--+  |
+|     |        |        |     |
+| +---v--+ +---v--+ +---v--+  |
+| | task | | task | | task |  |
+| +--+---+ +---+--+ +---+--+  |
+|    |         |        |     |
++-----------------------------+
+     |         |        |
+     v         v        v
+ +---+--+   +--+---+   ++-----+
+ |  BE  |   |  BE  |   |  BE  |
+ +------+   +------+   +------+
+
+```
+
+如上图，Client 向 FE 提交一个例行导入作业。FE 通过 JobScheduler 将一个导入作业拆分成若干个 Task。每个 Task 负责导入指定的一部分数据。Task 被 TaskScheduler 分配到指定的 BE 上执行。在 BE 上，一个 Task 被视为一个普通的导入任务，通过 Stream Load 的导入机制进行导入。导入完成后，向 FE 汇报。FE 中的 JobScheduler 根据汇报结果，继续生成后续新的 Task，或者对失败的 Task 进行重试。整个例行导入作业通过不断的产生新的 Task，来完成数据不间断的导入。
+
+## Kafka 例行导入
+
+当前我们仅支持从 Kafka 系统进行例行导入。该部分会详细介绍 Kafka 例行导入使用方式和最佳实践。
+
+### 使用限制
+
+1. 仅支持无认证的 Kafka 访问。
+2. 支持的消息格式为 csv 文本格式。每一个 message 为一行，且行尾**不包含**换行符。
+3. 仅支持 Kafka 0.10.0.0(含) 以上版本。
+
+### 创建例行导入任务
+
+创建例行导入任务的的详细语法可以参照 [这里]()。或者连接到 Doris 后，执行 `HELP ROUTINE LOAD;` 查看语法帮助。这里主要详细介绍，创建作业时的注意事项。
+
+* columns_mapping
+
+    columns_mapping 主要用于指定表结构和 message 中的列映射关系，以及一些列的转换。如果不指定，Doris 会默认 message 中的列和表结构的列按顺序一一对应。虽然在正常情况下，如果源数据正好一一对应，则不指定也可以进行正常的数据导入。但是我们依然强烈建议用户**显示的指定列映射关系**。这样当表结构发生变化（比如增加一个 nullable 的列），或者源文件发生变化（比如增加了一列）时，导入任务依然可以继续进行。否则，当发生上述变动后，因为列映射关系不再一一对应，导入将报错。
+    
+    在 columns_mapping 中我们同样可以使用一些内置函数进行列的转换。但需要注意函数对应的实际列类型。举例说明：
+    
+    假设用户需要导入只包含 `k1` 一列的表，列类型为 int。并且需要将源文件中的 null 值转换为 0。该功能可以通过 `ifnull` 函数实现。正确是的使用方式如下：
+    
+    `COLUMNS (xx, k1=ifnull(xx, "3"))`
+    
+    注意这里我们使用 `"3"` 而不是 `3`。因为对于导入任务来说，源数据中的列类型都为 `varchar`，所以这里 `xx` 虚拟列的类型也为 `varchar`。所以我们需要使用 `"3"` 来进行对应的匹配，否则 `ifnull` 函数无法找到参数为 `(varchar, int)` 的函数签名，将出现错误。
+
+* desired\_concurrent\_number
+
+    desired_concurrent_number 用于指定一个例行作业期望的并发度。即一个作业，最多有多少 task 同时在执行。对于 Kafka 导入而言，当前的实际并发度计算如下：
+    
+    `Min(partition num / 3, desired_concurrent_number, alive_backend_num)`
 
 Review comment:
   ```suggestion
       `Min(partition num / 3, desired_concurrent_number, alive_backend_num, DEFAULT_TASK_MAX_CONCURRENT_NUM)`
       其中DEFAULT_TASK_MAX_CONCURRENT_NUM是系统的一个默认的最大并发数限制。
   ```

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@doris.apache.org
For additional commands, e-mail: dev-help@doris.apache.org