Unified Catalog

背景信息

通过Unified Catalog，您可以把Apache Paimon、Apache Hive™、Apache Iceberg、Apache Hudi、Apache Kudu和Delta Lake数据源作为一个融合的数据源，不需要执行导入就可以直接操作其中的表数据，包括：

• 无需手动建表，通过Unified Catalog直接查询Paimon、Hive、Iceberg、Hudi、Kudu和Delta Lake数据源里的数据。

• 通过INSERT INTO或异步物化视图（2.5版本及以上）将Hive、Iceberg、Hudi、Delta Lake和Kudu数据源里的数据进行加工建模，并导入至StarRocks。

• 在StarRocks侧创建或删除Hive、Iceberg库表。

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

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

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

使用限制

一个Unified Catalog当前只支持对接一个元数据服务。因此，您需要确保通过Unified Catalog访问的所有数据源都使用同一个元数据服务。

• 当元数据类型是hive时，Unified Catalog支持访问Apache Paimon、Apache Hive、Apache Iceberg、Apache Hudi、Apache Kudu和Delta Lake数据源的数据。您还需确保Serverless StarRocks集群能够正常访问您所使用的Hive集群。

• 当元数据类型是dlf时，Unified Catalog支持访问Apache Paimon、Apache Hive、Apache Iceberg、Apache Hudi和Delta Lake数据源的数据。

创建Unified Catalog

语法

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

参数说明

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

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

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

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

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

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

  • 使用DLF

    属性	是否必须	说明
    unified.metastore.type	是	数据源类型，取值为dlf。
    dlf.catalog.id	是	DLF中已有的数据目录ID。仅当hive.metastore.type配置为dlf时需要填写该参数。如果未配置dlf.catalog.id参数的值，则系统将使用默认的DLF Catalog。
    paimon.catalog.warehouse	否	当使用Paimon数据源时填写。 Paimon数据所在的Warehouse存储路径，支持HDFS、OSS和OSS-HDFS。OSS或OSS-HDFS格式为：oss://<yourBucketName>/<yourPath>。 重要 若使用OSS或OSS-HDFS作为warehouse，须配置参数aliyun.oss.endpoint。详情请参见StorageCredentialParams：StarRocks访问Paimon集群文件存储的相关参数配置。

  • 使用Hive MetaStore

    参数	是否必须	说明
    unified.metastore.type	是	元数据服务的类型。设置为hive。
    hive.metastore.uris	是	HMS的URI。格式为thrift://<HMS IP地址>:<端口号>，端口号默认为9083。 如果您的HMS开启了高可用模式，此处可以填写多个HMS地址并用逗号分隔，例如："thrift://<HMS IP地址1>:<HMS端口号 1>,thrift://<HMS IP地址2>:<HMS 端口号2>,thrift://<HMS IP地址3>:<HMS端口号3>"。

示例

以下示例创建了一个名为unified_catalog的Unified Catalog，用于查询融合数据源里的表数据。

• 元数据类型unified.metastore.type为dlf。

  CREATE EXTERNAL CATALOG unified_catalog
  PROPERTIES
  (
      "type"="unified",
      "unified.metastore.type"="dlf",
      "paimon.catalog.warehouse"="oss://<YourBucketName>/<YourPath>/",
       "dlf.catalog.id" = "unified_dlf_test"
  );

• 元数据类型unified.metastore.type为hive，使用HDFS作为存储。

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

切换Unified Catalog和数据库​

您可以通过如下方法切换至目标Unified Catalog和数据库。

• 先通过SET CATALOG指定当前会话生效的Unified Catalog，然后再通过USE指定数据库。

  -- 切换当前会话生效的 Catalog
  SET CATALOG <catalog_name>
  -- 指定当前会话生效的数据库
  USE <db_name>

• 通过USE直接将会话切换到目标Unified Catalog下的指定数据库。

  USE <catalog_name>.<db_name>

删除Unified Catalog

您可以通过DROP CATALOG删除某个External Catalog。

例如，通过如下命令删除Unified Catalogunified_catalog。

DROP CATALOG unified_catalog;

查看Unified Catalog内的表结构

您可以通过如下方法查看Hive表的表结构：

• 查看表结构

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

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

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

查询Unified Catalog内的表数据

• 您可以通过如下操作查询Unified Catalog内的表数据。

  1. 通过SHOW DATABASES查看指定 Unified Catalog 所属的数据源中的数据库。

     SHOW DATABASES FROM <catalog_name>;

  2. 切换Unified Catalog和数据库。

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

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

• 您也可以通过SELECT查询目标数据库中的目标表。

  SELECT * FROM <catalog_name>.<database_name>.<table_name>;

从Hive、Iceberg、Hudi、Delta Lake或Kudu导入数据

您可以通过INSERT INTO将 Hive、Iceberg、Hudi、Delta Lake或Kudu表中的数据导入StarRocks中Unified Catalog下的表。

例如，通过如下命令将Hive表hive_table的数据导入到StarRocks中Unified Catalogunified_catalog下数据库test_database里的表test_table。

INSERT INTO unified_catalog.test_database.test_table SELECT * FROM hive_table;

在Unified Catalog内创建数据库

同StarRocks内部数据目录（Internal Catalog）一致，如果您拥有Unified Catalog的CREATE DATABASE权限，那么您可以使用CREATE DATABASE在该Unified Catalog内创建数据库。

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

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

如果您在创建数据库时不指定location，那么系统会使用默认的<warehouse_location>/<database_name.db>作为文件路径。

location：用于指定数据库所在的文件路径，支持HDFS、阿里云OSS或OSS-HDFS。其中，prefix根据存储系统的不同而不同。

• HDFS：取值为hdfs。

• 阿里云OSS或OSS-HDFS：取值为oss。

从Unified Catalog内删除数据库​

同StarRocks内部数据库一致，如果您拥有Unified Catalog内数据库的DROP权限，那么您可以使用DROP DATABASE来删除该数据库。仅支持删除空数据库。

切换至目标Unified Catalog，然后通过如下语句删除数据库。

DROP DATABASE <database_name>;

在Unified Catalog内创建表​

同StarRocks内部数据库一致，如果您拥有Unified Catalog内数据库的CREATE TABLE权限，那么您可以使用CREATE TABLE或CREATE TABLE AS SELECT (CTAS)在该数据库下创建表。

切换至目标Unified Catalog和数据库，然后通过CREATE TABLE创建Hive表或Iceberg表。

CREATE TABLE <table_name>
(column_definition1[, column_definition2, ...]
ENGINE = {|hive|iceberg}
[partition_desc]

有关创建Hive表和Iceberg表的详细信息，请参见创建Hive表和创建Iceberg表。

例如，通过如下语句，创建一张Hive表hive_table。

CREATE TABLE hive_table
(
    action varchar(65533),
    id int,
    dt date
)
ENGINE = hive
PARTITION BY (id,dt);

向Unified Catalog内的表中插入数据​

同StarRocks内表一致，如果您拥有Unified Catalog内表的INSERT权限，那么您可以使用INSERT将StarRocks表数据写入到该表（当前仅支持写入到Parquet格式的Unified Catalog表）。

切换至目标Unified Catalog和数据库，然后通过INSERT INTO向Hive表或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 }

有关向Hive表和Iceberg表中插入数据的详细信息，请参见向Hive表中插入数据和向Iceberg表中插入数据。

例如，通过如下语句，向Hive表hive_table中写入如下数据。

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

从Unified Catalog内删除表​

同StarRocks内表一致，如果您拥有Unified Catalog内表的DROP权限，那么您可以使用DROP TABLE来删除该表。

切换至目标Unified Catalog和数据库，然后通过DROP TABLE删除Hive表或Iceberg表。

DROP TABLE <table_name>;

例如，通过如下语句，删除Hive表hive_table。

DROP TABLE hive_table FORCE;