morningman commented on a change in pull request #1488: Add administrator guide of load URL: https://github.com/apache/incubator-doris/pull/1488#discussion_r304205982
########## 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 + + 导入任务可被设定的最大/小超时时间（以秒为单位），用户自定义的导入超时时间不可大于/小于这个值。该值适配于所有的导入方式。用户也可以通过修改 FE 的配置项 ```max_load_timeout_second``` 和 ```min_load_timeout_second``` 来修改最大/小超时时间。 + ++ max\_filter\_ratio + + 导入任务的最大容忍率，默认为0容忍，取值范围是0~1。当导入的 filter ratio 超过该值，则导入失败。计算公式为： ``` (dpp.abnorm.ALL / (dpp.abnorm.ALL + dpp.norm.ALL ) )> max_filter_ratio ``` + + ``` dpp.abnorm.ALL ``` 在代码中也叫 ``` num_rows_filtered``` 指的是导入过程中被过滤的错误数据。比如：列在表中为非空列，但是导入数据为空则为错误数据。可以通过 ``` SHOW LOAD ``` 命令查询导入任务的错误数据量。 + + ``` dpp.norm.ALL ``` 指的是导入过程中正确数据的条数。可以通过 ``` SHOW LOAD ``` 命令查询导入任务的正确数据量。 + + ``` num_rows_unselected ``` 导入过程中被 where 条件过滤掉的数据量。过滤的数据量不参与容忍率的计算。 + + ``` 原始文件的行数 = dpp.abnorm.ALL + dpp.norm.ALL + num_rows_unselected ``` + ++ exec\_mem\_limit + + 导入任务的内存使用上限。当导入任务使用的内存超过设定上限时，导入任务会被 CANCEL。系统默认的内存上限为2G。 + + 设定导入任务内存上限，可以保证各个导入任务之间以及导入任务和查询之间相互不影响。导入任务的内存上限不宜过大，过大可能会导致导入占满 be 内存，查询无法快速返回结果。 + + ```导入任务内存使用量 < 文件大小 / 当前执行导入任务的并发数``` + +## 查看导入 +用户提交成功导入后，可通过查看导入命令获取导入状态，以及详细信息。对于异步的导入方式来说，用户必须在提交导入后，异步查看导入进度。在 SHOW LOAD 中导入状态改为 FINISHED 时，导入才算完成。用户也可以通过该方式查看导入失败的原因，以及导入的各项指标。 + +执行 ``` HELP SHOW LOAD``` 查看不同导入方式的语法帮助。 + ++ JobId + + 导入任务的唯一标识，每个导入任务的JobId都不同。与 Label 不同的是，JobId永远不会相同，而 Label 则可以在导入任务失败后被复用。 + ++ Label + + 导入任务的标识。 + ++ State + + 导入任务当前所处的阶段。流程中的每个阶段都可能出现在 State 中，但每个阶段不是必须出现在 State中。导入任务的最终阶段有两个： CANCELLED 和 FINISHED，当 Load job 处于这两个阶段时，导入完成。其中 CANCELLED 为导入失败，FINISHED 为导入成功。 + ++ Progress + + 导入任务的进度描述。分为两种进度：ETL 和 LOAD，对应了导入流程的两个阶段 ETL 和 LOADING。如果导入中没有进行某个阶段或者导入方式不存在某个节点的进度，则显示为 ```N/A```。 + + 导入的进度范围：0~100%。 + + *注：如果 Progress 显示 LOAD:99% 但是 State 还不是 FINISHED，这时候导入进行到最后的数据生效阶段。* + ++ Type + + 导入任务的类型。目前导入任务分为: BROKER, MINI, MULTI, INSERT, HADOOP, DELETE。其中除 DELETE 外其他均分别代表一种导入方式。 + ++ EtlInfo + + 主要显示了导入的数据量指标 ``` dpp.norm.ALL 和 dpp.abnorm.ALL```。用户可以根据这两个指标验证当前导入任务的 filter ratio 是否超过 max\_filter\_ratio. + ++ TaskInfo + + 主要显示了当前导入任务的属性，包括：cluster，timeout和max\_filter\_ratio。 + ++ ErrorMsg + + 在导入任务状态为CANCELLED，会显示失败的原因，显示分两部分：type和msg，如果导入任务成功则显示 ```N/A```。 + + ``` + type的取值意义 + USER_CANCEL: 用户取消的任务 + ETL_RUN_FAIL：在ETL阶段失败的导入任务 + ETL_QUALITY_UNSATISFIED：数据质量不合格，也就是错误数据率超过了 max_filter_ratio + LOAD_RUN_FAIL：在LOADING阶段失败的导入任务 + TIMEOUT：导入任务没在超时时间内完成 + UNKNOWN：未知的导入错误 + + ``` + + ++ CreateTime/EtlStartTime/EtlFinishTime/LoadStartTime/LoadFinishTime + + 这几个值分别代表导入创建的时间，ETL阶段开始的时间，ETL阶段完成的时间，Loading阶段开始的时间和整个导入任务完成的时间。 + + 导入任务长时间停留在CreateTime，其余时间均为 N/A 则说明目前导入任务堆积严重。用户可减少导入提交的频率。 + + ``` + LoadFinishTime - CreateTime = 整个导入任务所消耗时间 + LoadFinishTime - EtlStartTime = 整个导入任务执行时间 = 整个导入任务所消耗时间 - 导入任务等待的时间 + ``` + ++ URL + + 导入任务的错误数据样例，访问 URL 地址既可获取本次导入的错误数据样例。当本次导入不存在错误数据时，URL 字段则为 N/A。 + + +## 取消导入 Review comment: 并不是所有导入都可以取消 ---------------------------------------------------------------- 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: [email protected] With regards, Apache Git Services --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
