AI 助理
备案控制台
文档
输入文档关键字查找
首页 开源大数据平台 E-MapReduce EMR Serverless StarRocks 操作指南 开发指南 数据目录 Iceberg Catalog

Iceberg Catalog

更新时间：
产品详情
我的收藏

Iceberg Catalog是一种External Catalog，StarRocks从2.4版本开始支持。

背景信息

通过Iceberg Catalog，您可以：

  • 无需手动建表，通过Iceberg Catalog直接查询Iceberg内的数据。

  • 通过INSERT INTO或异步物化视图（2.5版本及以上）将Iceberg内的数据进行加工建模，并导入至StarRocks。

  • 在StarRocks侧创建或删除Iceberg库表，或通过INSERT INTO将StarRocks表数据写入到Parquet格式的Iceberg表中（3.1版本及以上）。

为保证正常访问Iceberg内的数据，StarRocks集群必须能够访问Iceberg集群的存储系统和元数据服务。目前StarRocks支持以下存储系统和元数据服务：

  • 分布式文件系统（HDFS）或阿里云对象存储OSS。

  • 元数据服务。当前支持的元数据服务包括Hive Metastore（以下简称HMS）、数据湖构建（DLF）。

使用说明​

StarRocks查询Iceberg数据时，注意以下几点。

文件格式

压缩格式

Iceberg表版本

Parquet

SNAPPY、LZ4、ZSTD、GZIP和NO_COMPRESSION

  • v1表：支持。

  • v2表：自StarRocks 3.1版本起支持position-delete，自3.1.10+、3.2.5+、3.3版本起支持equality-delete。

ORC

ZLIB、SNAPPY、LZO、LZ4、ZSTD和NO_COMPRESSION

  • v1表：支持。

  • v2表：自StarRocks 3.0版本起支持position-delete，自3.1.8+、3.2.3+、3.3版本起支持equality-delete。

创建Iceberg Catalog

语法​

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

参数说明

  • catalog_name：Iceberg Catalog的名称，必选参数。命名要求如下：

    • 必须由字母（a~z或A~Z）、数字（0~9）或下划线（_）组成，并且只能以字母开头。

    • 总长度不能超过64个字符。

    • Catalog名称大小写敏感。

  • comment：Iceberg Catalog的描述，此参数为可选。

  • type：数据源的类型，设置为iceberg。

  • MetastoreParams：StarRocks访问Iceberg集群元数据服务的相关参数配置。Iceberg使用的元数据服务不同，参数的配置也不同。

    • 使用HMS

      属性

      说明

      iceberg.catalog.type

      Iceberg中Catalog的类型，取值为hive。

      hive.metastore.uris

      Hive MetaStore的URI。格式为thrift://<Hive MetaStore的IP地址>:<端口号>，端口号默认为9083。

    • 使用DLF

      属性

      说明

      iceberg.catalog.type

      Iceberg中Catalog的类型，取值为dlf。

      dlf.catalog.id

      DLF中已有的数据目录ID。如果未配置dlf.catalog.id参数的值，则系统将使用默认的DLF Catalog。

示例

以下示例创建了一个名为iceberg_catalog_hms的Iceberg Catalog。

CREATE EXTERNAL CATALOG iceberg_catalog_hms
PROPERTIES
(
    "type" = "iceberg",
    "iceberg.catalog.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083"
);

查看Iceberg Catalog

您可以通过SHOW CATALOGS查询当前所在StarRocks里所有Catalog。

SHOW CATALOGS;

您也可以通过SHOW CREATE CATALOG查询某个External Catalog的创建语句。例如，通过如下命令查询Iceberg Catalogiceberg_catalog_hms的创建语句。

SHOW CREATE CATALOG iceberg_catalog_hms;

创建Iceberg数据库

与StarRocks内部数据目录（Internal Catalog）一致，如果您拥有Iceberg Catalog的CREATE DATABASE权限，那么您可以使用CREATE DATABASE在该Iceberg Catalog内创建数据库。本功能自3.1版本起开始支持。

说明

您可以通过GRANT和REVOKE操作对用户和角色进行权限的赋予和收回。

语法

切换至目标Iceberg Catalog，然后通过以下语句创建Iceberg数据库。

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

参数说明

location参数用于指定数据库所在的文件路径，支持HDFS和阿里云对象存储OSS：

  • 选择HDFS作为存储系统时，Prefix取值是hdfs。

  • 选择阿里云对象存储OSS作为存储系统时，Prefix取值是oss。

说明

如果您不指定location参数，则StarRocks会在当前Iceberg Catalog的默认路径下创建该数据库。

切换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数据库

同StarRocks内部数据库一致，如果您拥有Iceberg数据库的DROP权限，那么您可以使用DROP DATABASE来删除该Iceberg数据库。本功能自3.1版本起开始支持，仅支持删除空数据库。

说明

您可以通过GRANT和REVOKE操作对用户和角色进行权限的赋予和收回。

删除数据库操作并不会将HDFS或对象存储上的对应文件路径删除。切换至目标Iceberg Catalog，然后通过以下语句删除Iceberg数据库。

DROP DATABASE <database_name>;

删除Iceberg Catalog

您可以通过DROP CATALOG删除某个External Catalog。例如，通过以下命令删除iceberg_catalog_hms。

DROP Catalog iceberg_catalog_hms;

创建Iceberg表

同StarRocks内部数据库一致，如果您拥有Iceberg数据库的CREATE TABLE权限，那么您可以使用CREATE TABLE或CREATE TABLE AS SELECT (CTAS)在该Iceberg数据库下创建表。本功能自3.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']

    涉及参数说明如下表所示。

    参数

    说明

    col_name

    列名称。

    col_type

    列数据类型。

    • 当前支持如下数据类型：TINYINT、SMALLINT、INT、BIGINT、FLOAT、DOUBLE、DECIMAL、DATE、DATETIME、CHAR、VARCHAR[(length)]、ARRAY、MAP、STRUCT。

    • 不支持LARGEINT、HLL、BITMAP类型。

    说明

    所有非分区列的默认值均为NULL。分区列必须在最后声明，且不能为NULL。

  • partition_desc

    partition_desc语法定义如下所示。

    PARTITION BY (par_col1[, par_col2...])

    目前StarRocks仅支持Identity Transforms。即会为每个唯一的分区值创建一个分区。

    说明

    分区列必须在最后声明，支持除FLOAT、DOUBLE、DECIMAL、DATETIME以外的数据类型，并且不支持NULL值。

  • PROPERTIES

    可以在PROPERTIES中通过"key"="value"的形式声明Iceberg表的属性。具体请参见Iceberg 表属性，以下列出几个常见的属性。

    属性

    描述

    location

    Iceberg表所在的文件路径。使用HMS作为元数据服务时，您无需指定location参数。

    file_format

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

    compression_codec

    Iceberg表的压缩格式。当前支持SNAPPY、GZIP、ZSTD和LZ4。默认值：gzip。该属性自3.2.3版本起弃用，此后写入Iceberg表时的压缩算法统一由会话变量connector_sink_compression_codec控制。

示例

  • 创建非分区表unpartition_tbl，包含id和score两列。

    CREATE TABLE unpartition_tbl
(
    id int,
    score double
);

  • 创建分区表partition_tbl_1，包含action、id、dt三列，并定义id和dt为分区列。

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

  • 查询原表partition_tbl_1的数据，并根据查询结果创建分区表partition_tbl_2，定义id和dt为partition_tbl_2的分区列。

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

查看Iceberg表结构

您可以通过如下方法查看Iceberg表的表结构。

  • 查看表结构。

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

  • 从CREATE命令查看表结构和表文件存放位置。

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

向Iceberg表中插入数据

同StarRocks内表一致，如果您拥有Iceberg表的INSERT权限，那么您可以使用INSERT将StarRocks表数据写入到该Iceberg表中（当前仅支持写入到Parquet格式的Iceberg表）。本功能自3.1版本起开始支持。

说明

您可以通过GRANT和REVOKE操作对用户和角色进行权限的赋予和收回。

切换至目标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，因此导入时需要保证分区列有值。

参数说明

参数

说明

INTO

将数据追加写入目标表。

OVERWRITE

将数据覆盖写入目标表。

column_name

导入的目标列。可以指定一个或多个列。指定多个列时，必须用逗号（,）分隔。指定的列必须是目标表中存在的列，并且必须包含分区列。该参数可以与源表中的列名称不同，但顺序需一一对应。如果不指定该参数，则默认导入数据到目标表中的所有列。如果源表中的某个非分区列在目标列不存在，则写入默认值NULL。如果查询语句的结果列类型与目标列的类型不一致，会进行隐式转化，如果不能进行转化，那么INSERT INTO语句会报语法解析错误。

expression

表达式，用以为对应列赋值。

DEFAULT

为对应列赋予默认值。

query

查询语句，查询的结果会导入至目标表中。查询语句支持任意StarRocks支持的SQL查询语法。

PARTITION

导入的目标分区。需要指定目标表的所有分区列，指定的分区列的顺序可以与建表时定义的分区列的顺序不一致。指定分区时，不允许通过列名（column_name）指定导入的目标列。

示例

以下写入语句以默认的Parquet格式为例。

  • 向表partition_tbl_1中插入如下三行数据。

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

  • 向表partition_tbl_1按指定列顺序插入一个包含简单计算的SELECT查询的结果数据。

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

  • 向表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;

  • 向表partition_tbl_2中dt='2023-09-01'、id=1的分区插入一个SELECT查询的结果数据。

    • 方式1

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

    • 方式2

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

  • 将表partition_tbl_1中dt='2023-09-01'、id=1的分区下所有action列值全部覆盖为close：

    • 方式1

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

    • 方式2

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

查询Iceberg表数据

  1. 通过SHOW DATABASES查看指定Catalog所属的Iceberg集群中的数据库。

    SHOW DATABASES FROM <catalog_name>;

  2. 切换至目标Iceberg Catalog和数据库。

  3. 通过SELECT查询目标数据库中的目标表。

    SELECT count(*) FROM <table_name> LIMIT 10;

删除Iceberg表

同StarRocks内表一致，在拥有Iceberg表的DROP权限的情况下，您可以使用DROP TABLE来删除该Iceberg表。本功能自3.1版本起开始支持。

说明

您可以通过GRANT和REVOKE操作对用户和角色进行权限的赋予和收回。

删除表操作并不会将HDFS或对象存储上的对应文件路径和数据删除。强制删除表（增加FORCE关键字）会将HDFS或对象存储上的数据删除，但不会删除对应文件路径。切换至目标Iceberg Catalog和数据库，然后通过以下语句删除Iceberg表。

DROP TABLE <table_name> FORCE;

相关文档

Iceberg更多介绍，请参见Iceberg概述。

上一篇：Hive Catalog下一篇：Hudi Catalog
文档推荐