BROKER LOAD
功能
Broker Load 是一种基于 MySQL 协议的异步导入方式。您提交导入作业以后,StarRocks 会异步地执行导入作业。您可以使用 SELECT * FROM information_schema.loads
来查看 Broker Load 作业的结果,该功能自 3.1 版本起支持。有关 Broker Load 的背景信息、基本原理、支持的数据文件格式、如何执行单表导入 (Single-Table Load) 和多表导入 (Multi-Table Load) 操作、以及如何查看导入作业的结果等 信息,请参见从 HDFS 导入和从云存储导入。
注意
Broker Load 操作需要目标表的 INSERT 权限。如果您的用户账号没有 INSERT 权限,请参考 GRANT 给用户赋权。
语法
LOAD LABEL [<database_name>.]<label_name>
(
data_desc[, data_desc ...]
)
WITH BROKER
(
StorageCredentialParams
)
[PROPERTIES
(
opt_properties
)
]
注意在 StarRocks 中,部分文字是 SQL 语言的保留关键字,不能直接用于 SQL 语句。如果想在 SQL 语句中使用这些保留关键字,必须用反引号 (`) 包裹起来。参见关键字。
参数说明
database_name 和 label_name
label_name
指定导入作业的标签。
database_name
为可选,指定目标 StarRocks 表所在的数据库。
每个导入作业都对应一个在该数据库内唯一的标签。通过标签,可以查看对应导入作业的执行情况,并防止导入相同的数据。导入作业的状态为 FINISHED 时,其标签不可再复用给其他导入作业。导入作业的状态为 CANCELLED 时,其标签可以复用给其他导入作业,但通常都是用来重试同一个导入作业(即使用同一个标签导入相同的 数据)以实现数据“精确一次 (Exactly-Once)”语义。
有关标签的命名规范,请参见系统限制。
data_desc
用于描述一批次待导入的数据。每个 data_desc
声明了本批次待导入数据所属的数据源地址、ETL 函数、StarRocks 表和分区等信息。
Broker Load 支持一次导入多个数据文件。在一个导入作业中,您可以使用多个 data_desc
来声明导入多个数据文件,也可以使用一个 data_desc
来声明导入一个路径下的所有数据文件。Broker Load 还支持保证单次导入事务的原子性,即单次导入的多个数据文件都成功或者都失败,而不会出现部分导入成功、部分导入失败的情况。
data_desc
语法如下:
DATA INFILE ("<file_path>"[, "<file_path>" ...])
[NEGATIVE]
INTO TABLE <table_name>
[PARTITION (<partition1_name>[, <partition2_name> ...])]
[TEMPORARY PARTITION (<temporary_partition1_name>[, <temporary_partition2_name> ...])]
[COLUMNS TERMINATED BY "<column_separator>"]
[ROWS TERMINATED BY "<row_separator>"]
[FORMAT AS "CSV | Parquet | ORC"]
[(format_type_options)]
[(column_list)]
[COLUMNS FROM PATH AS (<partition_field_name>[, <partition_field_name> ...])]
[SET <k1=f1(v1)>[, <k2=f2(v2)> ...]]
[WHERE predicate]
data_desc
中的必选参数如下:
-
file_path
用于指定源数据文件所在的路径。
您可以指定导入一个具体的数据文件。例如,通过指定
"hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/20210411"
可以匹配 HDFS 服务器上/user/data/tablename
目录下名为20210411
的数据文件。您也可以用通配符指定导入某个路径下所有的数据文件。Broker Load 支持如下通配符:
?
、*
、[]
、{}
和^
。具体请参见通配符使用规则参考。例如, 通过指定"hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/*/*"
路径可以匹配 HDFS 服务器上/user/data/tablename
目录下所有分区内的数据文件,通过"hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/dt=202104*/*"
路径可以匹配 HDFS 服务器上/user/data/tablename
目录下所有202104
分区内的数据文件。说明
中间的目录也可以使用通配符匹配。
以 HDFS 数据源为例,文件路径中的
hdfs_host
和hdfs_port
参数说明如下:-
hdfs_host
:HDFS 集群中 NameNode 所在主机的 IP 地址。 -
hdfs_port
:HDFS 集群中 NameNode 所在主机的 FS 端口。默认端口号为9000
。
注意
- Broker Load 支持通过 S3 或 S3A 协议访问 AWS S3,因此 从 AWS S3 导入数据时,您在文件路径中传入的目标文件的 S3 URI 可以使用
s3://
或s3a://
作为前缀。 - 由于 Broker Load 只支持通过 gs 协议访问 Google GCS,因此当从 Google GCS 导入数据时,必须确保文件路径传入的目标文件的 GCS URI 使用
gs://
为前缀。 - 从 Blob Storage 导入数据时,需要使用 wasb 或 wasbs 作为文件协议访问目标数据:
- 如果您的存储账号支持通过 HTTP 协议进行访问,请使用 wasb 文件协议,文件路径格式为
wasb://<container_name>@<storage_account_name>.blob.core.windows.net/<path>/<file_name>/*
。 - 如果您的存储账号支持通过 HTTPS 协议进行访问,请使用 wasbs 文件协议,文件路径格式为
wasbs://<container_name>@<storage_account_name>.blob.core.windows.net/<path>/<file_name>/*
。
- 如果您的存储账号支持通过 HTTP 协议进行访问,请使用 wasb 文件协议,文件路径格式为
- 从 Data Lake Storage Gen2 导入数据时,需要使用 abfs 或 abfss 作为文件协议访问目标数据:
- 如果您的存储账号支持通过 HTTP 协议进行访问,请使用 abfs 文件协议,文件路径格式为
abfs://<container_name>@<storage_account_name>.dfs.core.windows.net/<file_name>
。 - 如果您的存储账号支持通过 HTTPS 协议进行访问,请使用 abfss 文件协议,文件路径格式为
abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<file_name>
。
- 如果您的存储账号支持通过 HTTP 协议进行访问,请使用 abfs 文件协议,文件路径格式为
- 从 Azure Data Lake Storage Gen1 导入数据时,需要使用 adl 作为文件协议访问目标数据,文件路径格式为
adl://<data_lake_storage_gen1_name>.azuredatalakestore.net/<path>/<file_name>
。
-
-
INTO TABLE
用于指定目标 StarRocks 表的名称。
data_desc
中的可选参数如下:
-
NEGATIVE
用于撤销某一批已经成功导入的数据。如果想要撤销某一批已经成功导入的数据,可以通过指定
NEGATIVE
关键字来导入同一批数据。说明
该参数仅适用于目标 StarRocks 表使用聚合模型、并且所有 Value 列的聚合函数均为
sum
的情况。 -
PARTITION
指定要把数据导入哪些分区。如果不指定该参数,则默认导入到 StarRocks 表所在的所有分区中。
-
TEMPORARY PARTITION
指定要把数据导入哪些临时分区。
-
COLUMNS TERMINATED BY
用于指定源数据文件中的列分隔符。如果不指定该参数,则默认列分隔符为
\t
,即 Tab。必须确保这里指定的列分隔符与源数据文件中的列分隔符一致;否则,导入作业会因数据质量错误而失败,作业状态 (State
) 会显示为CANCELLED
。需要注意的是,Broker Load 通过 MySQL 协议提交导入请求,除了 StarRocks 会做转义处理以外,MySQL 协议也会做转义处理。因此,如果列分隔符是 Tab 等不可见字符,则需要在列分隔字符前面多加一个反斜线 (\)。例如,如果列分隔符是
\t
,这里必须输入\\t
;如果列分隔符是\n
,这里必须输入\\n
。Apache Hive™ 文件的列分隔符为\x01
,因此,如果源数据文件是 Hive 文件,这里必须传入\\x01
。说明
- StarRocks 支持设置长度最大不超过 50 个字节的 UTF-8 编码字符串作为列分隔符,包括常见的逗号 (,)、Tab 和 Pipe (|)。
- 空值 (null) 用
\N
表示。比如 ,数据文件一共有三列,其中某行数据的第一列、第三列数据分别为a
和b
,第二列没有数据,则第二列需要用\N
来表示空值,写作a,\N,b
,而不是a,,b
。a,,b
表示第二列是一个空字符串。
-
ROWS TERMINATED BY
用于指定源数据文件中的行分隔符。如果不指定该参数,则默认行分隔符为
\n
,即换行符。必须确保这里指定的行分隔符与源数据文件中的行分隔符一致;否则,导入作业会因数据质量错误而失败,作业状态 (State
) 会显示为CANCELLED
。该参数从 2.5.4 版本开始支持。其他注意事项和使用条件与上文通过
COLUMNS TERMINATED BY
指定列分隔符相同。 -
FORMAT AS
用于指定源数据文件的格式。取值包括
CSV
、Parquet
和ORC
。如果不指定该参数,则默认通过file_path
参数中指定的文件扩展名(.csv、.parquet、和 .orc)来判断文件格式。 -
format_type_options
FORMAT AS
设置为CSV
时用于指定 CSV 格式选项。语法如下:(
key = value
key = value
...
)说明
format_type_options
在 3.0 及以后版本支持。选项说明见下表。
参数 说明 skip_header 用于指定跳过 CSV 文件最开头的几行数据。取值类型:INTEGER。默认值: 0
。
在某些 CSV 文件里,最开头的几行数据会用来定义列名、列类型等元数据信息。通过设置该参数,可以使 StarRocks 在导入数据时忽略 CSV 文件的前面几行。例如,如果设置该参数为1
,则 StarRocks 会在导入数据时忽略 CSV 文件的第一行。
这里的行所使用的分隔符须与您在导入语句中所设定的行分隔符一致。trim_space 用于指定是否去除 CSV 文件中列分隔符前后的空格。取值类型:BOOLEAN。默认值: false
。
有些数据库在导出数据为 CSV 文件时,会在列分隔符的前后添加一些空格。根据位置的不同,这些空格可以称为“前导空格”或者“尾随空格”。通过设置该参数,可以使 StarRocks 在导入数据时删除这些不必要的空格。
需要注意的是,StarRocks 不会去除被enclose
指定字符括起来的字段内的空格(包括字段的前导空格和尾随空格)。例如,列分隔符是竖线 (|
),enclose
指定的字符是双引号 ("
):|"Love StarRocks"|
|" Love StarRocks "|
| "Love StarRocks" |
如果设置trim_space
为true
,则 StarRocks 处理后的结果数据如下:|"Love StarRocks"|
|" Love StarRocks "|
|"Love StarRocks"|
enclose 根据 RFC4180,用于指定把 CSV 文件中的字段括起来的字符。取值类型:单字节字符。默认值: NONE
。最常用enclose
字符为单引号 ('
) 或双引号 ("
)。
被enclose
指定字符括起来的字段内的所有特殊字符(包括行分隔符、列分隔符等)均看做是普通符号。比 RFC4180 标准更进一步的是,StarRocks 提供的enclose
属性支持设置任意单个字节的字符。
如果一个字段内包含了enclose
指定字符,则可以使用同样的字符对enclose
指定字符进行转义。例如,在设置了enclose
为双引号 ("
) 时,字段值a "quoted" c
在 CSV 文件中应该写作"a ""quoted"" c"
。escape 指定用于转义的字符。用来转义各种特殊字符,比如行分隔符、列分隔符、转义符、 enclose
指定字符等,使 StarRocks 把这些特殊字符当做普通字符而解析成字段值的一部分。取值类型:单字节字符。默认值:NONE
。最常用的escape
字符为斜杠 (\
),在 SQL 语句中应该写作双斜杠 (\\
)。
说明escape
指定字符同时作用于enclose
指定字符的内部和外部。
以下为两个示例:- 当设置
enclose
为双引号 ("
) 、escape
为斜杠 (\
) 时,StarRocks 会把"say \"Hello world\""
解析成一个字段值say "Hello world"
。 - 假设列分隔符为逗号 (
,
) ,当设置escape
为斜杠 (\
) ,StarRocks 会把a, b\, c
解析成a
和b, c
两个字段值。
- 当设置
-
column_list
用于指定源数据文件和 StarRocks 表之间的列对应关系。语法如下:
(<column_name>[, <column_name> ...])
。column_list
中声明的列与 StarRocks 表中的列按名称一一对应。说明
如果源数据文件的列和 StarRocks 表中的列按顺序一一对应,则不需要指定
column_list
参数。如果要跳过源数据文件中的某一列,只需要在
column_list
参数中将该列命名为 StarRocks 表中不存在的列名即可。具体请参见导入过程中实现数据转换。 -
COLUMNS FROM PATH AS
用于从指定的文件路径中提取一个或多个分区字段的信息。该参数仅当指定的文件路径中存在分区字段时有效。
例如,源数据文件所在的路径为
/path/col_name=col_value/file1
,其中col_name
可以对应到 StarRocks 表中的列。这时候,您可以设置参数为col_name
。导入时,StarRocks 会将col_value
落入col_name
对应的列中。说明
该参数只有在从 HDFS 导入数据时可用。
-
SET
用于将源数据文件的某一列按照指定的函数进行转化,然后将转化后的结果落入 StarRocks 表中。语法如下:
column_name = expression
。以下为两个示例:- StarRocks 表中有三列,按顺序依次为
col1
、col2
和col3
;源数据文件中有四列,前两列按顺序依次对应 StarRocks 表中的col1
、col2
列,后两列之和对应 StarRocks 表中的col3
列。这种情况下,需要通过column_list
参数声明(col1,col2,tmp_col3,tmp_col4)
,并使用 SET 子句指定SET (col3=tmp_col3+tmp_col4)
来实现数据转换。 - StarRocks 表中有三列,按顺序依次为
year
、month
和day
;源数据文件中只有一个包含时间数据的列,格式为yyyy-mm-dd hh:mm:ss
。这种情况下,需要通过column_list
参数声明(tmp_time)
、并使用 SET 子句指定SET (year = year(tmp_time), month=month(tmp_time), day=day(tmp_time))
来实现数据转换。
- StarRocks 表中有三列,按顺序依次为
-
WHERE
用于指定过滤条件,对做完转换的数据进行过滤。只有符合 WHERE 子句中指定的过滤条件的数据才会导入到 StarRocks 表中。
WITH BROKER
在 v2.3 及以前版本,您需要在导入语句中通过 WITH BROKER "<broker_name>"
来指定使用哪个 Broker。自 v2.5 起,您不再需要指定 broker_name
,但继续保留 WITH BROKER
关键字。
说明
在 v2.3 及以前版本,StarRocks 在执行 Broker Load 时需要借助 Broker 才能访问外部存储系统,称为“有 Broker 的导入”。Broker 是一个独立的无状态服务,封装了文件系统接口。通过 Broker,StarRocks 能够访问和读取外部存储系统上的数据文件,并利用自身的计算资源对数据文件中的数据进行预处理和导入。
自 v2.5 起,StarRocks 在执行 Broker Load 时不需要借助 Broker 即可访问外部存储系统,称为“无 Broker 的导入”。
您可以通过 SHOW BROKER 语句来查看 StarRocks 集群中已经部署的 Broker。如果集群中没有部署 Broker,请参见部署 Broker 节点完成 Broker 部署。
StorageCredentialParams
StarRocks 访问存储系统的认证配置。
HDFS
社区版 HDFS 支持简单认证和 Kerberos 认证两种认证方式(Broker Load 默认使用简单认证),并且支持 NameNode 节点的 HA 配置。如果存储系统为社区版 HDFS,您可以按如下指定认证方式和 HA 配置:
-
认证方式
-
如果使用简单认证,请按如下配置
StorageCredentialParams
:"hadoop.security.authentication" = "simple",
"username" = "<hdfs_username>",
"password" = "<hdfs_password>"StorageCredentialParams
包含如下参数。参数名称 参数说明 hadoop.security.authentication 指定认证方式。取值范围: simple
和kerberos
。默认值:simple
。simple
表示简单认证,即无认证。kerberos
表示 Kerberos 认证。username 用于访问 HDFS 集群中 NameNode 节点的用户名。 password 用于访问 HDFS 集群中 NameNode 节点的密码。 -
如果使用 Kerberos 认证,请按如下配置
StorageCredentialParams
:"hadoop.security.authentication" = "kerberos",
"kerberos_principal" = "nn/zelda1@ZELDA.COM",
"kerberos_keytab" = "/keytab/hive.keytab",
"kerberos_keytab_content" = "YWFhYWFh"StorageCredentialParams
包含如下参数。参数名称 参数说明 hadoop.security.authentication 指定认证方式。取值范围: simple
和kerberos
。默认值 :simple
。simple
表示简单认证,即无认证。kerberos
表示 Kerberos 认证。kerberos_principal 用于指定 Kerberos 的用户或服务 (Principal)。每个 Principal 在 HDFS 集群内唯一,由如下三部分组成: username
或servicename
:HDFS 集群中用户或服务的名称。instance
:HDFS 集群要认证的节点所在服务器的名称,用来保证用户或服务全局唯一。比如,HDFS 集群中有多个 DataNode 节点,各节点需要各自独立认证。realm
:域,必须全大写。
nn/zelda1@ZELDA.COM
。kerberos_keytab 用于指定 Kerberos 的 Key Table(简称为“keytab”)文件的路径。 kerberos_keytab_content 用于指定 Kerberos 中 keytab 文件的内容经过 Base64 编码之后的内容。该参数跟 kerberos_keytab
参数二选一配置。需要注意的是,在多 Kerberos 用户的场景下,您需要确保至少部署了一组独立的 Broker,并且在导入语句中通过
WITH BROKER "<broker_name>"
来指定使用哪组 Broker。另外还需要打开 Broker 进程的启动脚本文件 start_broker.sh,在文件 42 行附近修改如下信息让 Broker 进程读取 krb5.conf 文件信息:export JAVA_OPTS="-Dlog4j2.formatMsgNoLookups=true -Xmx1024m -Dfile.encoding=UTF-8 -Djava.security.krb5.conf=/etc/krb5.conf"
说明
- /etc/krb5.conf 文件路径根据实际情况进行修改,Broker 需要有权限读取该文件。部署多个 Broker 时,每个 Broker 节点均需要修改如上信息,然后重启各 Broker 节点使配置生效。
- 您可以通过 SHOW BROKER 语句来查看 StarRocks 集群中已经部署的 Broker。
-
-
HA 配置
可以为 HDFS 集群中的 NameNode 节点配置 HA 机制,从而确保发生 NameNode 节点切换时,StarRocks 能够自动识别新切换到的 NameNode 节点,包括如下几种场景:
-
在单 HDFS 集群、并且配置了单 Kerberos 用户的场景下,可以采用有 Broker 的导入,也可以采用无 Broker 的导入。
-
如果采用有 Broker 的导入,您需要确保至少部署了一组独立的 Broker,并将
hdfs-site.xml
文件放在 HDFS 集群对应的 Broker 节点的{deploy}/conf
目录下。Broker 进程重启时,会将{deploy}/conf
目录添加到CLASSPATH
环境变量,使 Broker 能够读取 HDFS 集群中各节点的信息。 -
如果采用无 Broker 的导入,您需要将
hdfs-site.xml
文件放在每个 FE 节点和每个 BE(或 CN)节点的{deploy}/conf
目录下。
-
-
在单 HDFS 集群、并且配置了多 Kerberos 用户的场景下,只支持有 Broker 的导入。您需要确保至少部署了一组独立的 Broker,并将
hdfs-site.xml
文件放在 HDFS 集群对应的 Broker 节点的{deploy}/conf
目录下。Broker 进程重启时,会将{deploy}/conf
目录添加到CLASSPATH
环境变量,使 Broker 能够读取 HDFS 集群中各节点的信息。 -
在多 HDFS 集群场景下(不管是单 Kerberos 用户、还是多 Kerberos 用户),只支持有 Broker 的导入。您需要确保至少部署了一组独立的 Broker,并且采取如下方法之一来配置 Broker 读取 HDFS 集群中各节点的信息:
-
将
hdfs-site.xml
文件放在每个 HDFS 集群对应的 Broker 节点的{deploy}/conf
目录下。Broker 进程重启时,会将{deploy}/conf
目录添加到CLASSPATH
环境变量,使 Broker 能够读取 HDFS 集群中各节点的信息。 -
在创建 Broker Load 作业时增加如下 HA 配置:
"dfs.nameservices" = "ha_cluster",
"dfs.ha.namenodes.ha_cluster" = "ha_n1,ha_n2",
"dfs.namenode.rpc-address.ha_cluster.ha_n1" = "<hdfs_host>:<hdfs_port>",
"dfs.namenode.rpc-address.ha_cluster.ha_n2" = "<hdfs_host>:<hdfs_port>",
"dfs.client.failover.proxy.provider" = "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider"上述配置中的参数说明如下表所述:
参数名称 参数说明 dfs.nameservices 自定义 HDFS 集群的名称。 dfs.ha.namenodes.XXX 自定义 NameNode 的名称,多个名称以逗号 (,) 分隔,双引号内不允许出现空格。
其中xxx
为dfs.nameservices
中自定义的HDFS 服务的名称。dfs.namenode.rpc-address.XXX.NN 指定 NameNode 的 RPC 地址信息。
其中NN
表示dfs.ha.namenodes.XXX
中自定义 NameNode 的名称。dfs.client.failover.proxy.provider 指定客户端连接的 NameNode 的提供者,默认为 org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider
。
-
说明
您可以通过 SHOW BROKER 语句来查看 StarRocks 集群中已经部署的 Broker。
-
AWS S3
如果存储系统为 AWS S3,请按如下配置 StorageCredentialParams
:
-
基于 Instance Profile 进行认证和鉴权
"aws.s3.use_instance_profile" = "true",
"aws.s3.region" = "<aws_s3_region>"