You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@doris.apache.org by GitBox <gi...@apache.org> on 2019/07/27 15:11:17 UTC
[GitHub] [incubator-doris] morningman commented on a change in pull request
#1558: Modify load docs
morningman commented on a change in pull request #1558: Modify load docs
URL: https://github.com/apache/incubator-doris/pull/1558#discussion_r307968036
##########
File path: docs/documentation/cn/administrator-guide/load-data/broker-load-manual.md
##########
@@ -1,386 +1,451 @@
# Broker Load
-Broker load 是一个异步的导入方式，主要支持的数据源有 HDFS, BOS, AFS。用户需要通过 Mysql client 创建 Broker load 导入，并通过查看导入命令检查导入结果。
-Broker load 主要适用于源数据在文件系统中的，或者是超大文件导入的需求。
+Broker load 是一个异步的导入方式，支持的数据源取决于 Broker 进程支持的数据源。
-# 名词解释
-1. HDFS: Hadoop 分布式文件系统。用户的待导入数据可能存放的位置。
-2. BOS：百度云提供的对象存储系统，百度云上的 Palo 用户的待导入数据可能存放的位置。
-3. AFS：百度内部提供的超大规模文件系统，百度厂内的 Palo 用户的待导入数据可能存放的位置。
-4. plan：导入执行计划，BE 会执行导入执行计划将数据导入到 Doris 系统中。
-5. Broker：Doris 系统中负责读取外部文件系统数据的组件。
-6. backend（BE）：Doris 系统的计算和存储节点。在导入流程中主要负责数据的 ETL 和存储。
-7. frontend（FE）：Doris 系统的元数据和调度节点。在导入流程中主要负责导入 plan 生成和导入任务的调度工作。
+用户需要通过 MySQL 协议 创建 Broker load 导入，并通过查看导入命令检查导入结果。
-# 基本原理
+## 适用场景
-用户在提交导入任务后，FE 会生成对应的 plan 并根据目前 BE 的个数和文件的大小，将 plan 分给 多个 BE 执行，每个 BE 执行一部分导入数据。
+* 源数据在 Broker 可以访问的存储系统中，如 HDFS。
+* 数据量在 几十到百GB 级别。
-BE 在执行的过程中会从 Broker 拉取数据，在对数据 transform 之后将数据导入系统。所有 BE 均完成导入，并且事务被 publish 后，导入完成。
+## 名词解释
+
+1. Frontend（FE）：Doris 系统的元数据和调度节点。在导入流程中主要负责导入 plan 生成和导入任务的调度工作。
+2. Backend（BE）：Doris 系统的计算和存储节点。在导入流程中主要负责数据的 ETL 和存储。
+3. Broker：Broker 为一个独立的无状态进程。封装了文件系统接口，提供 Doris 读取远端存储系统中文件的能力。
+4. Plan：导入执行计划，BE 会执行导入执行计划将数据导入到 Doris 系统中。
+
+## 基本原理
+
+用户在提交导入任务后，FE 会生成对应的 Plan 并根据目前 BE 的个数和文件的大小，将 Plan 分给 多个 BE 执行，每个 BE 执行一部分导入数据。
+
+BE 在执行的过程中会从 Broker 拉取数据，在对数据 transform 之后将数据导入系统。所有 BE 均完成导入，由 FE 最终决定导入是否成功。
```
+
- | user create broker load
+ | 1. user create broker load
v
+----+----+
| |
| FE |
| |
+----+----+
|
- | BE etl and load the data
+ | 2. BE etl and load the data
+--------------------------+
| | |
+---v---+ +--v----+ +---v---+
| | | | | |
| BE | | BE | | BE |
| | | | | |
-+---+---+ +---+---+ +----+--+
- | | |
- | | | pull data from broker
-+---v---+ +---v---+ +----v--+
++---+-^-+ +---+-^-+ +--+-^--+
+ | | | | | |
+ | | | | | | 3. pull data from broker
++---v-+-+ +---v-+-+ +--v-+--+
| | | | | |
|Broker | |Broker | |Broker |
| | | | | |
-+-------+--+ +---+---+ ++------+
- | | |
- | | |
- +-v------v---------v--+
- |HDFS/BOS/AFS cluster |
- | |
- +---------------------+
++---+-^-+ +---+-^-+ +---+-^-+
+ | | | | | |
++---v-+-----------v-+----------v-+-+
+| HDFS/BOS/AFS cluster |
+| |
++----------------------------------+
```
-# 基本操作
-## 创建导入
+## 基本操作
+
+### 创建导入
Broker load 创建导入语句
-```
-语法
-LOAD LABEL load_label
- (data_desc, ...)
- with broker broker_name broker_properties
- [PROPERTIES (key1=value1, ... )]
+语法：
-LABEL: db_name.label_name
+```
+LOAD LABEL db_name.label_name
+(data_desc, ...)
+WITH BROKER broker_name broker_properties
+[PROPERTIES (key1=value1, ... )]
-data_desc:
- DATA INFILE ('file_path', ...)
- [NEGATIVE]
- INTO TABLE tbl_name
- [PARTITION (p1, p2)]
- [COLUMNS TERMINATED BY separator ]
- [(col1, ...)]
- [SET (k1=f1(xx), k2=f2(xx))]
+* data_desc:
-broker_name: string
+ DATA INFILE ('file_path', ...)
+ [NEGATIVE]
+ INTO TABLE tbl_name
+ [PARTITION (p1, p2)]
+ [COLUMNS TERMINATED BY separator ]
+ [(col1, ...)]
+ [SET (k1=f1(xx), k2=f2(xx))]
-broker_properties: (key1=value1, ...)
+* broker_properties:
+ (key1=value1, ...)
+```
示例：
-load label test.int_table_01
- (DATA INFILE("hdfs://abc.com:8888/user/palo/test/ml/id_name") into table id_name_table columns terminated by "," (tmp_c1,tmp_c2) set (id=tmp_c2, name=tmp_c1))
- with broker 'broker' ("username"="root", "password"="3trqDWfl")
- properties ("timeout" = "10000" );
+
+```
+LOAD LABEL db1.label1
+(
+ DATA INFILE("hdfs://abc.com:8888/user/palo/test/ml/file1")
+ INTO TABLE tbl1
+ COLUMNS TERMINATED BY ","
+ (tmp_c1,tmp_c2)
+ SET
+ (
+ id=tmp_c2,
+ name=tmp_c1)
+ ),
+ DATA INFILE("hdfs://abc.com:8888/user/palo/test/ml/file2")
+ INTO TABLE tbl2
+ COLUMNS TERMINATED BY ","
+ (col1, col2)
+)
+WITH BROKER 'broker'
+(
+ "username"="user",
+ "password"="pass"
+)
+PROPERTIES
+(
+ "timeout" = "3600"
+);
```
-创建导入的详细语法执行 ``` HELP BROKER LOAD；``` 查看语法帮助。这里主要介绍 Broker load 的创建导入语法中参数意义和注意事项。
+创建导入的详细语法执行 ```HELP BROKER LOAD``` 查看语法帮助。这里主要介绍 Broker load 的创建导入语法中参数意义和注意事项。
-+ label
+#### Label
- 导入任务的标识。每个导入任务，都有一个在单 database 内部唯一的 label。label 是用户在导入命令中自定义的名称。通过这个 label，用户可以查看对应导入任务的执行情况。
-
- label 的另一个作用，是防止用户重复导入相同的数据。**强烈推荐用户同一批次数据使用相同的label。这样同一批次数据的重复请求只会被接受一次，保证了 At most once**
-
- 当 label 对应的导入作业状态为 CANCELLED 时，该 label 可以再次被使用。
+导入任务的标识。每个导入任务，都有一个在单 database 内部唯一的 Label。Label 是用户在导入命令中自定义的名称。通过这个 Label，用户可以查看对应导入任务的执行情况。
+
+Label 的另一个作用，是防止用户重复导入相同的数据。**强烈推荐用户同一批次数据使用相同的label。这样同一批次数据的重复请求只会被接受一次，保证了 At-Most-Once 语义**
+
+当 Label 对应的导入作业状态为 CANCELLED 时，可以再次使用该 Label 提交导入作业。
-### 数据描述类参数
+#### 数据描述类参数
数据描述类参数主要指的是 Broker load 创建导入语句中的属于 ```data_desc``` 部分的参数。每组 ```data_desc ``` 主要表述了本次导入涉及到的数据源地址，ETL 函数，目标表及分区等信息。
下面主要对数据描述类的部分参数详细解释：
-+ 多表导入
++ 多表导入
- Broker load 支持一次导入任务涉及多张表，每个 Broker load 导入任务可在多个 ``` data_desc ``` 声明多张表来实现多表导入。每个单独的 ```data_desc``` 还可以指定属于该表的数据源地址。Broker load 保证了单次导入的多张表之间原子性成功或失败。
+ Broker load 支持一次导入任务涉及多张表，每个 Broker load 导入任务可在多个 ``` data_desc ``` 声明多张表来实现多表导入。每个单独的 ```data_desc``` 还可以指定属于该表的数据源地址。Broker load 保证了单次导入的多张表之间原子性成功或失败。
-+ negative
++ negative
- ```data_desc```中还可以设置数据取反导入。这个功能主要用于，当用户上次导入已经成功，但是想取消上次导入的数据时，就可以使用相同的源文件并设置导入 nagetive 取反功能。上次导入的数据就可以被撤销了。
+ ```data_desc```中还可以设置数据取反导入。这个功能主要用于，当数据表中聚合列的类型都为 SUM 类型时。如果希望撤销某一批导入的数据。则可以通过 `negative` 参数当如同一批数据。Doris 会自动为这一批数据在聚合列上数据取反，以达到消除同一批数据的功能。
+
++ partition
- 该功能仅对聚合类型为 SUM 的列有效。聚合列数值在取反导入后会根据待导入数据值，不断递减。
-
-+ Partition
+ 在 ```data_desc``` 中可以指定待导入表的 partition 信息，如果待导入数据不属于指定的 partition 则不会被导入。同时，不在指定 Partition 的数据会被认为是错误数据。
+
+#### 导入作业参数
- 在 ``` data_desc ``` 中可以指定待导入表的 Partition 信息，如果待导入数据不属于指定的 Partition 则不会被导入。这些数据将计入 ```dpp.abnorm.ALL ```
-
-### 导入任务参数
+导入作业参数主要指的是 Broker load 创建导入语句中的属于 ```opt_properties```部分的参数。导入作业参数是作用于整个导入作业的。
-导入任务参数主要指的是 Broker load 创建导入语句中的属于 ```opt_properties```部分你的参数。导入任务参数是作用于整个导入任务的。
-
-下面主要对导入任务参数的部分参数详细解释：
+下面主要对导入作业参数的部分参数详细解释：
+ timeout
-
- 导入任务的超时时间(以秒为单位)，用户可以在```opt_properties```中自行设置每个导入的超时时间。导入任务在设定的 timeout 时间内未完成则会被系统取消，变成 CANCELLED。Broker load 的默认导入超时时间为4小时。
-
- 通常情况下，用户不需要手动设置导入任务的超时时间。当在默认超时时间内无法完成导入时，可以手动设置任务的超时时间。
-
- **推荐超时时间**
-
- ```
- 总文件大小（MB） / 用户 Doris 集群最慢导入速度(MB/s) > timeout > （（总文件大小(MB) * 待导入的表及相关 Roll up 表的个数） / (10 * 导入并发数） ）
-
- 导入并发数见文档最后的导入系统配置说明，公式中的 10 为目前的导入限速 10MB/s。
-
- ```
-
- 例如一个 1G 的待导入数据，待导入表涉及了3个 Roll up 表，当前的导入并发数为 3。则 timeout 的 最小值为 ```(1 * 1024 * 3 ) / (10 * 3) = 102 秒```
-
- 由于每个 Doris 集群的机器环境不同且集群并发的查询任务也不同，所以用户 Doris 集群的最慢导入速度需要用户自己根据历史的导入任务速度进行推测。
-
- *注意：用户设置导入超时时间最好在上述范围内。如果设置的超时时间过长，可能会导致总导入任务的个数超过 Doris 系统限制，导致后续提交的导入被系统取消*
-
+
+ 导入作业的超时时间(以秒为单位)，用户可以在 ```opt_properties``` 中自行设置每个导入的超时时间。导入任务在设定的 timeout 时间内未完成则会被系统取消，变成 CANCELLED。Broker load 的默认导入超时时间为4小时。
+
+ 通常情况下，用户不需要手动设置导入任务的超时时间。当在默认超时时间内无法完成导入时，可以手动设置任务的超时时间。
+
+ > 推荐超时时间
+ >
+ > 总文件大小（MB） / 用户 Doris 集群最慢导入速度(MB/s) > timeout > （（总文件大小(MB) * 待导入的表及相关 Roll up 表的个数） / (10 * 导入并发数） ）
+
+ > 导入并发数见文档最后的导入系统配置说明，公式中的 10 为目前的导入限速 10MB/s。
+
+ > 例如一个 1G 的待导入数据，待导入表包含3个 Rollup 表，当前的导入并发数为 3。则 timeout 的 最小值为 ```(1 * 1024 * 3 ) / (10 * 3) = 102 秒```
+
+ 由于每个 Doris 集群的机器环境不同且集群并发的查询任务也不同，所以用户 Doris 集群的最慢导入速度需要用户自己根据历史的导入任务速度进行推测。
+
+ 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 ``` 命令查询导入任务的正确数据量。
-
- ``` 原始文件的行数 = dpp.abnorm.ALL + dpp.norm.ALL ```
-
+ 导入任务的最大容忍率，默认为0容忍，取值范围是0~1。当导入的错误率超过该值，则导入失败。
+
+ 如果用户希望忽略错误的行，可以通过设置这个参数大于 0，来保证导入可以成功。
+
+ 计算公式为：
+
+ ``` (dpp.abnorm.ALL / (dpp.abnorm.ALL + dpp.norm.ALL ) ) > max_filter_ratio ```
+
+ ```dpp.abnorm.ALL``` 表示数据质量不合格的行数。如类型不匹配，列数不匹配，长度不匹配等等。
+
+ ```dpp.norm.ALL``` 指的是导入过程中正确数据的条数。可以通过 ```SHOW LOAD``` 命令查询导入任务的正确数据量。
+
+ 原始文件的行数 = `dpp.abnorm.ALL + dpp.norm.ALL`
+
+ exec\_mem\_limit
- 导入任务的内存使用上限。当导入任务使用的内存超过设定上限时，导入任务会被 CANCEL。系统默认的内存上限为2G。
-
- 设定导入任务内存上限，可以保证各个导入任务之间以及导入任务和查询之间相互不影响。导入任务的内存上限不宜过大，过大可能会导致导入占满 be 内存，查询无法快速返回结果。
-
- ```导入任务内存使用量 < 文件大小 / 当前执行导入任务的并发数```
-
-+ strict mode
+ 导入任务的内存使用上限。当导入任务使用的内存超过设定上限时，导入任务会被 CANCEL。默认为 2G，单位为字节。
+
+ 当导入出现 `Memory exceed limit` 错误时，可以适当调整这个参数，如调整为 4G、8G 等。
- Broker load 导入可以开启 strict mode模式。开启方式为 ```properties ("strict_mode" = "true")``` 。默认的 strict mode为开启。
++ strict\_mode
- strict mode模式的意思是：对于导入过程中的列类型转换进行严格过滤。严格过滤的策略如下：
+ Broker load 导入可以开启 strict mode 模式。开启方式为 ```properties ("strict_mode" = "true")``` 。默认的 strict mode 为开启。
- 1. 对于列类型转换来说，如果 strict\_mode 为true，则错误的数据将被 filter。这里的错误数据是指：原始数据并不为空值，在参与列类型转换后结果为空值的这一类数据。
+ strict mode 模式的意思是：对于导入过程中的列类型转换进行严格过滤。严格过滤的策略如下：
- 2. 对于导入的某列包含函数变换的，导入的值和函数的结果一致，strict 对其不产生影响。（其中 strftime 等 Broker load 支持的函数也属于这类）。
+ 1. 对于列类型转换来说，如果 strict mode 为true，则错误的数据将被 filter。这里的错误数据是指：原始数据并不为空值，在参与列类型转换后结果为空值的这一类数据。
- 3. 对于导入的某列类型包含范围限制的，如果原始数据能正常通过类型转换，但无法通过范围限制的，strict 对其也不产生影响。
- + 例如：如果类型是 decimal(1,0), 原始数据为10，则属于可以通过类型转换但不在列声明的范围内。这种数据 strict 对其不产生影响。
+ 2. 对于导入的某列由函数变换生成时，strict mode 对其不产生影响。
+
+ 3. 对于导入的某列类型包含范围限制的，如果原始数据能正常通过类型转换，但无法通过范围限制的，strict mode 对其也不产生影响。例如：如果类型是 decimal(1,0), 原始数据为 10，则属于可以通过类型转换但不在列声明的范围内。这种数据 strict 对其不产生影响。
- #### strict mode 与 source data 的导入关系
+#### strict mode 与 source data 的导入关系
Review comment:
嗯 这个问题，主要是因为，sphnix 的文档框架，不支持缩进的表格。。所以这个小结中那个strict 示例的表格，只能顶头放，这样就导致这个小结不得不也顶头，所以直接再开一个4级标题了。。。
----------------------------------------------------------------
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