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

BROKER LOAD

StarRocks 提供了基于 MySQL 的加载方法 Broker Load。提交加载作业后，StarRocks 会异步运行该作业。您可以使用 SELECT * FROM information_schema.loads 查询作业结果。此功能自 v3.1 起受支持。有关背景信息、原理、支持的数据文件格式、如何执行单表加载和多表加载以及如何查看作业结果的更多信息，请参见加载概述。

只有具有 StarRocks 表的 INSERT 权限的用户才能将数据加载到 StarRocks 表中。如果您没有 INSERT 权限，请按照GRANT中提供的说明授予用于连接到 StarRocks 集群的用户的 INSERT 权限。语法为 GRANT INSERT ON TABLE <table_name> IN DATABASE <database_name> TO { ROLE <role_name> | USER <user_identity>}。

语法​

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 可选地指定目标表所属的数据库的名称。

每个加载作业都有一个标签，该标签在整个数据库中是唯一的。您可以使用加载作业的标签来查看加载作业的执行状态并防止重复加载相同的数据。当加载作业进入 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 的数据文件。

    您还可以通过使用通配符 ?、*、[]、{} 或 ^ 将此参数指定为多个数据文件的保存路径。请参见通配符参考。例如，您可以将此参数指定为 "hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/*/*" 或 "hdfs://<hdfs_host>:<hdfs_port>/user/data/tablename/dt=202104*/*" 以从 HDFS 服务器上的路径 /user/data/tablename 加载所有分区或仅 202104 分区中的数据文件。

    注意

    通配符也可以用于指定中间路径。

    在前面的示例中，hdfs_host 和 hdfs_port 参数描述如下

    • hdfs_host：HDFS 集群中 NameNode 主机的 IP 地址。

    • hdfs_host：HDFS 集群中 NameNode 主机的 FS 端口。默认端口号为 9000。

    注意

    • Broker Load 支持根据 S3 或 S3A 协议访问 AWS S3。因此，当您从 AWS S3 加载数据时，您可以将 s3:// 或 s3a:// 作为您作为文件路径传递的 S3 URI 中的前缀。
    • Broker Load 仅支持根据 gs 协议访问 Google GCS。因此，当您从 Google GCS 加载数据时，您必须将 gs:// 作为您作为文件路径传递的 GCS URI 中的前缀。
    • 当您从 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>/*。
    • 当您从 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>。
    • 当您从 Data Lake Storage Gen1 加载数据时，您必须使用 adl 协议来访问您的数据并将文件路径写为 adl://<data_lake_storage_gen1_name>.azuredatalakestore.net/<path>/<file_name>。

  • INTO TABLE

    指定目标 StarRocks 表的名称。

data_desc 也可以选择性地包含以下参数

  • NEGATIVE

    撤销特定批次数据的加载。要实现这一点，您需要加载具有指定 NEGATIVE 关键字的同一批次数据。

    注意

    此参数仅在 StarRocks 表是 Aggregate 表且其所有值列均由 sum 函数计算时才有效。

  • PARTITION

    指定要将数据加载到的分区。默认情况下，如果您未指定此参数，则源数据将加载到 StarRocks 表的所有分区中。

  • TEMPORARY PARTITION

    指定要将数据加载到的临时分区的名称。您可以指定多个临时分区，必须用逗号 (,) 分隔。

  • COLUMNS TERMINATED BY

    指定数据文件中使用的列分隔符。默认情况下，如果您未指定此参数，则此参数默认为 \t，表示制表符。您使用此参数指定的列分隔符必须与数据文件中实际使用的列分隔符相同。否则，由于数据质量不足，加载作业将失败，并且其 State 将为 CANCELLED。

    Broker Load 作业是根据 MySQL 协议提交的。StarRocks 和 MySQL 都转义加载请求中的字符。因此，如果列分隔符是诸如制表符之类的不可见字符，则必须在列分隔符前面添加反斜杠 ()。例如，如果列分隔符是 \t，则必须输入 \\t，如果列分隔符是 \n，则必须输入 \\n。Apache Hive™ 文件使用 \x01 作为其列分隔符，因此如果数据文件来自 Hive，则必须输入 \\x01。

    注意

    • 对于 CSV 数据，您可以使用 UTF-8 字符串，例如逗号 (,)、制表符或管道 (|)，其长度不超过 50 个字节作为文本分隔符。
    • 空值用 \N 表示。例如，数据文件包含三列，并且来自该数据文件的记录在第一列和第三列中包含数据，但在第二列中没有数据。在这种情况下，您需要在第二列中使用 \N 来表示空值。这意味着记录必须编译为 a,\N,b 而不是 a,,b。a,,b 表示记录的第二列包含一个空字符串。

  • ROWS TERMINATED BY

    指定数据文件中使用的行分隔符。默认情况下，如果您未指定此参数，则此参数默认为 \n，表示换行符。您使用此参数指定的行分隔符必须与数据文件中实际使用的行分隔符相同。否则，由于数据质量不足，加载作业将失败，并且其 State 将为 CANCELLED。此参数自 v2.5.4 起受支持。

    有关行分隔符的用法说明，请参见前面的 COLUMNS TERMINATED BY 参数的用法说明。

  • FORMAT AS

    指定数据文件的格式。有效值：CSV、Parquet 和 ORC。默认情况下，如果您未指定此参数，则 StarRocks 会根据 file_path 参数中指定的扩展名 .csv、.parquet 或 .orc 确定数据文件格式。

  • format_type_options

    当 FORMAT AS 设置为 CSV 时，指定 CSV 格式选项。语法

    (
        key = value
        key = value
        ...
    )

    注意

    format_type_options 在 v3.0 及更高版本中受支持。

    下表描述了这些选项。

    参数描述
    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。

  • column_list

    指定数据文件和 StarRocks 表之间的列映射。语法：(<column_name>[, <column_name> ...])。column_list 中声明的列按名称映射到 StarRocks 表列。

    注意

    如果数据文件的列按顺序映射到 StarRocks 表的列，则无需指定 column_list。

    如果要跳过数据文件的特定列，只需暂时将该列的名称设置为与任何 StarRocks 表列的名称不同。有关更多信息，请参见加载概述。

  • COLUMNS FROM PATH AS

    从您指定的文件路径中提取有关一个或多个分区字段的信息。此参数仅在文件路径包含分区字段时有效。

    例如，如果数据文件存储在路径 /path/col_name=col_value/file1 中，其中 col_name 是一个分区字段，可以映射到 StarRocks 表的列，则可以将此参数指定为 col_name。因此，StarRocks 从路径中提取 col_value 值，并将它们加载到映射了 col_name 的 StarRocks 表列中。

    注意

    此参数仅在从 HDFS 加载数据时可用。

  • SET

    指定要用于转换数据文件列的一个或多个函数。例子

    • StarRocks 表包含三个列，它们依次是 col1、col2 和 col3。数据文件包含四列，其中前两列按顺序映射到 StarRocks 表的 col1 和 col2，最后两列的总和映射到 StarRocks 表的 col3。在这种情况下，您需要将 column_list 指定为 (col1,col2,tmp_col3,tmp_col4)，并在 SET 子句中指定 (col3=tmp_col3+tmp_col4) 以实现数据转换。
    • StarRocks 表包含三个列，它们依次是 year、month 和 day。数据文件仅包含一个列，用于容纳 yyyy-mm-dd hh:mm:ss 格式的日期和时间值。在这种情况下，您需要将 column_list 指定为 (tmp_time)，并在 SET 子句中指定 (year = year(tmp_time), month=month(tmp_time), day=day(tmp_time)) 以实现数据转换。

  • WHERE

    指定要用于过滤源数据的条件。StarRocks 仅加载满足 WHERE 子句中指定的过滤器条件的源数据。

WITH BROKER​

在 v2.3 及更早版本中，输入 WITH BROKER "<broker_name>" 以指定要使用的 broker。从 v2.5 开始，您不再需要指定 broker，但仍然需要保留 WITH BROKER 关键字。

StorageCredentialParams​

StarRocks 用于访问您的存储系统的身份验证信息。

HDFS​

开源 HDFS 支持两种身份验证方法：简单身份验证和 Kerberos 身份验证。Broker Load 默认使用简单身份验证。开源 HDFS 还支持为 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：principal 的名称。
      • instance：托管要在 HDFS 集群中进行身份验证的节点的服务器的名称。服务器名称有助于确保 principal 是唯一的，例如，当 HDFS 集群由多个 DataNode 组成时，每个 DataNode 都是独立进行身份验证的。
      • realm：realm 的名称。realm 名称必须大写。
      示例：nn/zelda1@ZELDA.COM。
      kerberos_keytabKerberos keytab 文件的保存路径。
      kerberos_keytab_contentKerberos keytab 文件的 Base64 编码内容。您可以选择指定 kerberos_keytab 或 kerberos_keytab_content。

  • HA 配置

    您可以为 HDFS 集群的 NameNode 配置 HA 机制。这样，如果 NameNode 切换到另一个节点，StarRocks 可以自动识别用作 NameNode 的新节点。这包括以下场景

    • 如果您从配置了一个 Kerberos 用户的单个 HDFS 集群加载数据，则支持基于 broker 的加载和无 broker 加载。

      • 要执行基于 broker 的加载，请确保至少部署了一个独立的 broker 组，并将 hdfs-site.xml 文件放在 broker 节点上服务 HDFS 集群的 {deploy}/conf 路径中。StarRocks 会在 broker 启动时将 {deploy}/conf 路径添加到环境变量 CLASSPATH，从而允许 broker 读取有关 HDFS 集群节点的信息。

      • 要执行无 broker 加载，您只需要在集群中所有 FE、BE 和 CN 节点的部署目录下的 conf/core-site.xml 中设置 hadoop.security.authentication = kerberos，并使用 kinit 命令配置 Kerberos 帐户。

    • 如果您从配置了多个 Kerberos 用户的单个 HDFS 集群加载数据，则仅支持基于 broker 的加载。确保至少部署了一个独立的 broker 组，并将 hdfs-site.xml 文件放在 broker 节点上服务 HDFS 集群的 {deploy}/conf 路径中。StarRocks 会在 broker 启动时将 {deploy}/conf 路径添加到环境变量 CLASSPATH，从而允许 broker 读取有关 HDFS 集群节点的信息。

    • 如果您从多个 HDFS 集群加载数据（无论是否配置了一个或多个 Kerberos 用户），则仅支持基于 broker 的加载。确保为每个 HDFS 集群部署至少一个独立的 broker 组，并执行以下操作之一以使 broker 能够读取有关 HDFS 集群节点的信息

      • 将 hdfs-site.xml 文件放在 broker 节点上服务每个 HDFS 集群的 {deploy}/conf 路径中。StarRocks 会在 broker 启动时将 {deploy}/conf 路径添加到环境变量 CLASSPATH，从而允许 broker 读取有关该 HDFS 集群中的节点的信息。

      • 在作业创建时添加以下 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"

        下表描述了 HA 配置中的参数。

        参数描述
        dfs.nameservicesHDFS 集群的名称。
        dfs.ha.namenodes.XXXHDFS 集群中 NameNode 的名称。如果您指定多个 NameNode 名称，请用逗号 (,) 分隔它们。xxx 是您在 dfs.nameservices 中指定的 HDFS 集群名称。
        dfs.namenode.rpc-address.XXX.NNHDFS 集群中 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

    "aws.s3.use_instance_profile" = "true",
    "aws.s3.region" = "<aws_s3_region>"

  • 要选择基于假设角色的身份验证方法，请按如下方式配置 StorageCredentialParams

    "aws.s3.use_instance_profile" = "true",
    "aws.s3.iam_role_arn" = "<iam_role_arn>",
    "aws.s3.region" = "<aws_s3_region>"

  • 要选择基于 IAM 用户的身份验证方法，请按如下方式配置 StorageCredentialParams

    "aws.s3.use_instance_profile" = "false",
    "aws.s3.access_key" = "<iam_user_access_key>",
    "aws.s3.secret_key" = "<iam_user_secret_key>",
    "aws.s3.region" = "<aws_s3_region>"

下表描述了需要在 StorageCredentialParams 中配置的参数。

参数必需描述
aws.s3.use_instance_profile是指定是否启用凭证方法实例配置文件和假设角色。有效值：true 和 false。默认值：false。
aws.s3.iam_role_arn否具有对您的 AWS S3 bucket 的权限的 IAM 角色的 ARN。如果您选择假设角色作为访问 AWS S3 的凭证方法，则必须指定此参数。
aws.s3.region是您的 AWS S3 bucket 所在的区域。示例：us-west-1。
aws.s3.access_key否您的 IAM 用户的访问密钥。如果您选择 IAM 用户作为访问 AWS S3 的凭证方法，则必须指定此参数。
aws.s3.secret_key否您的 IAM 用户的密钥。如果您选择 IAM 用户作为访问 AWS S3 的凭证方法，则必须指定此参数。

有关如何选择访问 AWS S3 的身份验证方法以及如何在 AWS IAM Console 中配置访问控制策略的信息，请参见访问 AWS S3 的身份验证参数。

Google GCS​

如果您选择 Google GCS 作为您的存储系统，请执行以下操作之一

  • 要选择基于 VM 的身份验证方法，请按如下方式配置 StorageCredentialParams

    "gcp.gcs.use_compute_engine_service_account" = "true"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数默认值值 示例描述
    gcp.gcs.use_compute_engine_service_accountfalsetrue指定是否直接使用绑定到您的 Compute Engine 的服务帐户。

  • 要选择基于服务帐户的身份验证方法，请按如下方式配置 StorageCredentialParams

    "gcp.gcs.service_account_email" = "<google_service_account_email>",
    "gcp.gcs.service_account_private_key_id" = "<google_service_private_key_id>",
    "gcp.gcs.service_account_private_key" = "<google_service_private_key>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数默认值值 示例描述
    gcp.gcs.service_account_email"""user@hello.iam.gserviceaccount.com"在创建服务帐户时生成的 JSON 文件中的电子邮件地址。
    gcp.gcs.service_account_private_key_id"""61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"在创建服务帐户时生成的 JSON 文件中的私钥 ID。
    gcp.gcs.service_account_private_key"""-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"在创建服务帐户时生成的 JSON 文件中的私钥。

  • 要选择基于模拟的身份验证方法，请按如下方式配置 StorageCredentialParams

    • 使 VM 实例模拟服务帐户

      "gcp.gcs.use_compute_engine_service_account" = "true",
      "gcp.gcs.impersonation_service_account" = "<assumed_google_service_account_email>"

      下表描述了需要在 StorageCredentialParams 中配置的参数。

      参数默认值值 示例描述
      gcp.gcs.use_compute_engine_service_accountfalsetrue指定是否直接使用绑定到您的 Compute Engine 的服务帐户。
      gcp.gcs.impersonation_service_account"""hello"您要模拟的服务帐户。

    • 使服务帐户（命名为元服务帐户）模拟另一个服务帐户（命名为数据服务帐户）

      "gcp.gcs.service_account_email" = "<google_service_account_email>",
      "gcp.gcs.service_account_private_key_id" = "<meta_google_service_account_email>",
      "gcp.gcs.service_account_private_key" = "<meta_google_service_account_email>",
      "gcp.gcs.impersonation_service_account" = "<data_google_service_account_email>"

      下表描述了需要在 StorageCredentialParams 中配置的参数。

      参数默认值值 示例描述
      gcp.gcs.service_account_email"""user@hello.iam.gserviceaccount.com"在创建元服务帐户时生成的 JSON 文件中的电子邮件地址。
      gcp.gcs.service_account_private_key_id"""61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"在创建元服务帐户时生成的 JSON 文件中的私钥 ID。
      gcp.gcs.service_account_private_key"""-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"在创建元服务帐户时生成的 JSON 文件中的私钥。
      gcp.gcs.impersonation_service_account"""hello"您要模拟的数据服务帐户。

其他 S3 兼容存储系统​

如果您选择其他 S3 兼容存储系统（例如 MinIO），请按如下方式配置 StorageCredentialParams

"aws.s3.enable_ssl" = "false",
"aws.s3.enable_path_style_access" = "true",
"aws.s3.endpoint" = "<s3_endpoint>",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_secret_key>"

下表描述了需要在 StorageCredentialParams 中配置的参数。

参数必需描述
aws.s3.enable_ssl是指定是否启用 SSL 连接。有效值：true 和 false。默认值：true。
aws.s3.enable_path_style_access是指定是否启用路径样式 URL 访问。有效值：true 和 false。默认值：false。对于 MinIO，您必须将值设置为 true。
aws.s3.endpoint是用于连接到您的 S3 兼容存储系统而不是 AWS S3 的端点。
aws.s3.access_key是您的 IAM 用户的访问密钥。
aws.s3.secret_key是您的 IAM 用户的密钥。

Microsoft Azure Storage​

Azure Blob Storage​

如果您选择 Blob Storage 作为您的存储系统，请执行以下操作之一

  • 要选择共享密钥身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.blob.storage_account" = "<storage_account_name>",
    "azure.blob.shared_key" = "<storage_account_shared_key>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.blob.storage_account是您的 Blob Storage 帐户的用户名。
    azure.blob.shared_key是您的 Blob Storage 帐户的共享密钥。

  • 要选择 SAS 令牌身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.blob.storage_account" = "<storage_account_name>",
    "azure.blob.container" = "<container_name>",
    "azure.blob.sas_token" = "<storage_account_SAS_token>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.blob.storage_account是您的 Blob Storage 帐户的用户名。
    azure.blob.container是存储数据的 Blob 容器的名称。
    azure.blob.sas_token是用于访问 Blob 存储帐户的 SAS 令牌。
Azure Data Lake Storage Gen2​

如果选择 Data Lake Storage Gen2 作为存储系统，请执行以下操作之一

  • 要选择托管标识身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.adls2.oauth2_use_managed_identity" = "true",
    "azure.adls2.oauth2_tenant_id" = "<service_principal_tenant_id>",
    "azure.adls2.oauth2_client_id" = "<service_client_id>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.adls2.oauth2_use_managed_identity是指定是否启用托管标识身份验证方法。将值设置为 true。
    azure.adls2.oauth2_tenant_id是您要访问其数据的租户的 ID。
    azure.adls2.oauth2_client_id是托管标识的客户端（应用程序）ID。

  • 要选择共享密钥身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.adls2.storage_account" = "<storage_account_name>",
    "azure.adls2.shared_key" = "<storage_account_shared_key>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.adls2.storage_account是您的 Data Lake Storage Gen2 存储帐户的用户名。
    azure.adls2.shared_key是您的 Data Lake Storage Gen2 存储帐户的共享密钥。

  • 要选择服务主体身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.adls2.oauth2_client_id" = "<service_client_id>",
    "azure.adls2.oauth2_client_secret" = "<service_principal_client_secret>",
    "azure.adls2.oauth2_client_endpoint" = "<service_principal_client_endpoint>"

    下表描述了您需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.adls2.oauth2_client_id是服务主体的客户端（应用程序）ID。
    azure.adls2.oauth2_client_secret是创建的新客户端（应用程序）密钥的值。
    azure.adls2.oauth2_client_endpoint是服务主体或应用程序的 OAuth 2.0 令牌端点 (v1)。
Azure Data Lake Storage Gen1​

如果选择 Data Lake Storage Gen1 作为存储系统，请执行以下操作之一

  • 要选择托管服务标识身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.adls1.use_managed_service_identity" = "true"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.adls1.use_managed_service_identity是指定是否启用托管服务标识身份验证方法。将值设置为 true。

  • 要选择服务主体身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.adls1.oauth2_client_id" = "<application_client_id>",
    "azure.adls1.oauth2_credential" = "<application_client_credential>",
    "azure.adls1.oauth2_endpoint" = "<OAuth_2.0_authorization_endpoint_v2>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.adls1.oauth2_client_id是的客户端（应用程序）ID。
    azure.adls1.oauth2_credential是创建的新客户端（应用程序）密钥的值。
    azure.adls1.oauth2_endpoint是服务主体或应用程序的 OAuth 2.0 令牌端点 (v1)。

opt_properties​

指定一些可选参数，这些参数的设置应用于整个加载作业。语法

PROPERTIES ("<key1>" = "<value1>"[, "<key2>" = "<value2>" ...])

支持以下参数

  • timeout

    指定加载作业的超时时间。单位：秒。默认超时时间为 4 小时。建议您指定一个短于 6 小时的超时时间。如果加载作业未在超时时间内完成，StarRocks 会取消加载作业，并且加载作业的状态变为 CANCELLED。

    注意

    在大多数情况下，您不需要设置超时时间。建议您仅在加载作业无法在默认超时时间内完成时才设置超时时间。

    使用以下公式来推断超时时间

    超时时间 > (要加载的数据文件的总大小 x 要加载的数据文件的总数以及在数据文件上创建的物化视图数)/平均加载速度

    注意

    “平均加载速度”是整个 StarRocks 集群的平均加载速度。平均加载速度因每个集群而异，具体取决于服务器配置和集群允许的最大并发查询任务数。您可以根据历史加载作业的加载速度来推断平均加载速度。

    假设您想要加载一个 1-GB 的数据文件，该文件上创建了两个物化视图，并将其加载到平均加载速度为 10 MB/s 的 StarRocks 集群中。数据加载所需的时间约为 102 秒。

    (1 x 1024 x 3)/10 = 307.2 (秒)

    对于此示例，我们建议您将超时时间设置为大于 308 秒的值。

  • max_filter_ratio

    指定加载作业的最大错误容忍度。最大错误容忍度是由于数据质量不足而被过滤掉的行的最大百分比。有效值：0~1。默认值：0。

    • 如果将此参数设置为 0，StarRocks 在加载期间不会忽略不合格的行。因此，如果源数据包含不合格的行，则加载作业将失败。这有助于确保加载到 StarRocks 中的数据的正确性。

    • 如果将此参数设置为大于 0 的值，StarRocks 可以在加载期间忽略不合格的行。因此，即使源数据包含不合格的行，加载作业也可以成功。

      注意

      由于数据质量不足而被过滤掉的行不包括被 WHERE 子句过滤掉的行。

    如果由于最大错误容忍度设置为 0 而导致加载作业失败，则可以使用 SHOW LOAD 来查看作业结果。然后，确定是否可以过滤掉不合格的行。如果可以过滤掉不合格的行，则根据作业结果中返回的 dpp.abnorm.ALL 和 dpp.norm.ALL 的值计算最大错误容忍度，调整最大错误容忍度，然后再次提交加载作业。计算最大错误容忍度的公式如下

    max_filter_ratio = [dpp.abnorm.ALL/(dpp.abnorm.ALL + dpp.norm.ALL)]

    dpp.abnorm.ALL 和 dpp.norm.ALL 返回的值之和是要加载的行总数。

  • log_rejected_record_num

    指定可以记录的不合格数据行的最大数量。此参数从 v3.1 开始支持。有效值：0、-1 和任何非零正整数。默认值：0。

    • 值 0 指定将不记录被过滤掉的数据行。
    • 值 -1 指定将记录所有被过滤掉的数据行。
    • 一个非零正整数（例如 n）指定每个 BE 上最多可以记录 n 个被过滤掉的数据行。

  • load_mem_limit

    指定可以为加载作业提供的最大内存量。此参数的值不能超过每个 BE 或 CN 节点支持的内存上限。单位：字节：默认内存限制为 2 GB。

  • strict_mode

    指定是否启用严格模式。有效值：true 和 false。默认值：false。true 指定启用严格模式，false 指定禁用严格模式。

  • timezone

    指定加载作业的时区。默认值：Asia/Shanghai。时区设置会影响 strftime、alignment_timestamp 和 from_unixtime 等函数返回的结果。有关更多信息，请参阅配置时区。timezone 参数中指定的时区是会话级时区。

  • priority

    指定加载作业的优先级。有效值：LOWEST、LOW、NORMAL、HIGH 和 HIGHEST。默认值：NORMAL。Broker Load 提供 FE 参数 max_broker_load_job_concurrency，用于确定 StarRocks 集群中可以并发运行的 Broker Load 作业的最大数量。如果在指定的时间段内提交的 Broker Load 作业数量超过最大数量，则过多的作业将根据其优先级排队等待调度。

    您可以使用 ALTER LOAD 语句来更改处于 QUEUEING 或 LOADING 状态的现有加载作业的优先级。

    StarRocks 从 v2.5 开始允许为 Broker Load 作业设置 priority 参数。

  • partial_update

    是否使用部分更新。有效值：TRUE 和 FALSE。默认值：FALSE，表示禁用此功能。

  • partial_update_mode

    指定部分更新的模式。有效值：row 和 column。

    • 值 row（默认）表示行模式下的部分更新，更适合具有许多列和小批量的实时更新。
    • 值 column 表示列模式下的部分更新，更适合具有少量列和大量行的批量更新。在这种情况下，启用列模式可以提供更快的更新速度。例如，在一个具有 100 列的表中，如果仅更新所有行的 10 列（占总数的 10%），则列模式的更新速度是 10 倍。

  • merge_condition

    指定要用作条件的列的名称，以确定更新是否可以生效。仅当源数据记录在指定列中具有大于或等于目标数据记录的值时，从源记录到目标记录的更新才会生效。

    注意

    您指定的列不能是主键列。此外，只有使用主键表的表才支持条件更新。

StarRocks 从 v3.2.3 开始支持加载 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 数据”部分。

加载 JSON 数据时，还要注意每个 JSON 对象的大小不能超过 4 GB。如果 JSON 数据文件中的单个 JSON 对象的大小超过 4 GB，则会报告错误“This parser can't support a document that big.”。

列映射​

配置 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 数据。

FE 配置项 max_broker_load_job_concurrency 指定 StarRocks 集群中可以并发运行的 Broker Load 作业的最大数量。

在 StarRocks v2.4 及更早版本中，如果在特定时间段内提交的 Broker Load 作业总数超过最大数量，则过多的作业将根据其提交时间排队并进行调度。

从 StarRocks v2.5 开始，如果在特定时间段内提交的 Broker Load 作业总数超过最大数量，则过多的作业将根据其优先级排队并进行调度。您可以使用上述 priority 参数为作业指定优先级。您可以使用 ALTER LOAD 修改处于 QUEUEING 或 LOADING 状态的现有作业的优先级。

作业拆分和并发运行​

Broker Load 作业可以拆分为一个或多个并发运行的任务。加载作业中的任务在单个事务中运行。它们必须全部成功或全部失败。StarRocks 根据您在 LOAD 语句中声明 data_desc 的方式拆分每个加载作业

  • 如果您声明多个 data_desc 参数，每个参数都指定一个不同的表，则会生成一个任务来加载每个表的数据。

  • 如果您声明多个 data_desc 参数，每个参数都指定同一表的不同分区，则会生成一个任务来加载每个分区的数据。

此外，每个任务可以进一步拆分为一个或多个实例，这些实例均匀分布并在 StarRocks 集群的 BE 或 CN 上并发运行。StarRocks 根据 FE 参数 min_bytes_per_broker_scanner 和 BE 或 CN 节点的数量拆分每个任务。您可以使用以下公式来计算单个任务中的实例数

单个任务中的实例数 = min(单个任务要加载的数据量/min_bytes_per_broker_scanner, BE/CN 节点的数量)

在大多数情况下，每个加载作业仅声明一个 data_desc，每个加载作业仅拆分为一个任务，并且该任务拆分的实例数与 BE 或 CN 节点的数量相同。

示例​

本节以 HDFS 为例，介绍各种加载配置。

加载 CSV 数据​

本节以 CSV 为例，解释您可以使用的各种参数配置，以满足您不同的加载需求。

设置超时时间​

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

您的数据文件 example1.csv 也由三个列组成，这些列依次映射到 table1 的 col1、col2 和 col3。

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

LOAD LABEL test_db.label1
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example1.csv")
    INTO TABLE table1
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
)
PROPERTIES
(
    "timeout" = "3600"
);

设置最大错误容忍度​

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

您的数据文件 example2.csv 也由三个列组成，这些列依次映射到 table2 的 col1、col2 和 col3。

如果您想将所有数据从 example2.csv 加载到 table2 中，最大错误容忍度为 0.1，请运行以下命令

LOAD LABEL test_db.label2
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example2.csv")
    INTO TABLE table2

)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
)
PROPERTIES
(
    "max_filter_ratio" = "0.1"
);

从文件路径加载所有数据文件​

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

存储在 HDFS 集群的 /user/starrocks/data/input/ 路径中的所有数据文件也分别由三个列组成，这些列依次映射到 table3 的 col1、col2 和 col3。这些数据文件中使用的列分隔符为 \x01。

如果您想将数据从存储在 hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/ 路径中的所有这些数据文件加载到 table3 中，请运行以下命令

LOAD LABEL test_db.label3
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/*")
    INTO TABLE table3
    COLUMNS TERMINATED BY "\\x01"
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

设置 NameNode HA 机制​

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

您的数据文件 example4.csv 也由三个列组成，这些列映射到 table4 的 col1、col2 和 col3。

如果您想将所有数据从 example4.csv 加载到 table4 中，并为 NameNode 配置了 HA 机制，请运行以下命令

LOAD LABEL test_db.label4
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example4.csv")
    INTO TABLE table4
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>",
    "dfs.nameservices" = "my_ha",
    "dfs.ha.namenodes.my_ha" = "my_namenode1, my_namenode2","dfs.namenode.rpc-address.my_ha.my_namenode1" = "nn1_host:rpc_port",
    "dfs.namenode.rpc-address.my_ha.my_namenode2" = "nn2_host:rpc_port",
    "dfs.client.failover.proxy.provider" = "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider"
);

设置 Kerberos 身份验证​

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

您的数据文件 example5.csv 也由三个列组成，这些列依次映射到 table5 的 col1、col2 和 col3。

如果您想将所有数据从 example5.csv 加载到 table5 中，并配置了 Kerberos 身份验证并指定了 keytab 文件路径，请运行以下命令

LOAD LABEL test_db.label5
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example5.csv")
    INTO TABLE table5
    COLUMNS TERMINATED BY "\t"
)
WITH BROKER
(
    "hadoop.security.authentication" = "kerberos",
    "kerberos_principal" = "starrocks@YOUR.COM",
    "kerberos_keytab" = "/home/starRocks/starRocks.keytab"
);

撤销数据加载​

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

您的数据文件 example6.csv 也由三个列组成，这些列依次映射到 table6 的 col1、col2 和 col3。

您已通过运行 Broker Load 作业将所有数据从 example6.csv 加载到 table6 中。

如果您想撤销已加载的数据，请运行以下命令

LOAD LABEL test_db.label6
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example6.csv")
    NEGATIVE
    INTO TABLE table6
    COLUMNS TERMINATED BY "\t"
)
WITH BROKER
(
    "hadoop.security.authentication" = "kerberos",
    "kerberos_principal" = "starrocks@YOUR.COM",
    "kerberos_keytab" = "/home/starRocks/starRocks.keytab"
);

指定目标分区​

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

您的数据文件 example7.csv 也由三个列组成，这些列依次映射到 table7 的 col1、col2 和 col3。

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

LOAD LABEL test_db.label7
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example7.csv")
    INTO TABLE table7
    PARTITION (p1, p2)
    COLUMNS TERMINATED BY ","
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

配置列映射​

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

您的数据文件 example8.csv 也由三个列组成，这些列依次映射到 table8 的 col2、col1 和 col3。

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

LOAD LABEL test_db.label8
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example8.csv")
    INTO TABLE table8
    COLUMNS TERMINATED BY ","
    (col2, col1, col3)
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

在前面的示例中，example8.csv 的列无法按照这些列在 table8 中排列的相同顺序映射到 table8 的列。因此，您需要使用 column_list 来配置 example8.csv 和 table8 之间的列映射。

设置过滤条件​

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

您的数据文件 example9.csv 也由三个列组成，这些列依次映射到 table9 的 col1、col2 和 col3。

如果您只想将第一列中的值大于 20180601 的数据记录从 example9.csv 加载到 table9 中，请运行以下命令

LOAD LABEL test_db.label9
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example9.csv")
    INTO TABLE table9
    (col1, col2, col3)
    where col1 > 20180601
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

在前面的示例中，example9.csv 的列可以按照这些列在 table9 中排列的相同顺序映射到 table9 的列，但是您需要使用 WHERE 子句来指定基于列的过滤条件。因此，您需要使用 column_list 来配置 example9.csv 和 table9 之间的列映射。

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

您的 StarRocks 数据库 test_db 包含一个名为 table10 的表。该表由四个列组成，它们依次为 id、col1、col2 和 col3。col1 和 col2 定义为 HLL 类型列。

您的数据文件 example10.csv 由三个列组成，其中第一列映射到 table10 的 id，第二列和第三列依次映射到 table10 的 col1 和 col2。可以通过使用函数将 example10.csv 的第二列和第三列中的值转换为 HLL 类型数据，然后将它们加载到 table10 的 col1 和 col2 中。

如果您想将所有数据从 example10.csv 加载到 table10 中，请运行以下命令

LOAD LABEL test_db.label10
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example10.csv")
    INTO TABLE table10
    COLUMNS TERMINATED BY ","
    (id, temp1, temp2)
    SET
    (
        col1 = hll_hash(temp1),
        col2 = hll_hash(temp2),
        col3 = empty_hll()
     )
 )
 WITH BROKER
 (
     "username" = "<hdfs_username>",
     "password" = "<hdfs_password>"
 );

注意

在前面的示例中，example10.csv 的三个列分别使用 column_list 命名为 id、temp1 和 temp2。然后，使用函数转换数据，如下所示

  • hll_hash 函数用于将 example10.csv 的 temp1 和 temp2 中的值转换为 HLL 类型数据，并将 example10.csv 的 temp1 和 temp2 映射到 table10 的 col1 和 col2。

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

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

从文件路径中提取分区字段值​

Broker Load 支持根据目标 StarRocks 表的列定义解析文件路径中包含的特定分区字段的值。StarRocks 的此功能类似于 Apache Spark™ 的分区发现功能。

您的 StarRocks 数据库 test_db 包含一个名为 table11 的表。该表由五个列组成，它们依次为 col1、col2、col3、city 和 utc_date。

您的 HDFS 集群的文件路径 /user/starrocks/data/input/dir/city=beijing 包含以下数据文件

  • /user/starrocks/data/input/dir/city=beijing/utc_date=2019-06-26/0000.csv

  • /user/starrocks/data/input/dir/city=beijing/utc_date=2019-06-26/0001.csv

这些数据文件分别由三个列组成，这些列依次映射到 table11 的 col1、col2 和 col3。

如果您想将数据从文件路径 /user/starrocks/data/input/dir/city=beijing/utc_date=*/* 中的所有数据文件加载到 table11 中，并且同时想提取文件路径中包含的分区字段 city 和 utc_date 的值，并将提取的值加载到 table11 的 city 和 utc_date 中，请运行以下命令

LOAD LABEL test_db.label11
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/dir/city=beijing/*/*")
    INTO TABLE table11
    FORMAT AS "csv"
    (col1, col2, col3)
    COLUMNS FROM PATH AS (city, utc_date)
    SET (uniq_id = md5sum(k1, city))
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

从包含 %3A 的文件路径中提取分区字段值​

在 HDFS 中，文件路径不能包含冒号 (:)。所有冒号 (:) 将转换为 %3A。

您的 StarRocks 数据库 test_db 包含一个名为 table12 的表。该表由三个列组成，它们依次为 data_time、col1 和 col2。表架构如下

data_time DATETIME,
col1        INT,
col2        INT

您的 HDFS 集群的文件路径 /user/starrocks/data 包含以下数据文件

  • /user/starrocks/data/data_time=2020-02-17 00%3A00%3A00/example12.csv

  • /user/starrocks/data/data_time=2020-02-18 00%3A00%3A00/example12.csv

如果您想将所有数据从 example12.csv 加载到 table12 中，并且同时想从文件路径中提取分区字段 data_time 的值，并将提取的值加载到 table12 的 data_time 中，请运行以下命令

LOAD LABEL test_db.label12
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/*/example12.csv")
    INTO TABLE table12
    COLUMNS TERMINATED BY ","
    FORMAT AS "csv"
    (col1,col2)
    COLUMNS FROM PATH AS (data_time)
    SET (data_time = str_to_date(data_time, '%Y-%m-%d %H%%3A%i%%3A%s'))
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

在前面的示例中，从分区字段 data_time 提取的值是包含 %3A 的字符串，例如 2020-02-17 00%3A00%3A00。因此，您需要使用 str_to_date 函数将字符串转换为 DATETIME 类型数据，然后将它们加载到 table8 的 data_time 中。

设置 format_type_options​

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

您的数据文件 example13.csv 也由三个列组成，这些列依次映射到 table13 的 col2、col1 和 col3。

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

LOAD LABEL test_db.label13
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/*/example13.csv")
    INTO TABLE table13
    COLUMNS TERMINATED BY ","
    FORMAT AS "CSV"
    (
        skip_header = 2
        trim_space = TRUE
        enclose = "\""
        escape = "\\"
    )
    (col2, col1, col3)
)
WITH BROKER
(
    "username" = "hdfs_username",
    "password" = "hdfs_password"
)
PROPERTIES
(
    "timeout" = "3600"
);

加载 Parquet 数据​

本节介绍加载 Parquet 数据时需要注意的一些参数设置。

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

您的数据文件 example13.parquet 也包含三列，它们按顺序映射到 table13 的 col1、col2 和 col3。

如果您想将 example13.parquet 中的所有数据加载到 table13，请运行以下命令

LOAD LABEL test_db.label13
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example13.parquet")
    INTO TABLE table13
    FORMAT AS "parquet"
    (col1, col2, col3)
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

默认情况下，当您加载 Parquet 数据时，StarRocks 会根据文件名是否包含扩展名 .parquet 来确定数据文件格式。如果文件名不包含扩展名 .parquet，您必须使用 FORMAT AS 将数据文件格式指定为 Parquet。

加载 ORC 数据​

本节介绍加载 ORC 数据时需要注意的一些参数设置。

您的 StarRocks 数据库 test_db 包含一个名为 table14 的表。该表包含三列，它们按顺序为 col1、col2 和 col3。

您的数据文件 example14.orc 也包含三列，它们按顺序映射到 table14 的 col1、col2 和 col3。

如果您想将 example14.orc 中的所有数据加载到 table14，请运行以下命令

LOAD LABEL test_db.label14
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example14.orc")
    INTO TABLE table14
    FORMAT AS "orc"
    (col1, col2, col3)
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

  • 默认情况下，当您加载 ORC 数据时，StarRocks 会根据文件名是否包含扩展名 .orc 来确定数据文件格式。如果文件名不包含扩展名 .orc，您必须使用 FORMAT AS 将数据文件格式指定为 ORC。

  • 在 StarRocks v2.3 及更早版本中，如果数据文件包含 ARRAY 类型列，则必须确保 ORC 数据文件的列与 StarRocks 表中的映射列具有相同的名称，并且不能在 SET 子句中指定这些列。

加载 JSON 数据​

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

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

`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，请运行以下命令

LOAD LABEL test_db.label15
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example1.csv")
    INTO TABLE tbl1
    FORMAT AS "json"
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
);

注意

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

使用匹配模式加载 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，请运行以下命令

LOAD LABEL test_db.label16
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example2.csv")
    INTO TABLE tbl1
    FORMAT AS "json"
    (category, price, author)
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
)
PROPERTIES
(
    "strip_outer_array" = "true",
    "jsonpaths" = "[\"$.category\",\"$.price\",\"$.author\"]"
);

注意

在前面的示例中，JSON 数据最外层是一个数组结构，由一对中括号 [] 表示。数组结构由多个 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，请运行以下命令

LOAD LABEL test_db.label17
(
    DATA INFILE("hdfs://<hdfs_host>:<hdfs_port>/user/starrocks/data/input/example3.csv")
    INTO TABLE tbl1
    FORMAT AS "json"
    (category, price, author)
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
)
PROPERTIES
(
    "json_root"="$.RECORDS",
    "strip_outer_array" = "true",
    "jsonpaths" = "[\"$.category\",\"$.price\",\"$.author\"]"
);

注意

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