STREAM LOAD
功能
Stream Load 是一种基于 HTTP 协议的同步导入方式,支持将本地文件或数据流导入到 StarRocks 中。您提交导入作业以后,StarRocks 会同步地执行导入作业,并返回导入作业的结果信息。您可以通过返回的结果信息来判断导入作业是否成功。有关 Stream Load 的应用场景、使用限制、基本原理、以及支持的数据文件格式等信息,请参见使用 Stream Load 从本地导入。
从 3.2.7 版本起,STREAM LOAD 支持在传输过程中对 JSON 数据进行压缩,减少网络带宽开销。用户可以通过 compression
或 Content-Encoding
参数指定不同的压缩方式,支持 GZIP、BZIP2、LZ4_FRAME、ZSTD 压缩算法。参见相关语法。
注意
- Stream Load 操作会同时更新和 StarRocks 原始表相关的物化视图的数据。
- Stream Load 操作需要目标表的 INSERT 权限。如果您的用户账号没有 INSERT 权限,请参考 GRANT 给用户赋权。
语法
curl --location-trusted -u <username>:<password> -XPUT <url>
(
data_desc
)
[opt_properties]
本文以 curl 工具为例介绍如何使用 Stream Load 导入数据。除了使用 curl 工具,您还可以通过其他支持 HTTP 协议的工具或语言提交导入作业以导入数据。导入相关的参数位于 HTTP 请求的请求头。传入这些导入相关的参数时,需要注意以下几点:
-
推荐使用分块上传方式,如本文示例所示。如果使用非分块上传方式,则必须使用请求头字段
Content-Length
来标示待上传内容的长度,从而保证数据完整性。说明
使用 curl 工具提交导入作业的时候,会自动添加
Content-Length
字段,因此无需手动指定Content-Length
。 -
必须在 HTTP 请求的请求头字段
Expect
中指定100-continue
,即"Expect:100-continue"
。这样在服务器拒绝导入作业请求的情况下,可以避免不必要的数据传输,从而减少不必要的资源开销。
注意在 StarRocks 中,部分文字是 SQL 语言的保留关键字,不能直接用于 SQL 语句。如果想在 SQL 语句中使用这些保留关键字,必须用反引号 (`) 包裹起来。参见关键字。
参数说明
username 和 password
用于指定 StarRocks 集群账号的用户名和密码。必选参数。如果账号没有设置密码,这里只需要传入 <username>:
。
XPUT
用于指定 HTTP 请求方法。必选参数。Stream Load 当前只支持 PUT 方法。
url
用于指定 StarRocks 表的 URL 地址。必选参数。语法如下:
http://<fe_host>:<fe_http_port>/api/<database_name>/<table_name>/_stream_load
url
中的参数如下表所述。
参数名称 | 是否必须 | 参数说明 |
---|---|---|
fe_host | 是 | 指定 StarRocks 集群中 FE 的 IP 地址。 说明 如果您直接提交导入作业给某一个 BE(或 CN)节点,则需要传入该 BE(或 CN)的 IP 地址。 |
fe_http_port | 是 | 指定 StarRocks 集群中 FE 的 HTTP 端口号。 默认端口号为 8030。 说明 如果您直接提交导入作业给某一指定的 BE(或 CN)节点,则需要传入该 BE(或 CN)的 HTTP 端口号。默认端口号为 8040。 |
database_name | 是 | 指定目标 StarRocks 表所在的数据库的名称。 |
table_name | 是 | 指定目标 StarRocks 表的名称。 |
说明
您可以通过 SHOW FRONTENDS 命令查看 FE 节点的 IP 地址和 HTTP 端口号。
data_desc
用于描述源数据文件,包括源数据文件的名称、格式、列分隔符、行分隔符、目标分区、以及与 StarRocks 表之间的列对应关系等。语法如下:
-T <file_path>
-H "format: CSV | JSON"
-H "column_separator: <column_separator>"
-H "row_delimiter: <row_delimiter>"
-H "columns: <column1_name>[, <column2_name>,... ]"
-H "partitions: <partition1_name>[, <partition2_name>, ...]"
-H "temporary_partitions: <temporary_partition1_name>[, <temporary_partition2_name>, ...]"
-H "jsonpaths: [ \"<json_path1>\"[, \"<json_path2>\", ...] ]"
-H "strip_outer_array: true | false"
-H "json_root: <json_path>"
-H "ignore_json_size: true | false"
-H "compression: <compression_algorithm> | Content-Encoding: <compression_algorithm>"
data_desc
中的参数可以分为三类:公共参数、CSV 适用的参数、以及 JSON 适用的参数。
公共参数
参数名称 | 是否必选 | 参数说明 |
---|---|---|
file_path | 是 | 指定源数据文件的保存路径。文件名里可选包含或者不包含扩展名。 |
format | 否 | 指定待导入数据的格式。取值包括 CSV 和 JSON 。默认值:CSV 。 |
partitions | 否 | 指定要把数据导入哪些分区。如果不指定该参数,则默认导入到 StarRocks 表所在的所有分区中。 |
temporary_partitions | 否 | 指定要把数据导入哪些临时分区。 |
columns | 否 | 指定源数据文件和 StarRocks 表之间的列对应关系。如果源数据文件中的列与 StarRocks 表中的列按顺序一一对应,则不需要指定 columns 参数。您可以通过 columns 参数实现数据转换。例如,要导入一个 CSV 格式的数据文件,文件中有两列,分别可以对应到目标 StarRocks 表的 id 和 city 两列。如果要实现把数据文件中第一列的数据乘以 100 以后再落入 StarRocks 表的转换,可以指定 "columns: city,tmp_id, id = tmp_id * 100" 。具体请参见本文“列映射”章节。 |
CSV 适用参数
参数名称 | 是否必选 | 参数说明 |
---|---|---|
column_separator | 否 | 用于指定源数据文件中的列分隔符。如果不指定该参数,则默认为 \t ,即 Tab。必须确保这里指定的列分隔符与源数据文件中的列分隔符一致。说明 StarRocks 支持设置长度最大不超过 50 个字节的 UTF-8 编码字符串作为列分隔符,包括常见的逗号 (,)、Tab 和 Pipe (|)。 |
row_delimiter | 否 | 用于指定源数据文件中的行分隔符。如果不指定该参数,则默认为 \n 。 |
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 指定字符的内部和外部。以下为两个示例:
|
说明
对于 CSV 格式的数据,需要注意以下两点:
- StarRocks 支持设置长度最大不超过 50 个字节的 UTF-8 编码字符串作为列分隔符,包括常见的逗号 (,)、Tab 和 Pipe (|)。
- 空值 (null) 用
\N
表示。比如,数据文件一共有三列,其中某行数据的第一列、第三列数据分别为a
和b
,第二列没有数据,则第二列需要用\N
来表示空值,写作a,\N,b
,而不是a,,b
。a,,b
表示第二列是一个空字符串。skip_header
、trim_space
、enclose
和escape
等属性在 3.0 及以后版本支持。