跳到主要内容
版本: 最新版本-3.5

STREAM LOAD

StarRocks 提供基于 HTTP 的 STREAM LOAD 加载方式，可以帮助您从本地文件系统或流式数据源加载数据。 提交加载作业后，StarRocks 会同步运行该作业，并在作业完成后返回作业结果。 您可以根据作业结果判断作业是否成功。 有关 Stream Load 的应用场景、限制、原理以及支持的数据文件格式的信息，请参阅通过 Stream Load 从本地文件系统加载。

提示

本示例使用 StarRocks 基础快速入门中的 Local Climatological Data(LCD) 数据集。您可以加载数据并自行尝试该示例。

自 v3.2.7 起，Stream Load 支持在传输过程中压缩 JSON 数据，从而减少网络带宽开销。 用户可以使用参数compression和Content-Encoding指定不同的压缩算法。 支持的压缩算法包括 GZIP、BZIP2、LZ4_FRAME 和 ZSTD。 有关更多信息，请参见data_desc。

从 v3.4.0 开始，系统支持合并多个 Stream Load 请求。 有关更多信息，请参见合并提交参数。

注意

  • 在使用 Stream Load 将数据加载到 StarRocks 表后，也会更新在该表上创建的物化视图的数据。
  • 您只能以对这些 StarRocks 表具有 INSERT 权限的用户身份将数据加载到 StarRocks 表中。 如果您没有 INSERT 权限，请按照GRANT中提供的说明，将 INSERT 权限授予用于连接到 StarRocks 集群的用户。

语法​

curl --location-trusted -u <username>:<password> -XPUT <url>
(
    data_desc
)
[opt_properties]

本主题以 curl 为例介绍如何使用 Stream Load 加载数据。 除了 curl 之外，您还可以使用其他与 HTTP 兼容的工具或语言来执行 Stream Load。 加载相关参数包含在 HTTP 请求标头字段中。 输入这些参数时，请注意以下几点

  • 您可以使用分块传输编码，如本主题所示。 如果您不选择分块传输编码，则必须输入Content-Length标头字段以指示要传输的内容的长度，从而确保数据完整性。

    注意

    如果您使用 curl 执行 Stream Load，StarRocks 会自动添加Content-Length标头字段，您无需手动输入。

  • 您必须添加一个Expect标头字段，并将其值指定为100-continue，如"Expect:100-continue"中所示。 这有助于防止不必要的数据传输，并减少在您的作业请求被拒绝时的资源开销。

请注意，在 StarRocks 中，一些字面量被 SQL 语言用作保留关键字。 请勿在 SQL 语句中直接使用这些关键字。 如果您想在 SQL 语句中使用这样的关键字，请将其括在一对反引号 (`) 中。 请参见关键字。

参数​

用户名和密码​

指定您用于连接到 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 端口号。 默认端口号为8030。
database_name是StarRocks 表所属的数据库的名称。
table_name是StarRocks 表的名称。

注意

您可以使用SHOW FRONTENDS查看 FE 节点的 IP 地址和 HTTP 端口。

data_desc​

描述您想要加载的数据文件。 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 会将数据文件加载到 StarRocks 表的所有分区中。
temporary_partitions否您想要将数据文件加载到的临时分区的名称。 您可以指定多个临时分区，这些分区必须用逗号 (,) 分隔。
columns否数据文件和 StarRocks 表之间的列映射。
如果数据文件中的字段可以按顺序映射到 StarRocks 表中的列，则您无需指定此参数。 相反，您可以使用此参数来实现数据转换。 例如，如果您加载一个 CSV 数据文件，并且该文件由可以按顺序映射到 StarRocks 表的两列 id 和 city 的两列组成，则您可以指定 "columns: city,tmp_id, id = tmp_id * 100"。 有关更多信息，请参见本主题中的“列映射”部分。

CSV 参数​

参数必需描述
column_separator否数据文件中用于分隔字段的字符。 如果您不指定此参数，则此参数默认为\t，表示制表符。
确保您使用此参数指定的列分隔符与数据文件中使用的列分隔符相同。
注意
对于 CSV 数据，您可以使用 UTF-8 字符串，例如逗号 (,)、制表符或管道 (|)，其长度不超过 50 个字节作为文本分隔符。
row_delimiter否数据文件中用于分隔行的字符。 如果您不指定此参数，则此参数默认为\n。
skip_header否指定当数据文件为 CSV 格式时是否跳过数据文件的前几行。 类型：INTEGER。 默认值：0。
在某些 CSV 格式的数据文件中，开头的几行用于定义元数据，例如列名和列数据类型。 通过设置skip_header参数，您可以使 StarRocks 在数据加载期间跳过数据文件的前几行。 例如，如果您将此参数设置为1，StarRocks 会在数据加载期间跳过数据文件的第一行。
数据文件中开头的几行必须使用您在加载命令中指定的行分隔符分隔。
trim_space否指定当数据文件为 CSV 格式时是否从数据文件中删除列分隔符之前和之后的空格。类型：BOOLEAN。默认值：false。
对于某些数据库，当您将数据导出为 CSV 格式的数据文件时，会在列分隔符中添加空格。 这些空格被称为前导空格或尾随空格，具体取决于它们的位置。 通过设置trim_space参数，您可以使 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 指定的字符包装的特殊字符（包括行分隔符和列分隔符）都被视为普通符号。 StarRocks 可以做得比 RFC4180 更多，因为它允许您指定任何单字节字符作为 enclose 指定的字符。
如果字段值包含一个 enclose 指定的字符，您可以使用相同的字符来转义该 enclose 指定的字符。 例如，您将 enclose 设置为 "，并且字段值为 a "quoted" c。 在这种情况下，您可以将字段值作为 "a ""quoted"" c" 输入到数据文件中。
escape否指定用于转义各种特殊字符的字符，例如行分隔符、列分隔符、转义字符和 enclose 指定的字符，然后 StarRocks 将它们视为普通字符，并解析为它们所在的字段值的一部分。 类型：单字节字符。 默认值：NONE。 最常见的字符是斜杠 (\)，它必须在 SQL 语句中写成双斜杠 (\\)。
注意
由 escape 指定的字符适用于每对 enclose 指定的字符的内部和外部。
以下是两个示例
  • 当您将 enclose 设置为 " 并将 escape 设置为 \ 时，StarRocks 会将 "say \"Hello world\"" 解析为 say "Hello world"。
  • 假设列分隔符是逗号 (,)。当您将 escape 设置为 \ 时，StarRocks 会将 a, b\, c 解析为两个单独的字段值：a 和 b, c。

注意

  • 对于 CSV 数据，您可以使用 UTF-8 字符串，例如逗号 (,)、制表符或管道 (|)，其长度不超过 50 个字节作为文本分隔符。
  • Null 值用\N表示。 例如，一个数据文件由三列组成，并且来自该数据文件的一条记录在第一列和第三列中保存数据，但在第二列中没有数据。 在这种情况下，您需要在第二列中使用\N来表示 null 值。 这意味着该记录必须编译为a,\N,b而不是a,,b。 a,,b表示记录的第二列保存一个空字符串。
  • v3.0 及更高版本支持格式选项，包括skip_header、trim_space、enclose 和 escape。

JSON 参数​

参数必需描述
jsonpaths否您想要从 JSON 数据文件中加载的键的名称。 您只需要在使用匹配模式加载 JSON 数据时指定此参数。 此参数的值采用 JSON 格式。 请参见配置 JSON 数据加载的列映射。
strip_outer_array否指定是否去除最外层的数组结构。 有效值：true 和 false。 默认值：false。
在实际业务场景中，JSON 数据可能具有由一对中括号[]指示的最外层数组结构。 在这种情况下，我们建议您将此参数设置为true，以便 StarRocks 删除最外层的中括号[]，并将每个内部数组加载为单独的数据记录。 如果您将此参数设置为false，StarRocks 会将整个 JSON 数据文件解析为一个数组，并将该数组加载为单个数据记录。
例如，JSON 数据是[ {"category" : 1, "author" : 2}, {"category" : 3, "author" : 4} ]。 如果您将此参数设置为true，则 {"category" : 1, "author" : 2} 和 {"category" : 3, "author" : 4} 将被解析为单独的数据记录，并加载到单独的 StarRocks 表行中。
json_root否您想要从 JSON 数据文件中加载的 JSON 数据的根元素。 您只需要在使用匹配模式加载 JSON 数据时指定此参数。 此参数的值是一个有效的 JsonPath 字符串。 默认情况下，此参数的值为空，表示将加载 JSON 数据文件的所有数据。 有关更多信息，请参见本主题的“使用匹配模式加载 JSON 数据，并指定根元素”部分。
ignore_json_size否指定是否检查 HTTP 请求中 JSON 主体的大小。
注意
默认情况下，HTTP 请求中 JSON 主体的大小不能超过 100 MB。 如果 JSON 主体的大小超过 100 MB，则会报告错误“此批次的大小超过 JSON 类型数据的最大大小 [104857600] 数据 [8617627793]。 设置 ignore_json_size 可以跳过检查，尽管这可能会导致巨大的内存消耗。”。 为了防止此错误，您可以在 HTTP 请求标头中添加 "ignore_json_size:true"，以指示 StarRocks 不检查 JSON 主体大小。
compression, Content-Encoding否应用于传输期间数据的编码算法。 支持的算法包括 GZIP、BZIP2、LZ4_FRAME 和 ZSTD。 示例：curl --location-trusted -u root: -v 'http://127.0.0.1:18030/api/db0/tbl_simple/_stream_load' \-X PUT -H "expect:100-continue" \-H 'format: json' -H 'compression: lz4_frame' -T ./b.json.lz4。

当您加载 JSON 数据时，还要注意每个 JSON 对象的大小不能超过 4 GB。 如果 JSON 数据文件中的单个 JSON 对象的大小超过 4 GB，则会报告错误“此解析器无法支持如此大的文档。”。

合并提交参数​

在指定的时间窗口内启用多个并发 Stream Load 请求的合并提交，并将它们合并到单个事务中。

参数必需描述
enable_merge_commit否是否为加载请求启用合并提交。 有效值：true 和 false（默认）。
merge_commit_async否服务器的返回模式。 有效值
  • true：启用异步模式，服务器在收到数据后立即返回。 此模式不能保证加载成功。
  • false（默认）：启用同步模式，服务器仅在合并的事务提交后返回，从而确保加载成功且可见。
merge_commit_interval_ms是合并时间窗口的大小。 单位：毫秒。 合并提交尝试将在此窗口内收到的加载请求合并到单个事务中。 较大的窗口可以提高合并效率，但会增加延迟。
merge_commit_parallel是为每个合并窗口创建的加载计划的并行度。 可以根据摄取的负载调整并行度。 如果有大量请求和/或要加载的大量数据，请增加此值。 并行度限制为 BE 节点的数量，计算公式为 max(merge_commit_parallel, BE 节点的数量)。
注意
  • 合并提交仅支持将同构加载请求合并到单个数据库和表中。 “同构”表示 Stream Load 参数是相同的，包括：通用参数、JSON 格式参数、CSV 格式参数、opt_properties 和合并提交参数。
  • 对于加载 CSV 格式的数据，您必须确保每行都以行分隔符结尾。 不支持 skip_header。
  • 服务器会自动为事务生成标签。 如果指定了标签，则会忽略它们。
  • 合并提交将多个加载请求合并到单个事务中。 如果一个请求包含数据质量问题，则事务中的所有请求都会失败。

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 "partial_update: true | false"
-H "partial_update_mode: row | column"
-H "merge_condition: <column_name>"

下表描述了可选参数。

参数必需描述
label否加载作业的标签。 如果您不指定此参数，StarRocks 会自动为加载作业生成一个标签。
StarRocks 不允许您使用一个标签多次加载一个数据批次。 因此，StarRocks 可以防止重复加载相同的数据。 有关标签命名约定，请参见系统限制。
默认情况下，StarRocks 会保留最近三天成功完成的加载作业的标签。 您可以使用FE 参数 label_keep_max_second 来更改标签保留期限。
where否StarRocks 用于过滤预处理数据的条件。 StarRocks 仅加载满足 WHERE 子句中指定的过滤条件的预处理数据。
max_filter_ratio否加载作业的最大误差容限。 误差容限是可以由于数据质量不足而被过滤掉的数据记录的最大百分比，占加载作业请求的所有数据记录的百分比。 有效值：0 到 1。 默认值：0。
我们建议您保留默认值0。 这样，如果检测到不合格的数据记录，则加载作业会失败，从而确保数据正确性。
如果您想要忽略不合格的数据记录，您可以将此参数设置为大于0的值。 这样，即使数据文件包含不合格的数据记录，加载作业也可以成功。
注意
不合格的数据记录不包括被 WHERE 子句过滤掉的数据记录。
log_rejected_record_num否指定可以记录的不合格数据行的最大数量。此参数从 v3.1 开始支持。有效值：0、-1 和任何非零正整数。默认值：0。
  • 值 0 指定将不记录被过滤掉的数据行。
  • 值 -1 指定将记录所有被过滤掉的数据行。
  • 一个非零正整数，例如n，指定每个 BE 或 CN 上最多可以记录 n 个被过滤掉的数据行。
timeout否加载作业的超时时间。 有效值：1 到 259200。 单位：秒。 默认值：600。
注意 除了 timeout 参数之外，您还可以使用FE 参数 stream_load_default_timeout_second 来集中控制 StarRocks 集群中所有 Stream Load 作业的超时时间。 如果您指定了 timeout 参数，则以 timeout 参数指定的超时时间为准。 如果您未指定 timeout 参数，则以 stream_load_default_timeout_second 参数指定的超时时间为准。
strict_mode否指定是否启用严格模式。 有效值：true 和 false。 默认值：false。 值 true 指定启用严格模式，值 false 指定禁用严格模式。
timezone否加载作业使用的时区。 默认值：Asia/Shanghai。 此参数的值会影响诸如 strftime、alignment_timestamp 和 from_unixtime 之类的函数返回的结果。 此参数指定的时区是一个会话级时区。 有关更多信息，请参见配置时区。
load_mem_limit否可以为加载作业提供的最大内存量。 单位：字节。 默认情况下，加载作业的最大内存大小为 2 GB。 此参数的值不能超过可以为每个 BE 或 CN 提供的最大内存量。
partial_update否是否使用部分更新。有效值：TRUE 和 FALSE。默认值：FALSE，表示禁用此功能。
partial_update_mode否指定部分更新的模式。 有效值：row 和 column。
  • 值 row（默认）表示行模式下的部分更新，更适合具有许多列和小批量的实时更新。
  • 值 column 表示列模式下的部分更新，更适合于少列多行的批量更新。 在这种情况下，启用列模式可以提供更快的更新速度。 例如，在一个有 100 列的表中，如果只更新所有行中的 10 列（总数的 10%），则列模式的更新速度比行模式快 10 倍。
merge_condition否指定您想要用作确定更新是否可以生效的条件的列的名称。 仅当源数据记录在指定列中具有大于或等于目标数据记录的值时，从源记录到目标记录的更新才会生效。 StarRocks 自 v2.5 起支持条件更新。
注意
您指定的列不能是主键列。 此外，只有使用主键表的表才支持条件更新。

列映射​

配置 CSV 数据加载的列映射​

如果数据文件的列可以按顺序一对一地映射到 StarRocks 表的列，则您无需配置数据文件和 StarRocks 表之间的列映射。

如果数据文件的列不能按顺序一对一地映射到 StarRocks 表的列，则您需要使用 columns 参数来配置数据文件和 StarRocks 表之间的列映射。 这包括以下两个用例

  • 列数相同，但列顺序不同。 此外，来自数据文件的数据在加载到匹配的 StarRocks 表列之前不需要由函数计算。

    在 columns 参数中，您需要以数据文件列的排列顺序指定 StarRocks 表列的名称。

    例如，StarRocks 表由三列组成，按顺序分别为 col1、col2 和 col3，数据文件也由三列组成，可以按顺序映射到 StarRocks 表列 col3、col2 和 col1。 在这种情况下，您需要指定 "columns: col3, col2, col1"。

  • 列数不同且列顺序不同。此外，数据文件中的数据在加载到匹配的 StarRocks 表列之前需要通过函数计算。

    在 columns 参数中，您需要以数据文件列的排列顺序指定 StarRocks 表列的名称，并指定要用于计算数据的函数。以下是两个示例

    • StarRocks 表由三列组成，按顺序分别为 col1、col2 和 col3。 数据文件由四列组成，其中前三列可以按顺序映射到 StarRocks 表列 col1、col2 和 col3，第四列无法映射到任何 StarRocks 表列。 在这种情况下，您需要为数据文件的第四列临时指定一个名称，并且临时名称必须与任何 StarRocks 表列名称不同。 例如，您可以指定 "columns: col1, col2, col3, temp"，其中数据文件的第四列临时命名为 temp。
    • StarRocks 表由三列组成，按顺序分别为 year、month 和 day。 数据文件仅由一列组成，该列容纳 yyyy-mm-dd hh:mm:ss 格式的日期和时间值。 在这种情况下，您可以指定 "columns: col, year = year(col), month=month(col), day=day(col)"，其中 col 是数据文件列的临时名称，函数 year = year(col)、month=month(col) 和 day=day(col) 用于从数据文件列 col 中提取数据，并将数据加载到映射的 StarRocks 表列中。 例如，year = year(col) 用于从数据文件列 col 中提取 yyyy 数据，并将数据加载到 StarRocks 表列 year 中。

有关详细示例，请参见配置列映射。

配置 JSON 数据加载的列映射​

如果 JSON 文档的键与 StarRocks 表的列具有相同的名称，则您可以使用简单模式加载 JSON 格式的数据。 在简单模式下，您无需指定 jsonpaths 参数。 此模式要求 JSON 格式的数据必须是一个由花括号{}指示的对象，例如 {"category": 1, "author": 2, "price": "3"}。 在此示例中，category、author 和 price 是键名，这些键可以通过名称一对一地映射到 StarRocks 表的列 category、author 和 price。

如果 JSON 文档的键与 StarRocks 表的列具有不同的名称，则您可以使用匹配模式加载 JSON 格式的数据。 在匹配模式下，您需要使用 jsonpaths 和 COLUMNS 参数来指定 JSON 文档和 StarRocks 表之间的列映射

  • 在 jsonpaths 参数中，按 JSON 文档中的排列顺序指定 JSON 键。
  • 在 COLUMNS 参数中，指定 JSON 键和 StarRocks 表列之间的映射
    • 在 COLUMNS 参数中指定的列名按顺序一对一地映射到 JSON 键。
    • COLUMNS 参数中指定的列名按名称一一映射到 StarRocks 表列。

有关使用匹配模式加载 JSON 格式的数据的示例，请参见使用匹配模式加载 JSON 数据。

返回值​

加载作业完成后，StarRocks 会以 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,
}

下表描述了返回的作业结果中的参数。

参数描述
TxnId加载作业的事务 ID。
Label导入作业的标签。
Status加载的数据的最终状态。
  • Success：数据已成功加载，可以查询。
  • Publish Timeout：加载作业已成功提交，但数据仍然无法查询。 您无需重试加载数据。
  • Label Already Exists：加载作业的标签已用于另一个加载作业。 数据可能已成功加载或正在加载。
  • Fail：数据加载失败。 您可以重试加载作业。
Message加载作业的状态。 如果加载作业失败，则会返回详细的失败原因。
NumberTotalRows读取的数据记录总数。
NumberLoadedRows成功加载的数据记录总数。 仅当为 Status 返回的值为 Success 时，此参数才有效。
NumberFilteredRows由于数据质量不足而被过滤掉的数据记录数。
NumberUnselectedRows被 WHERE 子句过滤掉的数据记录数。
LoadBytes加载的数据量。 单位：字节。
LoadTimeMs加载作业花费的时间。 单位：毫秒。
BeginTxnTimeMs为加载作业运行事务花费的时间。
StreamLoadPlanTimeMs为加载作业生成执行计划花费的时间。
ReadDataTimeMs为加载作业读取数据花费的时间。
WriteDataTimeMs为加载作业写入数据花费的时间。
CommitAndPublishTimeMs为加载作业提交和发布数据花费的时间。

如果加载作业失败，StarRocks 还会返回 ErrorURL。 示例

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

ErrorURL 提供了一个 URL，您可以从中获取有关已被过滤掉的不合格数据记录的详细信息。 您可以使用可选参数 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 命令来查看该文件。

然后，您可以调整加载作业的配置，并再次提交加载作业。

示例​

加载 CSV 数据​

本节以 CSV 数据为例，介绍如何使用各种参数设置和组合来满足您的各种加载需求。

设置超时时间​

您的 StarRocks 数据库 test_db 包含一个名为 table1 的表。 该表由三列组成，按顺序分别为 col1、col2 和 col3。

您的数据文件 example1.csv 也由三列组成，可以按顺序映射到 table1 的 col1、col2 和 col3。

如果您想要在最多 100 秒内将 example1.csv 中的所有数据加载到 table1 中，请运行以下命令

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

设置误差容限​

您的 StarRocks 数据库 test_db 包含一个名为 table2 的表。 该表由三列组成，按顺序分别为 col1、col2 和 col3。

您的数据文件 example2.csv 也由三列组成，可以按顺序映射到 table2 的 col1、col2 和 col3。

如果您想要以最大误差容限 0.2 将 example2.csv 中的所有数据加载到 table2 中，请运行以下命令

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

配置列映射​

您的 StarRocks 数据库 test_db 包含一个名为 table3 的表。 该表由三列组成，按顺序分别为 col1、col2 和 col3。

您的数据文件 example3.csv 也由三列组成，可以按顺序映射到 table3 的 col2、col1 和 col3。

如果您想要将 example3.csv 中的所有数据加载到 table3 中，请运行以下命令

curl --location-trusted -u <username>:<password>  -H "label:label3" \
    -H "Expect:100-continue" \
    -H "columns: col2, col1, col3" \
    -T example3.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table3/_stream_load

注意

在前面的示例中，example3.csv 的列不能以与这些列在 table3 中排列顺序相同的顺序映射到 table3 的列。 因此，您需要使用 columns 参数来配置 example3.csv 和 table3 之间的列映射。

设置过滤条件​

您的 StarRocks 数据库 test_db 包含一个名为 table4 的表。 该表由三列组成，按顺序分别为 col1、col2 和 col3。

您的数据文件 example4.csv 也由三列组成，可以按顺序映射到 table4 的 col1、col2 和 col3。

如果您想要仅将 example4.csv 第一列中的值等于 20180601 的数据记录加载到 table4 中，请运行以下命令

curl --location-trusted -u <username>:<password> -H "label:label4" \
    -H "Expect:100-continue" \
    -H "columns: col1, col2, col3"\
    -H "where: col1 = 20180601" \
    -T example4.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table4/_stream_load

注意

在前面的示例中，example4.csv 和 table4 具有相同数量的可以按顺序映射的列，但您需要使用 WHERE 子句来指定基于列的过滤条件。 因此，您需要使用 columns 参数为 example4.csv 的列定义临时名称。

设置目标分区​

您的 StarRocks 数据库 test_db 包含一个名为 table5 的表。 该表由三列组成，按顺序分别为 col1、col2 和 col3。

您的数据文件 example5.csv 也由三列组成，可以按顺序映射到 table5 的 col1、col2 和 col3。

如果您想将所有数据从 example5.csv 加载到 table5 的分区 p1 和 p2 中，请运行以下命令

curl --location-trusted -u <username>:<password>  -H "label:label5" \
    -H "Expect:100-continue" \
    -H "partitions: p1, p2" \
    -T example5.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table5/_stream_load

设置严格模式和时区​

您的 StarRocks 数据库 test_db 包含一个名为 table6 的表。该表由三列组成，依次为 col1、col2 和 col3。

您的数据文件 example6.csv 也由三列组成，这些列可以按顺序映射到 table6 的 col1、col2 和 col3。

如果您想使用严格模式和时区 Africa/Abidjan 将所有数据从 example6.csv 加载到 table6，请运行以下命令

curl --location-trusted -u <username>:<password> \
    -H "Expect:100-continue" \
    -H "strict_mode: true" \
    -H "timezone: Africa/Abidjan" \
    -T example6.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table6/_stream_load

将数据加载到包含 HLL 类型列的表中​

您的 StarRocks 数据库 test_db 包含一个名为 table7 的表。该表由两列 HLL 类型列组成，依次为 col1 和 col2。

您的数据文件 example7.csv 也由两列组成，其中第一列可以映射到 table7 的 col1，第二列无法映射到 table7 的任何列。 example7.csv 的第一列中的值可以通过函数转换为 HLL 类型数据，然后再加载到 table7 的 col1 中。

如果您想将数据从 example7.csv 加载到 table7，请运行以下命令

curl --location-trusted -u <username>:<password> \
    -H "Expect:100-continue" \
    -H "columns: temp1, temp2, col1=hll_hash(temp1), col2=hll_empty()" \
    -T example7.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table7/_stream_load

注意

在前面的示例中，example7.csv 的两列通过使用 columns 参数依次命名为 temp1 和 temp2。然后，使用函数转换数据，如下所示

  • hll_hash 函数用于将 example7.csv 的 temp1 中的值转换为 HLL 类型数据，并将 example7.csv 的 temp1 映射到 table7 的 col1。

  • hll_empty 函数用于将指定的默认值填充到 table7 的 col2 中。

有关函数 hll_hash 和 hll_empty 的用法，请参见 hll_hash 和 hll_empty。

将数据加载到包含 BITMAP 类型列的表中​

您的 StarRocks 数据库 test_db 包含一个名为 table8 的表。该表由两列 BITMAP 类型列组成，依次为 col1 和 col2。

您的数据文件 example8.csv 也由两列组成，其中第一列可以映射到 table8 的 col1，第二列无法映射到 table8 的任何列。 example8.csv 的第一列中的值可以通过函数转换后再加载到 table8 的 col1 中。

如果您想将数据从 example8.csv 加载到 table8，请运行以下命令

curl --location-trusted -u <username>:<password> \
    -H "Expect:100-continue" \
    -H "columns: temp1, temp2, col1=to_bitmap(temp1), col2=bitmap_empty()" \
    -T example8.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table8/_stream_load

注意

在前面的示例中，example8.csv 的两列通过使用 columns 参数依次命名为 temp1 和 temp2。然后，使用函数转换数据，如下所示

  • to_bitmap 函数用于将 example8.csv 的 temp1 中的值转换为 BITMAP 类型数据，并将 example8.csv 的 temp1 映射到 table8 的 col1。

  • bitmap_empty 函数用于将指定的默认值填充到 table8 的 col2 中。

有关函数 to_bitmap 和 bitmap_empty 的用法，请参见 to_bitmap 和 bitmap_empty。

设置 skip_header、trim_space、enclose 和 escape​

您的 StarRocks 数据库 test_db 包含一个名为 table9 的表。该表由三列组成，依次为 col1、col2 和 col3。

您的数据文件 example9.csv 也由三列组成，这些列按顺序映射到 table13 的 col2、col1 和 col3。

如果您想将所有数据从 example9.csv 加载到 table9，并打算跳过 example9.csv 的前五行，删除列分隔符之前和之后的空格，并将 enclose 设置为 \，将 escape 设置为 \，请运行以下命令

curl --location-trusted -u <username>:<password> -H "label:3875" \
    -H "Expect:100-continue" \
    -H "trim_space: true" -H "skip_header: 5" \
    -H "column_separator:," -H "enclose:\"" -H "escape:\\" \
    -H "columns: col2, col1, col3" \
    -T example9.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/tbl9/_stream_load

加载 JSON 数据​

本节介绍了加载 JSON 数据时需要注意的参数设置。

您的 StarRocks 数据库 test_db 包含一个名为 tbl1 的表，其 schema 如下

`category` varchar(512) NULL COMMENT "",`author` varchar(512) NULL COMMENT "",`title` varchar(512) NULL COMMENT "",`price` double NULL COMMENT ""

使用简单模式加载 JSON 数据​

假设您的数据文件 example1.json 包含以下数据

{"category":"C++","author":"avc","title":"C++ primer","price":895}

要将所有数据从 example1.json 加载到 tbl1，请运行以下命令

curl --location-trusted -u <username>:<password> -H "label:label6" \
    -H "Expect:100-continue" \
    -H "format: json" \
    -T example1.json -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/tbl1/_stream_load

注意

在前面的示例中，未指定参数 columns 和 jsonpaths。因此，example1.json 中的键按名称映射到 tbl1 的列。

为了提高吞吐量，Stream Load 支持一次加载多个数据记录。例子

[{"category":"C++","author":"avc","title":"C++ primer","price":89.5},{"category":"Java","author":"avc","title":"Effective Java","price":95},{"category":"Linux","author":"avc","title":"Linux kernel","price":195}]

使用匹配模式加载 JSON 数据​

StarRocks 执行以下步骤来匹配和处理 JSON 数据

  1. （可选）按照 strip_outer_array 参数设置的指示剥离最外层的数组结构。

    注意

    仅当 JSON 数据最外层是一个数组结构（由一对中括号 [] 指示）时，才会执行此步骤。您需要将 strip_outer_array 设置为 true。

  2. （可选）按照 json_root 参数设置的指示匹配 JSON 数据的根元素。

    注意

    仅当 JSON 数据具有根元素时，才会执行此步骤。您需要使用 json_root 参数指定根元素。

  3. 按照 jsonpaths 参数设置的指示提取指定的 JSON 数据。

使用匹配模式加载 JSON 数据，不指定根元素​

假设您的数据文件 example2.json 包含以下数据

[{"category":"xuxb111","author":"1avc","title":"SayingsoftheCentury","price":895},{"category":"xuxb222","author":"2avc","title":"SayingsoftheCentury","price":895},{"category":"xuxb333","author":"3avc","title":"SayingsoftheCentury","price":895}]

要仅从 example2.json 加载 category、author 和 price，请运行以下命令

curl --location-trusted -u <username>:<password> -H "label:label7" \
    -H "Expect:100-continue" \
    -H "format: json" \
    -H "strip_outer_array: true" \
    -H "jsonpaths: [\"$.category\",\"$.price\",\"$.author\"]" \
    -H "columns: category, price, author" \
    -T example2.json -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/tbl1/_stream_load

注意

在前面的示例中，JSON 数据最外层是一个数组结构（由一对中括号 [] 指示）。数组结构由多个 JSON 对象组成，每个对象代表一个数据记录。因此，您需要将 strip_outer_array 设置为 true，以剥离最外层的数组结构。在加载过程中，您不想加载的键 title 会被忽略。

使用匹配模式加载 JSON 数据，指定根元素​

假设您的数据文件 example3.json 包含以下数据

{"id": 10001,"RECORDS":[{"category":"11","title":"SayingsoftheCentury","price":895,"timestamp":1589191587},{"category":"22","author":"2avc","price":895,"timestamp":1589191487},{"category":"33","author":"3avc","title":"SayingsoftheCentury","timestamp":1589191387}],"comments": ["3 records", "there will be 3 rows"]}

要仅从 example3.json 加载 category、author 和 price，请运行以下命令

curl --location-trusted -u <username>:<password> \
    -H "Expect:100-continue" \
    -H "format: json" \
    -H "json_root: $.RECORDS" \
    -H "strip_outer_array: true" \
    -H "jsonpaths: [\"$.category\",\"$.price\",\"$.author\"]" \
    -H "columns: category, price, author" -H "label:label8" \
    -T example3.json -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/tbl1/_stream_load

注意

在前面的示例中，JSON 数据最外层是一个数组结构（由一对中括号 [] 指示）。数组结构由多个 JSON 对象组成，每个对象代表一个数据记录。因此，您需要将 strip_outer_array 设置为 true，以剥离最外层的数组结构。在加载过程中，您不想加载的键 title 和 timestamp 会被忽略。此外，json_root 参数用于指定 JSON 数据的根元素，该元素是一个数组。

合并 Stream Load 请求​

  • 运行以下命令以启动在同步模式下启用 Merge Commit 的 Stream Load 作业，并将合并窗口设置为 5000 毫秒，并行度设置为 2

    curl --location-trusted -u <username>:<password> \
        -H "Expect:100-continue" \
        -H "column_separator:," \
        -H "columns: id, name, score" \
        -H "enable_merge_commit:true" \
        -H "merge_commit_interval_ms:5000" \
        -H "merge_commit_parallel:2" \
        -T example1.csv -XPUT \
        http://<fe_host>:<fe_http_port>/api/mydatabase/table1/_stream_load

  • 运行以下命令以启动在异步模式下启用 Merge Commit 的 Stream Load 作业，并将合并窗口设置为 60000 毫秒，并行度设置为 2

    curl --location-trusted -u <username>:<password> \
        -H "Expect:100-continue" \
        -H "column_separator:," \
        -H "columns: id, name, score" \
        -H "enable_merge_commit:true" \
        -H "merge_commit_async:true" \
        -H "merge_commit_interval_ms:60000" \
        -H "merge_commit_parallel:2" \
        -T example1.csv -XPUT \
        http://<fe_host>:<fe_http_port>/api/mydatabase/table1/_stream_load