Skip to content

Commit 5070261

Browse files
EmmyMiao87palo-ci
authored andcommitted
Add administrator guide of load (apache#1488)
The catalogue of load docs: ---- load-manual.md ---- broker-load-manual.md ---- insert-into-manual.md ---- stream-load-manual.md This commit also changes max/min_stream_load_timeout to max/min_load_timeout. The old config named stream_load_timeout means the max timeout suited for all types of load. So the config name has been changed.
1 parent dc32181 commit 5070261

12 files changed

Lines changed: 905 additions & 44 deletions

File tree

‎docs/documentation/cn/administrator-guide/load-data/broker-load-manual.md‎

Lines changed: 360 additions & 17 deletions
Large diffs are not rendered by default.
Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Insert into
2+
3+
Insert into 主要用来将某几行数据插入某张表,或者将已经存在在 Doris 系统中的部分数据导入到目标表中。
4+
5+
目前所有的 Insert into 导入实现均为同步执行。但是为了兼容旧的 Insert into 导入,不指定 STREAMING 的 Insert into 同步执行完后,依然可以通过查看导入命令查看导入状态和结果。
6+
7+
# 基本操作
8+
## 创建导入
9+
10+
Insert into 创建导入请求需要通过 Mysql 协议提交,创建导入请求会同步返回导入结果。
11+
12+
Insert info 创建导入语句
13+
14+
```
15+
语法:
16+
INSERT INTO table_name [partition_info] [col_list] [plan_hints] [query_stmt] [VALUES]
17+
18+
示例:
19+
insert into char_4_new values ("qweasdzxcqweasdzxc"), ("a");
20+
insert into char_4_new select * from char_3_new;
21+
```
22+
23+
下面主要介绍创建导入语句中使用到的参数:
24+
25+
+ query\_stmt
26+
27+
通过一个查询语句,将查询语句的结果导入到 Doris 系统中的其他表。
28+
29+
+ VALUES
30+
31+
用户可以通过 VALUES 语法插入一条或者多条数据。
32+
33+
*注意:VALUES 方式仅适用于导入几条数据作为导入 DEMO 的情况,完全不适用于任何测试和生产环境。Doris 系统本身也不适合单条数据导入的场景。建议使用 Insert into select 的方式进行批量导入。*
34+
35+
+ partition\_info
36+
37+
导入表的目标分区,如果指定目标分区,则只会导入符合目标分区的数据。如果没有指定,则默认值为这张表的所有分区。所有不属于当前目标分区的数据均属于 ``` num_rows_unselected ```,不参与 ``` max_filter_ratio ``` 的计算。
38+
39+
+ col\_list
40+
41+
导入表的目标列,可以以任意的顺序存在。如果没有指定目标列,那么默认值是这张表的所有列。如果待表中的某个列没有存在目标列中,那么这个列需要有默认值,否则 INSERT 就会执行失败。
42+
43+
如果查询语句的结果列类型与目标列的类型不一致,那么会调用隐式类型转化,如果不能够进行转化,那么 INSERT 语句会报语法解析错误。
44+
45+
+ plan\_hints
46+
47+
可指定当前导入的导入方式,目前无论是否指定 hint 导入方式均为同步,用户均可以通过创建导入请求的结果判断导入结果。
48+
49+
唯一不同的是,不指定 STREAMING 的导入方式,由于为了兼容旧的使用习惯,用户依旧可以通过查看导入命令看到导入的结果。但导入实际上已经在创建导入返回结果的时候就已经完成了。
50+
51+
## 导入结果
52+
53+
Insert into 的导入结果也就是创建导入命令的返回值。
54+
55+
指定 plan\_hints 为 STREAMING 的 Insert into 导入直接根据 sql 执行的返回码确定导入是否成功,除了 query 返回 OK 以外,其他均为导入失败。
56+
57+
未指定 plan\_hints 的 Insert into 导入如果导入失败,也是返回 sql 执行失败,如果导入成功还会附加返回一个 Label 字段。
58+
59+
+ Label
60+
61+
导入任务的标识。每个导入任务,都有一个在单 database 内部唯一的 label。Insert into 的 label 则是由系统生成的,用户可以拿着这个 label 通过查询导入命令异步获取导入状态。
62+
63+
*注意:只有不指定 plan\_hints 的 Insert into 才会返回 Label 参数*
64+
65+
# Insert into 系统配置
66+
## FE conf 中的配置
67+
68+
+ timeout
69+
70+
导入任务的超时时间(以秒为单位),导入任务在设定的 timeout 时间内未完成则会被系统取消,变成 CANCELLED。
71+
72+
目前 Insert into 并不支持自定义导入的 timeout 时间,所有 Insert into 导入的超时时间是统一的,默认的 timeout 时间为1小时。如果导入的源文件无法再规定时间内完成导入,则需要调整 FE 的参数```insert_load_default_timeout_second```。
73+
74+
## Session variable 中的配置
75+
76+
+ enable\_insert\_strict
77+
78+
Insert into 导入本身不能设置 ```max_filter_ratio ```,这个参数用来代替错误率限制的功能,可以通过 ``` session variable ``` 设置,默认值为 false。当该参数设置为 false 时,则和```max_filter_ratio = 1 ``` 意义相同。如果该参数设置为 true 时,则和```max_filter_ratio = 0 ``` 意义相同。
79+
80+
# Insert into 最佳实践
81+
## 应用场景
82+
1. 用户希望仅导入几条假数据,验证一下 Doris 系统的功能。此时适合使用 Insert into VALUS 的语法。
83+
2. 用户希望将已经在 Doris 系统中的数据进行 ETL 转换并导入到一个新的 Doris 表中,此时适合使用 Insert into query\_stmt。
84+
85+
除以上两种情况外,其他情况并不适合使用 Insert into
86+
87+
## 数据量
88+
Insert into 对数据量没有限制,大数据量导入也可以支持。但 Insert into 有默认的超时时间,用户预估的导入数据量过大,就需要修改系统的 Insert into 导入超时时间。
89+
90+
```
91+
导入数据量 = 36G 约≤ 3600s * 10M/s
92+
其中 10M/s 是最大导入限速,用户需要根据当前集群情况计算出平均的导入速度来替换公式中的 10M/s
93+
```
94+
95+
## 完成例子
96+
用户有一张表 store_sales 在数据库 sales 中,用户又创建了一张表叫 bj_store_sales 也在数据库 sales 中,用户希望将 store_sales 中销售记录在 bj 的数据导入到这张新建的表 bj_store_sales 中。导入的数据量约为:10G。
97+
98+
```
99+
store_sales schema:
100+
(id, total, user_id, sale_timestamp, region)
101+
102+
bj_store_sales schema:
103+
(id, total, user_id, sale_timestamp)
104+
105+
```
106+
107+
集群情况:用户当前集群的平均导入速度约为 5M/s
108+
109+
+ Step1: 判断是否要修改 Insert into 的默认超时时间
110+
111+
```
112+
计算导入的大概时间
113+
10G / 5M/s = 2000s
114+
115+
修改 FE 配置
116+
insert_load_default_timeout_second = 2000
117+
```
118+
119+
+ Step2:创建导入任务
120+
121+
由于用户是希望将一张表中的数据做 ETL 并导入到目标表中,所以应该使用 Insert into query\_stmt 方式导入。
122+
123+
```
124+
insert into bj_store_sales select id, total, user_id, sale_timestamp from store_sales where region = "bj";
125+
```
126+
127+
128+
Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# 导入
2+
导入(Load)功能就是将用户的原始数据导入到 Doris 中。导入成功后,用户即可通过 Mysql 客户端查询数据。
3+
4+
本文档主要总体介绍导入简单原理,目前支持的几种导入方式,以及最佳实践。具体各个导入的操作手册请参阅各个导入的文档。
5+
6+
# 基本概念
7+
8+
1. 导入任务(Load job):导入任务读取用户提交的源数据,转换或清洗后,将数据导入到 Doris 系统中。导入完成后,数据即可被用户查询到。
9+
2. Backend(BE):Doris 系统的计算和存储节点。在导入流程中主要负责数据的 ETL 和存储。
10+
3. Frontend(FE):Doris 系统的元数据和调度节点。在导入流程中主要负责导入规划生成和导入任务的调度工作。
11+
4. Palo:Doris 系统在百度云上企业版售卖的名称。
12+
5. HDFS: Hadoop 分布式文件系统。用户的待导入数据可能存放的位置。
13+
6. BOS:百度云提供的对象存储系统,百度云上的 Palo 用户的待导入数据可能存放的位置。
14+
7. AFS:百度内部提供的超大规模文件系统,百度厂内的 Palo 用户的待导入数据可能存放的位置。
15+
8. Database(DB):Doris 系统中的 database。
16+
17+
# 基本原理
18+
## 导入执行流程
19+
20+
```
21+
+---------+ +---------+ +----------+ +-----------+
22+
| | | | | | | |
23+
|PENDING +----->+ETL +----->+LOADING +----->+FINISHED |
24+
| | | | | | | |
25+
+---------+ +---+-----+ +----+-----+ +-----------+
26+
| |
27+
| |
28+
| |
29+
| | +-----------+
30+
| | | |
31+
+-----------------+------------>CANCELLED |
32+
| |
33+
+-----------+
34+
35+
```
36+
37+
如上图,导入流程主要经过上面4个阶段。其中 PENDING 和 ETL 阶段不是必须的阶段。
38+
39+
+ PENDING: 该阶段只有 Broker load 才有。Broker load 被用户提交后会短暂停留在这个阶段,直到被 FE 中的 Scheduler 调度。 其中 Scheduler 的调度间隔为5秒。
40+
41+
+ ETL: 该阶段在版本0.11.0(包含)之前存在,主要是用于将原始数据按照用户声明的 transform 方式进行变换,并且过滤不满足条件的原始数据。在 0.11.0 后的版本,ETL 阶段不再存在,其中数据 transform 的工作被合并到 LOADING 阶段。
42+
43+
44+
+ LOADING: 该阶段在版本0.11.0(包含)之前主要用于将变换后的数据推到对应的 BE 存储中。在0.11.0后的版本,该阶段先对数据进行 ETL 清洗和变换,然后将数据发送到 BE 存储中。当所有导入数据均完成导入后,进入等待生效过程,此时 Load job 依旧是 LOADING。
45+
46+
47+
+ FINISHED: 在 Load job 涉及的所有数据均生效后,Load job 的状态变成 FINISHED。FINISHED 后导入的数据均可查询。
48+
49+
50+
+ CANCELLED: 在 ETL 或者 LOADING 的过程中,如果发生数据质量不合格等问题,Load Job 会被系统 cancel,本次导入会全部失败。当然,用户也可以手动取消 Load Job。CANCELLED 也是 Load Job 的最终状态,不可被再次执行。
51+
52+
53+
上述阶段,除了 PENDING 到 LOADING 阶段是 Scheduler 轮训调度的,其他阶段之前的转移都是回调机制实现。
54+
55+
# 导入方式
56+
57+
为适配不同的数据导入需求, Doris 系统提供了5种不同的导入方式。每种导入方式支持不同的数据源,存在不同的使用方式(异步,同步)。所有导入方式都支持 csv 数据格式。其中 Broker load 还支持 parquet 数据格式。
58+
59+
每个导入方式的说明见单个导入方式的操作手册。此处只简单介绍并讲解如何选择。
60+
61+
1. Broker load: 是一种异步类型的导入方式,主要支持数据源有 HDFS, BOS, AFS 这三种。用户可通过 mysql client 创建导入。
62+
2. Stream load:是一种同步类型的导入方式,用户提交 HTTP 请求并携带原始数据创建导入。
63+
+ Mini load:Mini load 和 Stream load 一样,但从功能上并不支持列的函数变换等。建议直接使用 Stream load 即可。
64+
3. Insert into: 是一种同步类型的导入方式,用户可以指定将已经存在在 Doris 系统中的数据导入到另一个 Table 中。用户可通过 Mysql client 创建导入。
65+
4. Multi load:是一种异步类型的导入方式,在导入创建后可接收多次 Mini load 导入,并且原子性生效同一个 Multi load中的导入数据。
66+
5. Routine load:流式导入方式,用户指定流式数据源后,Doris 会循环不断从数据源中读取新数据并导入。目前支持的流式数据源为 Kafka。
67+
68+
## 如何选择合适的导入方式
69+
第一原则:根据数据源所在位置选择导入方式。比如:如果用户的原始数据存放在 HDFS 上,则应该选择 Broker load 导入方式。
70+
71+
# 基本操作
72+
这里主要介绍了导入的几种基本操作,以及基本操作的使用流程。用户在确定了导入方式后,可查看各个导入方式的操作手册获取更详细的操作参数意义。
73+
74+
## 创建导入
75+
用户提交导入任务,并且设置导入任务的参数。用户提交导入任务后,根据不同的导入方式,导入任务会被异步或同步的执行。
76+
77+
同步执行的导入比如:Stream load,任务会直接进入LOADING阶段。异步执行的导入方式比如: Broker load,任务会先进入PENDING阶段。(在导入操作使用流程中会详细解释同步和异步的区别)
78+
79+
## 查看导入
80+
用户提交成功导入后,可通过查看导入命令获取导入状态,以及详细信息。对于异步的导入方式来说,用户必须在提交导入后,异步查看导入进度。在 SHOW LOAD 中导入状态改为 FINISHED 时,导入才算完成。用户也可以通过该方式查看导入失败的原因,以及导入的各项指标。
81+
82+
执行 ``` HELP SHOW LOAD``` 可查看查看导入的语法帮助。
83+
84+
## 取消导入
85+
用户可以通过指定待取消的任务任务的 Label,来手动取消导入任务。导入任务被取消后,导入任务不会导入任何数据。只有未完成的导入任务才能被手动取消。
86+
87+
执行 ```HELP CANCEL LOAD``` 查看取消导入的语法。
88+
89+
一般情况下,提交的导入配置错误或者导入消耗时间过长,都可以使用这个命令取消导入。
90+
91+
## 导入操作使用流程
92+
Doris 目前的导入方式分为两类,同步和异步。如果是外部程序接入 Doris 的导入功能,需要判断使用导入方式是哪类再确定接入逻辑。
93+
94+
### 同步
95+
同步导入方式既用户创建导入任务,Doris 同步执行导入,执行完成后返回用户导入结果。用户可直接根据创建导入任务命令返回的结果同步判断导入是否成功。
96+
97+
同步类型的导入方式有: Stream load , Mini load, Insert into。
98+
99+
操作步骤:
100+
101+
1. 用户(外部系统)创建导入任务
102+
2. Doris 返回导入结果
103+
3. 用户(外部系统)判断导入结果,如果失败可以再次提交导入任务。
104+
105+
*注意:如果用户使用的导入方式是同步返回的,且导入的数据量过大,则创建导入请求可能会花很长时间才能返回结果。*
106+
107+
### 异步
108+
异步导入方式既用户创建导入任务后,Doris 直接返回创建成功。导入任务会被异步执行,用户需要再发查看导入请求来确定导入是否完成。
109+
110+
异步类型的导入方式有:Broker load,Multi load。
111+
112+
操作步骤:
113+
114+
1. 用户(外部系统)创建导入任务
115+
2. Doris 返回导入创建结果
116+
3. 用户(外部系统)判断导入创建结果,成功则进入4,失败回到重试创建导入,回到1。
117+
4. 用户(外部系统)轮训查看导入任务,直到 state 变为 FINISHED 或 CANCELLED。
118+
119+
**强调:异步类型的导入,必须通过异步查看导入任务来确定导入是否成功。仅仅创建导入成功,并不代表导入完成**
120+
121+
### 注意事项
122+
无论是异步还是同步的导入类型,都不应该在 Doris 返回导入失败或导入创建失败后,无休止的重试。**外部系统在有限次数重试并失败后,保留失败信息,大部分多次重试均失败问题都是使用方法问题或数据本身问题。**
123+
124+
# 最佳实践
125+
用户在接入 Doris 导入时,一般会采用程序接入的方式,这样可以保证数据被定期的导入到 Doris 中。下面主要说明了程序接入 Doris 的最佳实践。
126+
127+
1. 选择合适的导入方式:根据数据源所在位置选择导入方式。例如:如果原始数据存放在 BOS 或 HDFS 上,则使用 Broker load导入。
128+
2. 确定导入方式的协议:如果选择了 Broker load 导入方式,则外部系统需要能使用 Mysql 协议定期提交任务。
129+
3. 确定导入方式的类型:导入方式为同步或异步。比如 Broker load 为异步导入方式,则外部系统在提交创建导入后,必须调用 查看导入命令,根据查看导入命令的结果来判断导入是否成功。
130+
4. 制定 label 生成策略:label 生成策略需满足,每一批次数据唯一且固定的原则。这样 Doris 就可以保证 at most once。
131+
5. 程序自身保证 at least once:外部系统需要保证自身的 at least once,这样就可以导入流程的 exactly once。
132+
133+
# 导入通用系统配置
134+
下面主要解释了几个所有导入方式均通用的系统级别的配置。
135+
136+
## FE conf 中的配置
137+
下面两个配置属于 FE 的系统配置,可以通过修改 FE 的配置文件 ```fe.conf``` 来修改配置。
138+
139+
+ max\_load\_timeout\_second 和 min\_load\_timeout\_second
140+
141+
这两个配置含义为:最大的导入超时时间,最小的导入超时时间,以秒为单位。默认的最大超时时间为3天, 默认的最小超时时间为1秒。用户自定义的导入超时时间不可超过这个范围。该参数通用于所有的导入方式。
142+
143+
该配置对应的 ```fe.conf```中的参数名为 ```max_load_timeout_second, min_load_timeout_second ```。
144+
145+
+ desired\_max\_waiting\_jobs
146+
147+
在等待队列中的导入任务个数最大值,默认为100。当在 FE 中处于 PENDING 状态(也就是等待执行的)导入个数超过该值,新的导入请求则会被拒绝。
148+
149+
此配置仅对异步执行的导入有效,当异步执行的导入等待个数超过默认值,则会在创建导入请求的时候被拒绝。
150+
151+
该配置对应的 ```fe.conf```中的参数名为 ```desired_max_waiting_jobs```。
152+
153+
+ max\_running\_txn\_num\_per\_db
154+
155+
这个配置的含义是说,每个 DB 中正在运行的导入最大个数(不区分导入类型,统一计数)。当当前 DB 正在运行的导入个数超过最大值时,后续的导入则会直接被系统取消。
156+
157+
对于同步执行的导入来说,如果当前 DB 的正在运行导入个数超过最大值,则创建导入请求就会返回失败。
158+
159+
对于异步执行的导入来说,如果当前 DB 的正在运行导入个数超过最大值,则会在导入被正式调度到(也就是从 PENDING 状态准备改为 LOADING 状态)的时候被系统异步取消。
160+
161+
该配置对应的是 ```fe.conf``` 中的参数名为 ``` max_running_txn_num_per_db ```。
162+
163+
164+
165+
166+
167+
168+
169+
170+
171+
172+
173+
174+
175+
176+

0 commit comments

Comments
 (0)