[GitHub] [incubator-doris] morningman commented on a change in pull request #1488: Add administrator guide of load

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

morningman commented on a change in pull request #1488:  Add administrator guide of load
URL: https://github.com/apache/incubator-doris/pull/1488#discussion_r304205458
 
 

 ##########
 File path: docs/documentation/cn/administrator-guide/load-data/load-manual.md
 ##########
 @@ -0,0 +1,256 @@
+# 导入
+导入（Load）功能就是将用户的原始数据导入到 Doris 中。导入成功后，用户即可通过 Mysql 客户端查询数据。
+
+本文档主要介绍导入简单原理，目前支持的几种导入方式，以及最佳实践。
+
+# 基本概念
+
+1. 导入任务（Load job）：导入任务读取用户提交的源数据，转换或清洗后，将数据导入到 Doris 系统中。导入完成后，数据即可被用户查询到。
+2. backend（BE）：Doris 系统的计算和存储节点。在导入流程中主要负责数据的 ETL 和存储。
+3. frontend（FE）：Doris系统的元数据和调度节点。在导入流程中主要负责导入规划生成和导入任务的调度工作。 
+
+# 基本原理
+## 导入执行流程
+
+```
++---------+      +---------+      +----------+      +-----------+
+|         |      |         |      |          |      |           |
+|PENDING  +----->+ETL      +----->+LOADING   +----->+FINISHED   |
+|         |      |         |      |          |      |           |
++---------+      +---+-----+      +----+-----+      +-----------+
+                     |                 |
+                     |                 |
+                     |                 |
+                     |                 |            +-----------+
+                     |                 |            |           |
+                     +-----------------+------------>CANCELLED  |
+                                                    |           |
+                                                    +-----------+
+
+```
+
+如上图，导入流程主要经过上面4个阶段。其中 PENDING 和 ETL 阶段不是必须的阶段。
+
++ PENDING: 该阶段只有 Broker load 才有。Broker load 被用户提交后会短暂停留在这个阶段，直到被 FE 中的 Scheduler 调度。 其中 Scheduler 的调度间隔为5秒。 
+
++ ETL： 该阶段在版本0.11.0(包含)之前存在，主要是用于将原始数据按照用户声明的 transform 方式进行变换，并且过滤不满足条件的原始数据。在 0.11.0 后的版本，ETL 阶段不再存在，其中数据 transform 的工作被合并到 LOADING 阶段。
+
+
++ LOADING： 该阶段在版本0.11.0（包含）之前主要用于将变换后的数据推到对应的 BE 存储中。在0.11.0后的版本，该阶段先对数据进行 ETL 清洗和变换，然后将数据发送到 BE 存储中。当所有导入数据均完成 LOADING 后，Load job 会被 commit。
+
+
++ FINISHED： 在 Load job 完成 commit 后，数据全部生效 Load job 被标记为 FINISHED。FINISHED 后导入的数据均可查询。
+
+
++ CANCELLED: 在 ETL 或者 LOADING 的过程中，如果发生数据质量不合格等问题，Load Job 会被系统 cancel，本次导入会全部失败。当然，用户也可以手动取消 Load Job。CANCELLED 也是 Load Job 的最终状态，不可被再次执行。
+
+
+上述阶段，除了 PENDING 到 LOADING 阶段是 Scheduler 轮训调度的，其他阶段之前的转移都是回调机制实现。
+
+# 导入相关配置
++ max\_load\_timeout\_second 和 min\_load\_timeout\_second
+	
+	这两个配置含义为：最大的导入超时时间，最小的导入超时时间。用户自定义的导入超时时间不可超过这个范围。该参数通用于所有的导入方式。
+	
++ desired\_max\_waiting\_jobs
+
+	在等待队列中的导入任务个数最大值，默认为100。当在 FE 中处于 PENDING 状态（也就是等待执行的）导入个数超过该值，新的导入请求则会被拒绝。
+
+# 基本操作
+## 创建导入
+用户提交导入任务，并且设置导入任务的参数。用户提交导入任务后，根据不同的导入方式，导入任务会被异步或同步的执行。
+
+同步执行的导入比如：Stream load，任务会直接进入LOADING阶段。异步执行的导入方式比如： Broker load，任务会先进入PENDING阶段。
+
+执行 ``` HELP BROKER LOAD;/ HELP MINI LOAD;/ HELP STREAM LOAD;/ HELP MULTI LOAD；``` 查看不同导入方式的语法帮助。
+
+这里主要介绍了创建导入用到的详细参数和意义。
+
++ label
+
+	导入任务的标识。每个导入任务，都有一个在单 database 内部唯一的 label。该 label 可能是用户在导入命令中自定义的名称，也可能是某些命令执行后，系统生成并返回给用户的。通过这个 label，用户可以查看对应导入任务的执行情况。
+	
+	label 的另一个作用，是防止用户重复导入相同的数据。**强烈推荐用户同一批次数据使用相同的label。这样同一批次数据的重复请求只会被接受一次，保证了 At most once**
+	
+	当 label 对应的导入作业状态为 CANCELLED 时，该 label 可以再次被使用。
+
++ timeout
+	
+	导入任务的超时时间(以秒为单位)，用户可以在创建导入的命令中自行设置每个导入的超时时间。导入任务在设定的 timeout 时间内未完成则会被系统取消，变成 CANCELLED。
+	
+	通常情况下，用户不需要手动设置导入任务的超时时间。每种导入任务都有默认的导入超时时间(具体见各个)。当在默认超时时间内无法完成导入时，可以手动设置任务的超时时间。(具体每种导入的默认超时配置见每种导入的操作手册)
+	
+	
+	**推荐超时时间**
+	```（总文件大小(MB) / 10 * 待导入的表及相关Roll up表的个数）* 10 > timeout > （总文件大小(MB) / 10 * 待导入的表及相关Roll up表的个数） ``` 其中10为目前的导入限速 10MB/s。
+	
+	*注意：用户设置导入超时时间最好在上述范围内。如果设置的超时时间过长，可能会导致大量导入任务堆积而耗尽 FE 的内存。*
+	
++ max/min\_load\_timeout\_second
 
 Review comment:
   你在这里 介绍的 min_load_timeout_second 这些是修改 fe.conf，而max_filter_ratio这些又是在load stmt 中指定，放在一起，会对用户产生困扰。
   建议所有的stmt 中的参数，直接放到各自手册中，这里只统一介绍 conf 中的相关系统级配置

----------------------------------------------------------------
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