跳到主要内容
版本：Candidate-3.5

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",
    MetastoreParams,
    StorageCredentialParams,
    MetadataUpdateParams
)

参数​

catalog_name​

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

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

comment​

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

type​

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

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>"

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 相关的元数据，包括表缓存、分区名称缓存以及 Manifest 中的数据文件缓存和删除数据文件缓存。
iceberg_manifest_cache_with_column_statisticsfalse是否缓存列的统计信息。
iceberg_manifest_cache_max_num100000可以缓存的 Manifest 文件的最大数量。
refresh_iceberg_manifest_min_length2 * 1024 * 1024触发数据文件缓存刷新的最小 Manifest 文件长度。

示例​

以下示例创建了一个名为 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"
    );

使用您的 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]
[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 作为元存储时，无需指定 location 参数，因为 StarRocks 会在当前 Iceberg catalog 的默认文件路径中创建表。当您使用 AWS Glue 作为元存储时：

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

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

compression_codec​

描述：Iceberg 表使用的压缩算法。支持的压缩算法有 SNAPPY、GZIP、ZSTD 和 LZ4。默认值：gzip。此属性在 v3.2.3 中已弃用，从该版本开始，导入数据到 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;

将数据下沉到 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 集群的元数据文件可能存储在远端存储中，例如 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 将不刷新其缓存元数据。

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

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

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

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

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

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

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

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