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

Iceberg Catalog

提示

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

Iceberg catalog 是 StarRocks v2.4 起支持的一种外部 Catalog。借助 Iceberg catalog，您可以：

  • 直接查询 Iceberg 中存储的数据，无需手动创建表。
  • 使用 INSERT INTO 或异步物化视图（v2.5 起支持）处理 Iceberg 中存储的数据，并将数据加载到 StarRocks 中。
  • 通过 StarRocks 执行操作来创建或删除 Iceberg 数据库和表，或者通过使用 INSERT INTO 将 StarRocks 表中的数据 Sink 到 Parquet 格式的 Iceberg 表中（此功能从 v3.1 起支持）。

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

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

  • Metastore，如 Hive metastore、AWS Glue 或 Tabular

注意
  • 如果您选择 AWS S3 作为存储，则可以使用 HMS 或 AWS Glue 作为 Metastore。如果您选择任何其他存储系统，则只能使用 HMS 作为 Metastore。
  • 如果选择 Tabular 作为 Metastore，则需要使用 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 集群的存储系统和 Metastore 集成。

存储​

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

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

建议使用以下身份验证方法

  • 实例配置文件
  • Assume Role
  • IAM 用户

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

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

创建 Iceberg catalog​

语法​

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

参数​

catalog_name​

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

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

comment​

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

type​

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

MetastoreParams​

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

Hive Metastore​

如果您选择 Hive Metastore 作为数据源的 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 集群的 Metastore 类型。将值设置为 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 作为 Metastore，则无需配置 StorageCredentialParams，可以跳过此部分。如果使用 HMS 或 AWS Glue 作为 Metastore，则必须配置 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>"

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 的身份验证参数。

MetadataUpdateParams​

关于 StarRocks 如何更新 Iceberg 元数据缓存的一组参数。此参数集为可选。

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

参数默认描述
enable_iceberg_metadata_cachetrue是否缓存与 Iceberg 相关的元数据，包括 Table Cache、Partition Name Cache 以及 Manifest 中的 Data File Cache 和 Delete Data File Cache。
iceberg_manifest_cache_with_column_statisticsfalse是否缓存列的统计信息。
iceberg_manifest_cache_max_num100000可以缓存的最大 Manifest 文件数。
refresh_iceberg_manifest_min_length2 * 1024 * 1024触发 Data File Cache 刷新的最小 Manifest 文件长度。

示例​

以下示例创建一个名为 iceberg_catalog_hms 或 iceberg_catalog_glue 的 Iceberg Catalog，具体取决于您使用的 Metastore 类型，以查询 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"
    );
如果选择基于假定角色的凭据​

  • 如果在 HIceberg 集群中使用 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"
    );

使用您的 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 指定一个活动的数据库

    -- Switch to a specified catalog in the current session:
    SET CATALOG <catalog_name>
    -- Specify the active database in the current session:
    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 表的 schema​

可以使用以下语法之一查看 Iceberg 表的 schema

  • 查看 Schema

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

  • 从 CREATE 语句中查看 Schema 和 Location

    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]
[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 (par_col1[, par_col2...])

目前 StarRocks 仅支持 identity transforms，这意味着 StarRocks 为每个唯一的分区值创建一个分区。

注意

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

PROPERTIES​

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

下表描述了几个关键属性。

location​

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

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

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

compression_codec​

描述：用于 Iceberg 表的压缩算法。支持的压缩算法有 SNAPPY、GZIP、ZSTD 和 LZ4。默认值：gzip。此属性在 v3.2.3 中已弃用，自该版本起，用于将数据 Sink 到 Iceberg 表的压缩算法统一由会话变量 connector_sink_compression_codec 控制。

示例​

  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;

将数据 Sink 到 Iceberg 表​

与 StarRocks 的内部表类似，如果您拥有 Iceberg 表的 INSERT 权限，则可以使用 INSERT 语句将 StarRocks 表的数据 Sink 到该 Iceberg 表（目前仅支持 Parquet 格式的 Iceberg 表）。此功能自 v3.1 起支持。

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

语法​

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

-- If you want to sink data to specified partitions, use the following syntax:
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. 将 SELECT 查询的结果（该查询从 partition_tbl_1 表中读取数据）插入到同一表中

    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. 使用 close 覆盖 partition_tbl_1 表中满足两个条件 dt='2023-09-01' 和 id=1 的分区中的所有 action 列值

    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 集群或云存储上的数据将随表一起删除，但表的 HDFS 集群或云存储上的文件路径会被保留。

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

DROP TABLE <table_name> [FORCE];

创建 Iceberg 视图​

您可以在 StarRocks 中定义 Iceberg 视图，或者将 StarRocks 方言添加到现有的 Iceberg 视图。针对此类 Iceberg 视图的查询支持抽象这些视图的 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']
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;

为现有 Iceberg 视图添加或修改 StarRocks 方言​

如果您的 Iceberg 视图是从其他系统（如 Apache Spark）创建的，同时您想从 StarRocks 查询这些视图，则可以将 StarRocks 方言添加到这些视图。 此功能自 v3.5 起支持。

注意
  • 您必须保证视图的两种方言的基本含义相同。 StarRocks 和其他系统不保证不同定义之间的一致性。
  • 您只能为每个 Iceberg 视图定义一个 StarRocks 方言。 您可以使用 MODIFY 子句更改方言的定义。
ALTER VIEW
[<catalog>.<database>.]<view_name>
(
    <column_name>
    [, <column_name>]
)
{ ADD | MODIFY } DIALECT
<query_statement>

示例​

  1. 将 StarRocks 方言添加到现有 Iceberg 视图 iceberg_view2。
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;

配置元数据缓存​

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

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

  • StarRocks 首先尝试从内存中检索请求的元数据。 如果元数据无法在内存中命中，StarRock 尝试从磁盘检索元数据。 StarRocks 从磁盘检索的元数据将被加载到内存中。 如果元数据也无法在磁盘中命中，StarRock 会从远程存储中检索元数据，并将检索到的元数据缓存在内存中。
  • 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 支持 快照。 使用最新的快照，您可以获得最新的结果。 因此，只有缓存的快照会影响数据新鲜度。 因此，您只需要关注包含快照的缓存的刷新策略。

下图显示了时间线上的时间间隔。

Timeline for updating and discarding cached metadata

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

  • 大量元数据的分布式计划

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

  • 少量元数据的本地计划

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

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

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

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