跳到主要内容
版本：4.0

Iceberg catalog

提示

此示例使用了在 StarRocks Basics 快速入门中介绍的本地气候数据 (LCD) 数据集。您可以导入数据并亲自尝试该示例。

Iceberg catalog 是一种外部 catalog，从 StarRocks v2.4 开始支持。使用 Iceberg catalog，您可以：

  • 直接查询存储在 Iceberg 中的数据，无需手动创建表。
  • 使用 INSERT INTO 或异步物化视图（从 v2.5 开始支持）来处理存储在 Iceberg 中的数据，并将数据导入到 StarRocks 中。
  • 在 StarRocks 上执行操作以创建或删除 Iceberg 数据库和表，或使用 INSERT INTO 将 StarRocks 表中的数据下沉到 Parquet 格式的 Iceberg 表中（此功能从 v3.1 开始支持）。

为了确保在 Iceberg 集群上的 SQL 工作负载成功，您的 StarRocks 集群必须能够访问 Iceberg 集群的存储系统和元存储。StarRocks 支持以下存储系统和元存储：

  • 分布式文件系统（HDFS）或对象存储，如 AWS S3、Microsoft Azure Storage、Google GCS 或其他 S3 兼容的存储系统（例如 MinIO）

  • 元存储如 Hive metastore、AWS Glue 或 Tabular

备注
  • 如果选择 AWS S3 作为存储，可以使用 HMS 或 AWS Glue 作为元存储。如果选择其他存储系统，则只能使用 HMS 作为元存储。
  • 如果选择 Tabular 作为元存储，则需要使用 Iceberg REST catalog。

使用注意事项​

使用 StarRocks 查询 Iceberg 数据时，请注意以下几点：

文件格式压缩格式Iceberg 表版本
ParquetSNAPPY, LZ4, ZSTD, GZIP, 和 NO_COMPRESSION
  • v1 表：支持。
  • v2 表：从 StarRocks v3.1 开始支持，其中对这些 v2 表的查询支持位置删除。在 v3.1.10、v3.2.5、v3.3 及其更高版本中，对 v2 表的查询还支持等值删除。
ORCZLIB, SNAPPY, LZO, LZ4, ZSTD, 和 NO_COMPRESSION
  • v1 表：支持。
  • v2 表：从 StarRocks v3.0 开始支持，其中对这些 v2 表的查询支持位置删除。在 v3.1.8、v3.2.3、v3.3 及其更高版本中，对 v2 表的查询还支持等值删除。

集成准备​

在创建 Iceberg catalog 之前，请确保您的 StarRocks 集群可以与 Iceberg 集群的存储系统和元存储集成。

存储​

选择与您的存储类型匹配的选项卡：

如果您的 Iceberg 集群使用 AWS S3 作为存储或 AWS Glue 作为元存储，请选择合适的身份验证方法并进行必要的准备，以确保您的 StarRocks 集群可以访问相关的 AWS 云资源。

推荐以下身份验证方法：

  • 实例配置文件
  • 假设角色
  • IAM 用户

在上述三种身份验证方法中，实例配置文件是最广泛使用的。

有关更多信息，请参见 AWS IAM 中的身份验证准备。

创建 Iceberg catalog​

语法​

CREATE EXTERNAL CATALOG <catalog_name>
[COMMENT <comment>]
PROPERTIES
(
    "type" = "iceberg",
    [SecurityParams],
    MetastoreParams,
    StorageCredentialParams,
    MetadataRelatedParams
)

参数​

catalog_name​

Iceberg catalog 的名称。命名约定如下：

  • 名称可以包含字母、数字（0-9）和下划线（_）。必须以字母开头。
  • 名称区分大小写，长度不能超过 1023 个字符。

comment​

Iceberg catalog 的描述。此参数是可选的。

type​

数据源的类型。将值设置为 iceberg。

SecurityParams​

关于 StarRocks 如何管理 Catalog 数据访问的参数。

有关管理 Iceberg REST Catalog 数据访问的详细说明，请参阅Iceberg REST Catalog 的安全设置。

catalog.access.control​

数据访问控制策略。有效值：

  • native（默认）：使用 StarRocks 内置的数据访问控制系统。
  • allowall：所有数据访问检查均委托给 Catalog 本身处理。
  • ranger：数据访问检查委托给 Apache Ranger 处理。

MetastoreParams​

关于 StarRocks 如何与数据源的元存储集成的一组参数。选择与您的元存储类型匹配的选项卡：

Hive metastore​

如果选择 Hive metastore 作为数据源的元存储，请按以下方式配置 MetastoreParams：

"iceberg.catalog.type" = "hive",
"hive.metastore.uris" = "<hive_metastore_uri>"
备注

在查询 Iceberg 数据之前，必须将 Hive metastore 节点的主机名和 IP 地址映射添加到 /etc/hosts 路径。否则，StarRocks 在启动查询时可能无法访问 Hive metastore。

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

iceberg.catalog.type​

必需：是 描述：您用于 Iceberg 集群的元存储类型。将值设置为 hive。

hive.metastore.uris​

必需：是 描述：Hive metastore 的 URI。格式：thrift://<metastore_IP_address>:<metastore_port>。
如果 Hive metastore 启用了高可用性（HA），您可以指定多个 metastore URI，并用逗号（,）分隔，例如 "thrift://<metastore_IP_address_1>:<metastore_port_1>,thrift://<metastore_IP_address_2>:<metastore_port_2>,thrift://<metastore_IP_address_3>:<metastore_port_3>"。

StorageCredentialParams​

关于 StarRocks 如何与您的存储系统集成的一组参数。此参数集是可选的。

注意以下几点：

  • 如果您使用 HDFS 作为存储，则无需配置 StorageCredentialParams，可以跳过此部分。如果您使用 AWS S3、其他 S3 兼容的存储系统、Microsoft Azure Storage 或 Google GCS 作为存储，则必须配置 StorageCredentialParams。

  • 如果您使用 Tabular 作为元存储，则无需配置 StorageCredentialParams，可以跳过此部分。如果您使用 HMS 或 AWS Glue 作为元存储，则必须配置 StorageCredentialParams。

选择与您的存储类型匹配的选项卡：

AWS S3​

如果选择 AWS S3 作为 Iceberg 集群的存储，请采取以下措施之一：

  • 要选择基于实例配置文件的身份验证方法，请按以下方式配置 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>"

  • 要选择基于 REST Catalog 的 Vended Credential（自 v4.0 起支持），请按以下方式配置 StorageCredentialParams：

    "aws.s3.region" = "<aws_s3_region>"

AWS S3 的 StorageCredentialParams：

aws.s3.use_instance_profile​
  • 必需：是
  • 描述：指定是否启用基于实例配置文件的身份验证方法和基于假设角色的身份验证方法。有效值：true 和 false。默认值：false。
aws.s3.iam_role_arn​
  • 必需：否
  • 描述：在您的 AWS S3 存储桶上具有权限的 IAM 角色的 ARN。如果使用基于假设角色的身份验证方法访问 AWS S3，则必须指定此参数。
aws.s3.region​
  • 必需：是
  • 描述：您的 AWS S3 存储桶所在的区域。例如：us-west-1。
aws.s3.access_key​
  • 必需：否
  • 描述：您的 IAM 用户的访问密钥。如果使用基于 IAM 用户的身份验证方法访问 AWS S3，则必须指定此参数。
aws.s3.secret_key​
  • 必需：否
  • 描述：您的 IAM 用户的秘密密钥。如果使用基于 IAM 用户的身份验证方法访问 AWS S3，则必须指定此参数。

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

MetadataRelatedParams​

关于 StarRocks Iceberg 元数据缓存的一组参数。此参数集是可选的。

从 v3.3.3 开始，StarRocks 支持 周期性元数据刷新策略。在大多数情况下，您可以忽略设置以下参数，不需要调整其中的策略参数，因为这些参数的默认值已经为您提供了开箱即用的性能。您可以使用系统变量 plan_mode 调整 Iceberg 元数据解析模式。

参数默认值描述
enable_iceberg_metadata_cachetrue是否缓存 Iceberg 相关的元数据，包括表缓存、分区名称缓存以及 Manifest 中的数据文件缓存和删除数据文件缓存。
iceberg_manifest_cache_with_column_statisticstrue是否缓存列的统计信息。开启时，仅缓存文件级 min/max 裁剪有效的列（分区来源列、排序键列和 identifier 列）的统计信息，以控制宽表的 Manifest 缓存内存占用。
refresh_iceberg_manifest_min_length2 * 1024 * 1024触发数据文件缓存刷新的最小 Manifest 文件长度。
iceberg_data_file_cache_memory_usage_ratio0.1Data File Manifest 缓存的最大内存使用率。从 v3.5.6 版本开始支持。
iceberg_delete_file_cache_memory_usage_ratio0.1Delete File Manifest 缓存的最大内存使用率。从 v3.5.6 版本开始支持。
iceberg_table_cache_refresh_interval_sec60触发 Iceberg 表缓存异步刷新操作的时间间隔（单位：秒）。从 v3.5.7 版本开始支持。

从 v3.4 起，StarRocks 在没有主动触发收集 Iceberg 表统计信息的情况下，可以通过设置以下参数读取 Iceberg 的元数据来获取 Iceberg 表的统计信息。

参数默认值描述
enable_get_stats_from_external_metadatafalse是否允许系统从 Iceberg 元数据中获取统计信息。当此项设置为 true 时，您可以通过会话变量 enable_get_stats_from_external_metadata 进一步控制要收集的统计信息类型。

示例​

以下示例创建了一个名为 iceberg_catalog_hms 或 iceberg_catalog_glue 的 Iceberg catalog，具体取决于您使用的元存储类型，以便从您的 Iceberg 集群中查询数据。选择与您的存储类型匹配的选项卡：

AWS S3​

如果选择基于实例配置文件的凭证​

  • 如果在 Iceberg 集群中使用 Hive metastore，请运行如下命令：

    CREATE EXTERNAL CATALOG iceberg_catalog_hms
    PROPERTIES
    (
        "type" = "iceberg",
        "iceberg.catalog.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "aws.s3.use_instance_profile" = "true",
        "aws.s3.region" = "us-west-2"
    );

  • 如果在 Amazon EMR Iceberg 集群中使用 AWS Glue，请运行如下命令：

    CREATE EXTERNAL CATALOG iceberg_catalog_glue
    PROPERTIES
    (
        "type" = "iceberg",
        "iceberg.catalog.type" = "glue",
        "aws.glue.use_instance_profile" = "true",
        "aws.glue.region" = "us-west-2",
        "aws.s3.use_instance_profile" = "true",
        "aws.s3.region" = "us-west-2"
    );
如果选择基于假设角色的凭证​

  • 如果在 Iceberg 集群中使用 Hive metastore，请运行如下命令：

    CREATE EXTERNAL CATALOG iceberg_catalog_hms
    PROPERTIES
    (
        "type" = "iceberg",
        "iceberg.catalog.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "aws.s3.use_instance_profile" = "true",
        "aws.s3.iam_role_arn" = "arn:aws:iam::081976408565:role/test_s3_role",
        "aws.s3.region" = "us-west-2"
    );

  • 如果在 Amazon EMR Iceberg 集群中使用 AWS Glue，请运行如下命令：

    CREATE EXTERNAL CATALOG iceberg_catalog_glue
    PROPERTIES
    (
        "type" = "iceberg",
        "iceberg.catalog.type" = "glue",
        "aws.glue.use_instance_profile" = "true",
        "aws.glue.iam_role_arn" = "arn:aws:iam::081976408565:role/test_glue_role",
        "aws.glue.region" = "us-west-2",
        "aws.s3.use_instance_profile" = "true",
        "aws.s3.iam_role_arn" = "arn:aws:iam::081976408565:role/test_s3_role",
        "aws.s3.region" = "us-west-2"
    );
如果选择基于 IAM 用户的凭证​

  • 如果在 Iceberg 集群中使用 Hive metastore，请运行如下命令：

    CREATE EXTERNAL CATALOG iceberg_catalog_hms
    PROPERTIES
    (
        "type" = "iceberg",
        "iceberg.catalog.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "aws.s3.use_instance_profile" = "false",
        "aws.s3.access_key" = "<iam_user_access_key>",
        "aws.s3.secret_key" = "<iam_user_access_key>",
        "aws.s3.region" = "us-west-2"
    );

  • 如果在 Amazon EMR Iceberg 集群中使用 AWS Glue，请运行如下命令：

    CREATE EXTERNAL CATALOG iceberg_catalog_glue
    PROPERTIES
    (
        "type" = "iceberg",
        "iceberg.catalog.type" = "glue",
        "aws.glue.use_instance_profile" = "false",
        "aws.glue.access_key" = "<iam_user_access_key>",
        "aws.glue.secret_key" = "<iam_user_secret_key>",
        "aws.glue.region" = "us-west-2",
        "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" = "us-west-2"
    );
如果选择 Vended Credential​

如果基于 REST Catalog 使用 Vended Credential，请运行如下命令：

CREATE EXTERNAL CATALOG polaris_s3
PROPERTIES
(
    "type" = "iceberg",
    "iceberg.catalog.uri" = "http://xxx:xxx/api/catalog",
    "iceberg.catalog.type" = "rest",
    "iceberg.catalog.rest.nested-namespace-enabled"="true",
    "iceberg.catalog.security" = "oauth2",
    "iceberg.catalog.oauth2.credential" = "xxxxx:xxxx",
    "iceberg.catalog.oauth2.scope"='PRINCIPAL_ROLE:ALL',
    "iceberg.catalog.warehouse" = "iceberg_catalog",
    "aws.s3.region" = "us-west-2"
);

使用您的 catalog​

查看 Iceberg catalog​

您可以使用 SHOW CATALOGS 查询当前 StarRocks 集群中的所有 catalog：

SHOW CATALOGS;

您还可以使用 SHOW CREATE CATALOG 查询外部 catalog 的创建语句。以下示例查询名为 iceberg_catalog_glue 的 Iceberg catalog 的创建语句：

SHOW CREATE CATALOG iceberg_catalog_glue;

切换到 Iceberg Catalog 及其中的数据库​

您可以使用以下方法之一切换到 Iceberg catalog 及其中的数据库：

  • 使用 SET CATALOG 指定当前会话中的 Iceberg catalog，然后使用 USE 指定活动数据库：

    -- 切换到当前会话中的指定 catalog：
    SET CATALOG <catalog_name>
    -- 指定当前会话中的活动数据库：
    USE <db_name>

  • 直接使用 USE 切换到 Iceberg catalog 及其中的数据库：

    USE <catalog_name>.<db_name>

删除 Iceberg catalog​

您可以使用 DROP CATALOG 删除外部 catalog。

以下示例删除名为 iceberg_catalog_glue 的 Iceberg catalog：

DROP Catalog iceberg_catalog_glue;

查看 Iceberg 表的模式​

您可以使用以下语法之一查看 Iceberg 表的模式：

  • 查看模式

    DESC[RIBE] <catalog_name>.<database_name>.<table_name>

  • 从 CREATE 语句中查看模式和位置

    SHOW CREATE TABLE <catalog_name>.<database_name>.<table_name>

查询 Iceberg 表​

  1. 使用 SHOW DATABASES 查看 Iceberg 集群中的数据库：

    SHOW DATABASES FROM <catalog_name>

  2. 切换到 Iceberg catalog 及其中的数据库。

  3. 使用 SELECT 查询指定数据库中的目标表：

    SELECT count(*) FROM <table_name> LIMIT 10

创建 Iceberg 数据库​

与 StarRocks 的内部 catalog 类似，如果您在 Iceberg catalog 上具有 CREATE DATABASE 权限，您可以使用 CREATE DATABASE 语句在该 Iceberg catalog 中创建数据库。此功能从 v3.1 开始支持。

提示

您可以使用 GRANT 和 REVOKE 授予和撤销权限。

切换到 Iceberg catalog，然后使用以下语句在该 catalog 中创建 Iceberg 数据库：

CREATE DATABASE <database_name>
[PROPERTIES ("location" = "<prefix>://<path_to_database>/<database_name.db>/")]

您可以使用 location 参数指定要在其中创建数据库的文件路径。支持 HDFS 和云存储。如果未指定 location 参数，StarRocks 会在 Iceberg catalog 的默认文件路径中创建数据库。

prefix 根据您使用的存储系统而有所不同：

HDFS​

Prefix 值：hdfs

Google GCS​

Prefix 值：gs

Azure Blob Storage​

Prefix 值：

  • 如果您的存储账户允许通过 HTTP 访问，prefix 为 wasb。
  • 如果您的存储账户允许通过 HTTPS 访问，prefix 为 wasbs。

Azure Data Lake Storage Gen1​

Prefix 值：adl

Azure Data Lake Storage Gen2​

Prefix 值：

  • 如果您的存储账户允许通过 HTTP 访问，prefix 为 abfs。
  • 如果您的存储账户允许通过 HTTPS 访问，prefix 为 abfss。

AWS S3 或其他 S3 兼容存储（例如 MinIO）​

Prefix 值：s3

删除 Iceberg 数据库​

与 StarRocks 的内部数据库类似，如果您在 Iceberg 数据库上具有 DROP 权限，您可以使用 DROP DATABASE 语句删除该 Iceberg 数据库。此功能从 v3.1 开始支持。您只能删除空数据库。

当您删除 Iceberg 数据库时，数据库在您的 HDFS 集群或云存储上的文件路径不会随数据库一起删除。

切换到 Iceberg catalog，然后使用以下语句在该 catalog 中删除 Iceberg 数据库：

DROP DATABASE <database_name>;

创建 Iceberg 表​

与 StarRocks 的内部数据库类似，如果您在 Iceberg 数据库上具有 CREATE TABLE 权限，您可以使用 CREATE TABLE 或 [CREATE TABLE AS SELECT ../../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_AS_SELECT.mdELECT.md) 语句在该 Iceberg 数据库中创建表。此功能从 v3.1 开始支持。

切换到 Iceberg catalog 及其中的数据库，然后使用以下语法在该数据库中创建 Iceberg 表。

语法​

CREATE TABLE [IF NOT EXISTS] [database.]table_name
(column_definition1[, column_definition2, ...
partition_column_definition1,partition_column_definition2...])
[partition_desc]
[ORDER BY sort_desc)]
[PROPERTIES ("key" = "value", ...)]
[AS SELECT query]

参数​

column_definition​

column_definition 的语法如下：

col_name col_type [COMMENT 'comment']
备注

所有非分区列必须使用 NULL 作为默认值。这意味着您必须在表创建语句中为每个非分区列指定 DEFAULT "NULL"。此外，分区列必须在非分区列之后定义，并且不能使用 NULL 作为默认值。

partition_desc​

partition_desc 的语法如下：

PARTITION BY (partition_expr[, partition_expr...])

每个 partition_expr 可以是以下形式之一：

column_name
| transform_expr(column_name)
| transform_expr(column_name, parameter)

当前，StarRocks 支持 Apache Iceberg 规范 transform expr 中定义的分区转换表达式。这使得 StarRocks 能够基于转换后的列值创建具有隐藏分区 (Hidden Partition) 的 Iceberg 表。

备注

分区列必须在非分区列之后定义。分区列支持所有数据类型，除 FLOAT、DOUBLE、DECIMAL 和 DATETIME 外，并且不能使用 NULL 作为默认值。

ORDER BY​

自 v4.0 起，StarRocks 支持在创建 Iceberg 表时通过 ORDER BY 子句指定排序键，用于在写入时根据排序键对写入数据进行排序，确保同一个数据文件中的数据按照指定排序键有序排列。

ORDER BY 子句也可以同时指定多个排序键，格式如下：

ORDER BY (column_name [sort_direction] [nulls_order], ...)

其中：

  • column_name：作为排序键的列名，必须是当前表结构中包含的列，暂不支持 Transform 表达式。
  • sort_direction：排序方向。有效值：ASC（默认）和 DESC。
  • nulls_order：NULL 值的排序顺序。有效值：NULLS FIRST（当指定 ASC 时默认）和 NULLS LAST（当指定 DESC 时默认）。

sort_direction 和 nulls_order 可以省略。例如，以下各示例均为有效的 sort_desc：

  • column_name
  • column_name ASC
  • column_name DESC NULLS FIRST
PROPERTIES​

您可以在 PROPERTIES 中以 "key" = "value" 格式指定表属性。请参见 Iceberg 表属性。

下表描述了一些关键属性。

location​

描述：您要在其中创建 Iceberg 表的文件路径。当您使用 HMS 作为元存储时，无需指定 location 参数，因为 StarRocks 会在当前 Iceberg catalog 的默认文件路径中创建表。当您使用 AWS Glue 作为元存储时：

  • 如果您已为要在其中创建表的数据库指定了 location 参数，则无需为表指定 location 参数。因此，表默认为其所属数据库的文件路径。
  • 如果您未为要在其中创建表的数据库指定 location，则必须为表指定 location 参数。
file_format​

描述：Iceberg 表的文件格式。仅支持 Parquet 格式。默认值：parquet。

compression_codec​

描述：Iceberg 表使用的压缩算法。支持的压缩算法有 SNAPPY、GZIP、ZSTD 和 LZ4。默认值：zstd。

示例​

  1. 创建一个名为 unpartition_tbl 的非分区表。该表由两列 id 和 score 组成，如下所示：

    CREATE TABLE unpartition_tbl
    (
        id int,
        score double
    );

  2. 创建一个名为 partition_tbl_1 的分区表。该表由三列 action、id 和 dt 组成，其中 id 和 dt 被定义为分区列，如下所示：

    CREATE TABLE partition_tbl_1
    (
        action varchar(20),
        id int,
        dt date
    )
    PARTITION BY (id,dt);

  3. 查询一个名为 partition_tbl_1 的现有表，并根据 partition_tbl_1 的查询结果创建一个名为 partition_tbl_2 的分区表。对于 partition_tbl_2，id 和 dt 被定义为分区列，如下所示：

    CREATE TABLE partition_tbl_2
    PARTITION BY (id, dt)
    AS SELECT * from employee;

  4. 创建一个名为 partition_tbl_3 的表，使用隐藏分区。该表包含三个列：action、id 和 dt。其中，id 和 dt 用作分区键，但分区是通过转换表达式定义的，因此这些分区是隐藏的。

    CREATE TABLE partition_tbl_3 (
      action VARCHAR(20),
      id INT,
      dt DATE
    )
    PARTITION BY bucket(id, 10), year(dt);

分区演进（ADD/DROP PARTITION COLUMN）​

StarRocks 支持使用 ALTER TABLE ... ADD|DROP PARTITION COLUMN 为 Iceberg 表演进分区 Spec（包括转换表达式）。

语法​

ALTER TABLE [catalog.][database.]table_name
ADD PARTITION COLUMN partition_expr [, partition_expr ...];

ALTER TABLE [catalog.][database.]table_name
DROP PARTITION COLUMN partition_expr [, partition_expr ...];

partition_expr 可以是列名（Identity 变换）或以下转换表达式之一：year、month、day、hour、truncate、bucket。

示例​

ALTER TABLE test_part_evo
ADD PARTITION COLUMN dt, truncate(value, 10), bucket(id, 10);

ALTER TABLE test_part_evo
DROP PARTITION COLUMN dt;

ALTER TABLE test_part_evo
ADD PARTITION COLUMN month(dt);

将数据下沉到 Iceberg 表​

与 StarRocks 的内部表类似，如果您在 Iceberg 表上具有 INSERT 权限，您可以使用 INSERT 语句将 StarRocks 表的数据下沉到该 Iceberg 表（目前仅支持 Parquet 格式的 Iceberg 表）。此功能从 v3.1 开始支持。

切换到 Iceberg catalog 及其中的数据库，然后使用以下语法将 StarRocks 表的数据下沉到该数据库中的 Parquet 格式的 Iceberg 表。

语法​

INSERT {INTO | OVERWRITE} <table_name>
[ (column_name [, ...]) ]
{ VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }

-- 如果要将数据下沉到指定的分区，请使用以下语法：
INSERT {INTO | OVERWRITE} <table_name>
PARTITION (par_col1=<value> [, par_col2=<value>...])
{ VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }
备注

分区列不允许 NULL 值。因此，您必须确保没有空值被加载到 Iceberg 表的分区列中。

参数​

INTO​

将 StarRocks 表的数据追加到 Iceberg 表中。

OVERWRITE​

用 StarRocks 表的数据覆盖 Iceberg 表的现有数据。

column_name​

要加载数据的目标列的名称。您可以指定一个或多个列。如果指定多个列，请用逗号（,）分隔。您只能指定 Iceberg 表中实际存在的列，并且您指定的目标列必须包括 Iceberg 表的分区列。无论目标列名称是什么，您指定的目标列按顺序与 StarRocks 表的列一一对应。如果未指定目标列，数据将加载到 Iceberg 表的所有列中。如果 StarRocks 表的非分区列无法映射到 Iceberg 表的任何列，StarRocks 会将默认值 NULL 写入 Iceberg 表列。如果 INSERT 语句包含的查询语句返回的列类型与目标列的数据类型不匹配，StarRocks 会对不匹配的列进行隐式转换。如果转换失败，将返回语法解析错误。

expression​

为目标列分配值的表达式。

DEFAULT​

为目标列分配默认值。

query​

其结果将加载到 Iceberg 表中的查询语句。它可以是 StarRocks 支持的任何 SQL 语句。

PARTITION​

要加载数据的分区。您必须在此属性中指定 Iceberg 表的所有分区列。您在此属性中指定的分区列可以与您在表创建语句中定义的分区列顺序不同。如果指定此属性，则不能指定 column_name 属性。

示例​

  1. 向 partition_tbl_1 表中插入三行数据：

    INSERT INTO partition_tbl_1
    VALUES
        ("buy", 1, "2023-09-01"),
        ("sell", 2, "2023-09-02"),
        ("buy", 3, "2023-09-03");

  2. 将包含简单计算的 SELECT 查询结果插入到 partition_tbl_1 表中：

    INSERT INTO partition_tbl_1 (id, action, dt) SELECT 1+1, 'buy', '2023-09-03';

  3. 将从 partition_tbl_1 表中读取数据的 SELECT 查询结果插入到同一表中：

    INSERT INTO partition_tbl_1 SELECT 'buy', 1, date_add(dt, INTERVAL 2 DAY)
    FROM partition_tbl_1
    WHERE id=1;

  4. 将 SELECT 查询结果插入到满足两个条件 dt='2023-09-01' 和 id=1 的 partition_tbl_2 表的分区中：

    INSERT INTO partition_tbl_2 SELECT 'order', 1, '2023-09-01';

    或

    INSERT INTO partition_tbl_2 partition(dt='2023-09-01',id=1) SELECT 'order';

  5. 将 partition_tbl_1 表中满足两个条件 dt='2023-09-01' 和 id=1 的分区中的所有 action 列值覆盖为 close：

    INSERT OVERWRITE partition_tbl_1 SELECT 'close', 1, '2023-09-01';

    或

    INSERT OVERWRITE partition_tbl_1 partition(dt='2023-09-01',id=1) SELECT 'close';

删除 Iceberg 表​

与 StarRocks 的内部表类似，如果您在 Iceberg 表上具有 DROP 权限，您可以使用 DROP TABLE 语句删除该 Iceberg 表。此功能从 v3.1 开始支持。

当您删除 Iceberg 表时，表在您的 HDFS 集群或云存储上的文件路径和数据不会随表一起删除。

当您强制删除 Iceberg 表（即在 DROP TABLE 语句中指定了 FORCE 关键字）时，表在您的 HDFS 集群或云存储上的数据将随表一起删除，但表的文件路径将保留。

切换到 Iceberg catalog 及其中的数据库，然后使用以下语句在该数据库中删除 Iceberg 表。

DROP TABLE <table_name> [FORCE];

创建 Iceberg 视图​

您可以通过 StarRocks 定义 Iceberg 视图，或者对已有 Iceberg 视图增加 StarRocks 语法风格的定义。在查询视图时，支持读取视图的 StarRocks 定义。此功能从 v3.5 开始支持。

CREATE VIEW [IF NOT EXISTS]
[<catalog>.<database>.]<view_name>
(
    <column_name>[ COMMENT 'column comment']
    [, <column_name>[ COMMENT 'column comment'], ...]
)
[COMMENT 'view comment']
[PROPERTIES ("key" = "value", ...)]
AS <query_statement>

示例​

基于 Iceberg 表 iceberg_table 创建 Iceberg 视图 iceberg_view1。

CREATE VIEW IF NOT EXISTS iceberg.iceberg_db.iceberg_view1 AS
SELECT k1, k2 FROM iceberg.iceberg_db.iceberg_table;

自 v4.0.3 起，您可以在 PROPERTIES 中以 "key" = "value" 格式指定视图属性。

CREATE VIEW IF NOT EXISTS iceberg.iceberg_db.iceberg_view1
PROPERTIES (
  "key1" = "value1",
  "key2" = "value2"
)
AS
SELECT k1, k2 FROM iceberg.iceberg_db.iceberg_table;

为已有 Iceberg 视图增加或修改 StarRocks 语法风格的定义​

如果您的 Iceberg 视图由其他系统，如 Apache Spark 创建，同时您希望该视图可以被 StarRocks 查询，则您可以为该视图增加 StarRocks 语法风格的定义。此功能从 v3.5 开始支持。

备注
  • 您需要提前验证确保 StarRocks 语法的定义与其他系统的定义实际含义相同，StarRocks 或其他系统不保证不同定义之间的一致性。
  • 一个视图仅能拥有一个 StarRocks 语法风格的定义，如您希望修改，可以使用 MODIFY 语句进行重写。
ALTER VIEW
[<catalog>.<database>.]<view_name>
(
    <column_name>
    [, <column_name>]
)
{ ADD | MODIFY } DIALECT
<query_statement>

示例​

  1. 为已有的 Iceberg 视图 iceberg_view2 增加 StarRocks 语法定义。
ALTER VIEW iceberg.iceberg_db.iceberg_view2 ADD DIALECT SELECT k1, k2 FROM iceberg.iceberg_db.iceberg_table;
  1. 修改 Iceberg 视图 iceberg_view2 的 StarRocks 语法定义。
ALTER VIEW iceberg.iceberg_db.iceberg_view2 MODIFY DIALECT SELECT k1, k2, k3 FROM iceberg.iceberg_db.iceberg_table;

手动 Compaction​

从 v4.0 开始，StarRocks 支持对 Iceberg 表执行手动 Compaction。

每次将数据导入到 Iceberg 表时，都会生成新的数据文件和元数据文件。随着时间推移，大量的数据文件会显著降低查询计划生成速度，并影响系统性能。

此时需要对表或分区执行手动 Compaction，将小型数据文件合并，从而提升系统性能。

语法​

ALTER TABLE [catalog.][database.]table_name 
EXECUTE rewrite_data_files
("key"=value [,"key"=value, ...]) 
[WHERE <predicate>]

参数​

rewrite_data_files 属性​

声明手动 Compaction 行为的 "key"=value 键值对。请注意，需要用双引号包裹其中的键。

min_file_size_bytes​
  • 描述：小型数据文件的上限值。小于该值的数据文件将在 Compaction 过程中被合并。
  • 单位：Byte
  • 类型：Int
  • 默认值：268,435,456（256 MB）
batch_size​
  • 描述：每次批处理中可处理的最大数据量。
  • 单位：Byte
  • 类型：Int
  • 默认值：10,737,418,240 (10 GB)
rewrite_all​
  • 描述：在 Compaction 过程中，是否忽略用于筛选具有特定条件的数据文件的参数，重写所有数据文件。
  • 单位：-
  • 类型：Boolean
  • 默认值：false
WHERE 子句​
  • 描述：用于指定参与 Compaction 操作的分区的过滤谓词。

示例​

以下示例对 Iceberg 表 t1 中的特定分区执行手动 Compaction。分区由子句 WHERE part_col = 'p1' 表示。在这些分区中，小于 134,217,728 字节（128 MB）的数据文件将在 Compaction 过程中被合并。

ALTER TABLE t1 EXECUTE rewrite_data_files("min_file_size_bytes"= 134217728) WHERE part_col = 'p1';

配置元数据缓存​

您的 Iceberg 集群的元数据文件可能存储在远端存储中，例如 AWS S3 或 HDFS。默认情况下，StarRocks 将 Iceberg 元数据缓存到内存中。为了加速查询，StarRocks 采用了两级元数据缓存机制，可以在内存和磁盘上缓存元数据。对于每个初始查询，StarRocks 缓存其计算结果。如果发出与先前查询语义等效的任何后续查询，StarRocks 首先尝试从其缓存中检索请求的元数据，只有在缓存中未命中元数据时才从远端存储中检索元数据。

StarRocks 使用最近最少使用（LRU）算法来缓存和驱逐数据。基本规则如下：

  • StarRocks 首先尝试从内存中检索请求的元数据。如果内存中未命中元数据，StarRocks 尝试从磁盘中检索元数据。从磁盘中检索到的元数据将加载到内存中。如果磁盘中也未命中元数据，StarRocks 从远端存储中检索元数据并将其缓存到内存中。
  • StarRocks 将从内存中驱逐的元数据写入磁盘，但直接丢弃从磁盘中驱逐的元数据。

从 v3.3.3 开始，StarRocks 支持 周期性元数据刷新策略。您可以使用系统变量 plan_mode 调整 Iceberg 元数据缓存计划。

Iceberg 元数据缓存的 FE 配置​

enable_iceberg_metadata_disk_cache​
  • 单位：N/A
  • 默认值：false
  • 描述：指定是否启用磁盘缓存。
iceberg_metadata_cache_disk_path​
  • 单位：N/A
  • 默认值：StarRocksFE.STARROCKS_HOME_DIR + "/caches/iceberg"
  • 描述：磁盘上缓存的元数据文件的保存路径。
iceberg_metadata_disk_cache_capacity​
  • 单位：字节
  • 默认值：2147483648，相当于 2 GB
  • 描述：磁盘上允许缓存的元数据的最大大小。
iceberg_metadata_memory_cache_capacity​
  • 单位：字节
  • 默认值：536870912，相当于 512 MB
  • 描述：内存中允许缓存的元数据的最大大小。
iceberg_metadata_memory_cache_expiration_seconds​
  • 单位：秒
  • 默认值：86500
  • 描述：从上次访问开始，内存中缓存条目过期的时间。
iceberg_metadata_disk_cache_expiration_seconds​
  • 单位：秒
  • 默认值：604800，相当于一周
  • 描述：从上次访问开始，磁盘上缓存条目过期的时间。
iceberg_metadata_cache_max_entry_size​
  • 单位：字节
  • 默认值：8388608，相当于 8 MB
  • 描述：可以缓存的文件的最大大小。超过此参数值的文件无法缓存。如果查询请求这些文件，StarRocks 将从远端存储中检索它们。
enable_background_refresh_connector_metadata​
  • 单位：-
  • 默认值：true
  • 描述：是否启用周期性 Iceberg 元数据缓存刷新。启用后，StarRocks 会轮询 Iceberg 集群的元存储（Hive Metastore 或 AWS Glue），并刷新频繁访问的 Iceberg catalog 的缓存元数据以感知数据更改。true 表示启用 Iceberg 元数据缓存刷新，false 表示禁用。
background_refresh_metadata_interval_millis​
  • 单位：毫秒
  • 默认值：600000
  • 描述：两次连续 Iceberg 元数据缓存刷新之间的间隔。
background_refresh_metadata_time_secs_since_last_access_sec​
  • 单位：秒
  • 默认值：86400
  • 描述：Iceberg 元数据缓存刷新任务的过期时间。对于已访问的 Iceberg catalog，如果超过指定时间未访问，StarRocks 将停止刷新其缓存元数据。对于未访问的 Iceberg catalog，StarRocks 将不刷新其缓存元数据。

附录 A：周期性元数据刷新策略​

Iceberg 支持 Snapshot。有了最新 Snapshot，就能得到最新结果。因此，只有缓存 Snapshot 能影响数据的新鲜度。您只需注意包含快照的缓存的刷新策略即可。

下面的流程图在时间轴上显示了时间间隔。

Timeline for updating and discarding cached metadata

附录 B：元数据文件解析​

  • 大规模元数据的分布式计划

    为了有效处理大规模元数据，StarRocks 使用多个 BE 和 CN 节点采用分布式方法。此方法利用现代查询引擎的并行计算能力，可以将读取、解压缩和过滤清单文件等任务分配到多个节点。通过并行处理这些清单文件，显著减少了元数据检索所需的时间，从而加快了作业计划。对于涉及大量清单文件的大型查询，这尤其有益，因为它消除了单点瓶颈并提高了整体查询执行效率。

  • 小规模元数据的本地计划

    对于较小的查询，其中清单文件的重复解压缩和解析可能会引入不必要的延迟，采用了不同的策略。StarRocks 缓存反序列化的内存对象，特别是 Avro 文件，以解决此问题。通过将这些反序列化的文件存储在内存中，系统可以绕过后续查询的解压缩和解析阶段。此缓存机制允许直接访问所需的元数据，显著减少了检索时间。因此，系统变得更加响应，并更适合满足高查询需求和物化视图重写需求。

  • 自适应元数据检索策略（默认）

    StarRocks 旨在根据各种因素自动选择适当的元数据检索方法，包括 FE 和 BE/CN 节点的数量、其 CPU 核心数以及当前查询所需的清单文件数量。此自适应方法确保系统动态优化元数据检索，而无需手动调整与元数据相关的参数。通过这样做，StarRocks 提供了无缝体验，在分布式和本地计划之间取得平衡，以在不同条件下实现最佳查询性能。

您可以使用系统变量 plan_mode 调整 Iceberg 元数据缓存计划。

Rocky the happy otterStarRocks Assistant

AI generated answers are based on docs and other sources. Please test answers in non-production environments.