Paimon Catalog

背景信息

通过Paimon Catalog，您可以：

• 直接查询Apache Paimon里的数据。

• 新建Paimon库表，写Paimon数据。

• 通过INSERT INTO能力来实现数据转换和导入。

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

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

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

使用限制

仅在3.2.9及更高版本中，支持创建Paimon数据库、创建Paimon表以及向Paimon表插入数据。

创建Paimon Catalog

语法

CREATE EXTERNAL CATALOG <catalog_name>
[COMMENT <comment>]
PROPERTIES
(
    "type" = "paimon",
    CatalogParams,
    StorageCredentialParams
);

参数说明

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

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

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

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

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

• CatalogParams：StarRocks访问Paimon集群元数据的相关参数配置。Paimon集群使用的元数据类型不同，参数的配置也不同。

  • 使用DLF

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

  • 使用HMS

    属性	是否必须	说明
    paimon.catalog.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>"。

  • 使用filesystem

    属性	是否必须	说明
    paimon.catalog.type	是	数据源类型，取值为filesystem。
    paimon.catalog.warehouse	是	Paimon数据所在的Warehouse存储路径，支持HDFS、OSS和OSS-HDFS。OSS或OSS-HDFS格式为：oss://<yourBucketName>/<yourPath>。 重要 若使用OSS或OSS-HDFS作为warehouse，须配置参数aliyun.oss.endpoint。详情请参见StorageCredentialParams：StarRocks访问Paimon集群文件存储的相关参数配置。

• StorageCredentialParams：StarRocks访问Paimon集群文件存储的相关参数配置。

  • 如果您使用HDFS作为存储系统，则不需要配置StorageCredentialParams。

  • 如果您使用OSS或OSS-HDFS，则必须配置StorageCredentialParams。

    "aliyun.oss.endpoint" = "<YourAliyunOSSEndpoint>" 

    属性	是否必须	说明
    aliyun.oss.endpoint	是	使用OSS或OSS-HDFS，相应的Endpoint信息如下： OSS：您可以前往Bucket的概览页的访问端口区域获Endpoint，也可以参见OSS访问域名、数据中心、开放端口查看对应Region的Endpoint信息。如oss-cn-hangzhou.aliyuncs.com。 OSS-HDFS：您可以前往Bucket的概览页的访问端口区域获取HDFS服务的Endpoint。以杭州地域为例，示例值为cn-hangzhou.oss-dls.aliyuncs.com。 重要 使用该方式配置该参数后，您还需要在EMR Serverless StarRocks控制台的实例配置页面，修改core-site.xml和jindosdk.cfg中的参数fs.oss.endpoint，参数值与aliyun.oss.endpoint保持一致。

示例

以下示例创建了一个名为paimon_catalog的Paimon Catalog，用于查询Paimon数据源里的数据。

• 元数据类型paimon.catalog.type为dlf。

  CREATE EXTERNAL CATALOG paimon_catalog
  PROPERTIES
  (
      "type" = "paimon",
      "paimon.catalog.type" = "dlf",
      "paimon.catalog.warehouse" = "oss://<yourBucketName>/<yourPath>",
      "dlf.catalog.id" = "paimon_dlf_test"
  );

• 元数据类型paimon.catalog.type为hive。

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

• 元数据类型paimon.catalog.type为filesystem，使用OSS-HDFS作为存储。

  CREATE EXTERNAL CATALOG paimon_catalog
  PROPERTIES
  (
      "type" = "paimon",
      "paimon.catalog.type" = "filesystem",
      "paimon.catalog.warehouse" = "oss://<yourBucketName>/<yourPath>",
      "aliyun.oss.endpoint" = "cn-hangzhou.oss-dls.aliyuncs.com"
  );

查看Paimon Catalog

• 您可以通过SHOW CATALOGS查询当前StarRocks集群中的所有Catalog。

  SHOW CATALOGS;

• 您也可以通过SHOW CREATE CATALOG查询某个External Catalog的创建语句。

  SHOW CREATE CATALOG paimon_catalog;

删除Paimon Catalog​

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

DROP Catalog paimon_catalog;

创建Paimon数据库

CREATE DATABASE IF NOT EXISTS <catalog_name>.<database_name>;

创建Paimon表

语法

CREATE TABLE IF NOT EXISTS <catalog_name>.<database_name>.<table_name>
(
   id STRING,
   name STRING,
   day INT
)
PRIMARY KEY (id, day)  --创建append表时可省略--
PARTITION BY (`day`) --创建非分区表时可省略--
PROPERTIES (  --没有PROPERTIES时可省略--
  key = value
);

参数说明

常见PROPERTIES参数如下表所示。

使用限制

• 创建分区表时，所有分区列必须放置在列定义的最末端。

• 对于含有分区的表，所有分区列都必须包含在主键定义中。

• 指定的bucket_key不能同时作为分区列或主键的一部分。

示例

CREATE TABLE dlf_catalog.sr_dlf_db.ads_age_pvalue_analytics(
    final_gender_code STRING COMMENT '性别',
    age_level STRING COMMENT '年龄层次',
    pvalue_level STRING COMMENT '消费档次',
    clicks INT COMMENT '点击次数',
    total_behaviors INT COMMENT '总行为次数'
);

查看Paimon表结构

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

• 查看表结构

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

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

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

查询Paimon表数据

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

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

     SHOW DATABASES FROM <catalog_name>;

  2. 通过SET CATALOG切换当前会话生效的Catalog。

     SET CATALOG <catalog_name>;

     再通过USE指定当前会话生效的数据库。

     USE <db_name>;

     或者，也可以通过USE直接将会话切换到目标Catalog下的指定数据库。

     USE <catalog_name>.<db_name>;

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

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

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

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

写入Paimon数据

写入Paimon表

INSERT INTO <catalog_name>.<database_name>.<table_name> (column1, column2, ...) VALUES (value1, value2, ...);

例如，直接向ads_age_pvalue_analytics表插入以下数据。

INSERT INTO dlf_catalog.sr_dlf_db.ads_age_pvalue_analytics (final_gender_code, age_level, pvalue_level, clicks, total_behaviors)
VALUES 
('M', '18-24', 'Low', 1500, 2500),
('F', '25-34', 'Medium', 2200, 3300),
('M', '35-44', 'High', 2800, 4000);

导入Paimon数据至内表

假设StarRocks中存在一个OLAP表，表名为olap_tbl。您可以按照以下方式将Paimon表中的数据转换，并导入到StarRocks的olap_tbl表中。

INSERT INTO default_catalog.olap_db.olap_tbl SELECT * FROM <paimon_catalog>.<db_name>.<table_name>;

相关文档

• Paimon更多介绍，请参见Paimon概述。

• 使用DLF 2.0的更多介绍，请参见使用DLF 2.0 Catalog。