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

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_statisticsfalse是否缓存列的统计信息。
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 DDL 操作​

DDL 操作（CREATE/DROP DATABASE、CREATE/DROP TABLE、CREATE/ALTER VIEW），请参见 Iceberg DDL 操作。

Iceberg DML 操作​

DML 操作（INSERT），请参见 Iceberg DML 操作。

Iceberg Procedures​

有关 Iceberg Procedures，请参见 Iceberg Procedures。

配置元数据缓存​

您的 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.