背景信息

通過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。對于DLF 1.0，如果未配置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。