STREAM LOAD

Stream Load 是一种基于 HTTP 协议的同步导入方式，支持将本地文件或数据流导入到 StarRocks 中。您提交导入作业以后，StarRocks 会同步地执行导入作业，并返回导入作业的结果信息。您可以通过返回的结果信息来判断导入作业是否成功。有关 Stream Load 的应用场景、使用限制、基本原理、以及支持的数据文件格式等信息，请参见 使用 Stream Load 从本地导入 。

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 中的参数如下表所述。

您可以通过 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>"

data_desc 中的参数可以分为三类：公共参数、CSV 适用的参数、以及 JSON 适用的参数。

公共参数 ​

CSV 适用参数 ​

对于 CSV 格式的数据，需要注意以下两点：

JSON 适用参数 ​

另外，导入 JSON 格式的数据时，需要注意单个 JSON 对象的大小不能超过 4 GB。如果 JSON 文件中单个 JSON 对象的大小超过 4 GB，会提示 "This parser can't support a document that big." 错误。

opt_properties ​

用于指定一些导入相关的可选参数。指定的参数设置作用于整个导入作业。语法如下：

-H "label: <label_name>"
-H "where: <condition1>[, <condition2>, ...]"
-H "max_filter_ratio: <num>"
-H "timeout: <num>"
-H "strict_mode: true | false"
-H "timezone: <string>"
-H "load_mem_limit: <num>"
-H "merge_condition: <column_name>"

参数说明如下表所述。

列映射 ​

导入 CSV 数据时配置列映射关系 ​

如果源数据文件中的列与目标表中的列按顺序一一对应，您不需要指定列映射和转换关系。

如果源数据文件中的列与目标表中的列不能按顺序一一对应，包括数量或顺序不一致，则必须通过 COLUMNS 参数来指定列映射和转换关系。一般包括如下两种场景：

列数量一致、但是顺序不一致，并且数据不需要通过函数计算、可以直接落入目标表中对应的列。 这种场景下，您需要在 COLUMNS 参数中按照源数据文件中的列顺序、使用目标表中对应的列名来配置列映射和转换关系。

例如，目标表中有三列，按顺序依次为 col1 、 col2 和 col3 ；源数据文件中也有三列，按顺序依次对应目标表中的 col3 、 col2 和 col1 。这种情况下，需要指定 COLUMNS(col3, col2, col1) 。

列数量、顺序都不一致，并且某些列的数据需要通过函数计算以后才能落入目标表中对应的列。 这种场景下，您不仅需要在 COLUMNS 参数中按照源数据文件中的列顺序、使用目标表中对应的列名来配置列映射关系，还需要指定参与数据计算的函数。以下为两个示例：

有关操作示例，参见 设置列映射关系 。

导入 JSON 数据时配置列映射关系 ​

如果 JSON 文件中的 Key 名与目标表中的列名一致，您可以使用简单模式来导入数据。简单模式下，不需要设置 jsonpaths 参数，这种模式要求 JSON 数据是大括号 表示的对象类型，例如 {"category": 1, "author": 2, "price": "3"} 中， category 、 author 、 price 是 Key 的名称，按名称直接对应目标 表中的 category 、 author 、 price 三列。

如果 JSON 文件中的 Key 名与目标表中的列名不一致，则需要使用匹配模式来导入数据。匹配模式下，需要通过 jsonpaths 和 COLUMNS 两个参数来指定 JSON 文件中的 Key 和目标表中的列之间的映射和转换关系：

有关使用匹配模式导入 JSON 数据的示例，参见 使用匹配模式导入数据 。

返回值 ​

导入结束后，会以 JSON 格式返回导入作业的结果信息，如下所示：

{
    "TxnId": 1003,
    "Label": "label123",
    "Status": "Success",
    "Message": "OK",
    "NumberTotalRows": 1000000,
    "NumberLoadedRows": 999999,
    "NumberFilteredRows": 1,
    "NumberUnselectedRows": 0,
    "LoadBytes": 40888898,
    "LoadTimeMs": 2144,
    "BeginTxnTimeMs": 0,
    "StreamLoadPlanTimeMs": 1,
    "ReadDataTimeMs": 0,
    "WriteDataTimeMs": 11,
    "CommitAndPublishTimeMs": 16,
}

返回结果中的参数说明如下表所述。

如果导入作业失败，还会返回 ErrorURL ，如下所示：

{
    "ErrorURL": "http://172.26.195.68:8045/api/_load_error_log?file=error_log_3a4eb8421f0878a6_9a54df29fd9206be"
}

通过 ErrorURL 可以查看导入过程中因数据质量不合格而过滤掉的错误数据行的具体信息。您可 以在提交导入作业时，通过可选参数 log_rejected_record_num 来指定最多可以记录多少条错误数据行的信息。

您可以通过 curl "url" 命令直接查看错误数据行的信息。也可以通过 wget "url" 命令导出错误数据行的信息，如下所示：

wget http://172.26.195.68:8045/api/_load_error_log?file=error_log_3a4eb8421f0878a6_9a54df29fd9206be

导出的错误数据行信息会保存到一个名为 _load_error_log?file=error_log_3a4eb8421f0878a6_9a54df29fd9206be 的本地文件中。您可以通过 cat _load_error_log?file=error_log_3a4eb8421f0878a6_9a54df29fd9206be 命令查看该文件的内容。

您可以根据错误信息调整导入作业，然后重新提交导入作业。

导入 CSV 格式的数据 ​

本小节以 CSV 格式的数据为例，重点阐述在创建导入作业的时候，如何运用各种参数配置来满足不同业务场景下的各种导入要求。

设置超时时间 ​

StarRocks 数据库 test_db 里的表 table1 包含三列，按顺序依次为 col1 、 col2 、 col3 。

数据文件 example1.csv 也包含三列，按顺序一一对应 table1 中的三列 col1 、 col2 、 col3 。

如果要把 example1.csv 中所有的数据都导入到 table1 中，并且要求超时时间最大不超过 100 秒，可以执行如下命令：

curl --location-trusted -u <username>:<password> -H "label:label1" \
    -H "Expect:100-continue" \
    -H "timeout:100" \
    -H "max_filter_ratio:0.2" \
    -T example1.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table1/_stream_load