Paimon Catalog - E-MapReduce

Paimon Catalog是一種External Catalog，自StarRocks 3.1版本開始支援。本文為您介紹如何建立和查看Paimon Catalog。

背景資訊

通過Paimon Catalog，您可以：

直接查詢Apache Paimon裡的資料。
建立Paimon庫表，寫Paimon資料。
通過INSERT INTO能力來實現資料轉換和匯入。

為保證正常訪問Paimon內的資料，StarRocks叢集必須能夠訪問Paimon叢集的儲存系統和中繼資料服務。目前StarRocks支援以下儲存系統和中繼資料服務：

Distributed File System（HDFS）或阿里雲Object Storage Service。
中繼資料服務。當前支援的中繼資料服務包括資料湖構建DLF 1.0（舊版）、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
);

參數說明

說明

StarRocks的Paimon Catalog與原生Paimon API裡的Catalog是一一映射關係，配置項和配置含義都相同。

Paimon叢集使用的中繼資料類型不同，參數的配置也不同。

使用HMS

catalog_name：Paimon Catalog的名稱，必選參數。命名要求如下：
- 必須由字母（a~z或A~Z）、數字（0~9）或底線（_）組成，並且只能以字母開頭。
- 總長度不能超過64個字元。
comment：Paimon Catalog的描述。此參數為可選。
type：資料來源的類型。設定為paimon。

CatalogParams：StarRocks訪問Paimon叢集中繼資料的相關參數配置。

屬性	是否必須	說明
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>"`。

StorageCredentialParams：StarRocks訪問Paimon叢集檔案儲存體的相關參數配置。

如果您使用HDFS作為儲存系統，則不需要配置StorageCredentialParams。

如果您使用OSS或OSS-HDFS，則必須配置StorageCredentialParams。

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

涉及參數說明如下表所示。

屬性

說明

aliyun.oss.endpoint

使用OSS或OSS-HDFS，相應的Endpoint資訊如下：

OSS：您可以前往Bucket的概覽頁的訪問連接埠地區獲Endpoint，也可以參見地區和Endpoint查看對應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保持一致。

使用filesystem

catalog_name：Paimon Catalog的名稱，必選參數。命名要求如下：
- 必須由字母（a~z或A~Z）、數字（0~9）或底線（_）組成，並且只能以字母開頭。
- 總長度不能超過64個字元。
comment：Paimon Catalog的描述。此參數為可選。
type：資料來源的類型。設定為paimon。

CatalogParams：StarRocks訪問Paimon叢集中繼資料的相關參數配置。Paimon叢集使用的中繼資料類型不同，參數的配置也不同。

屬性	是否必須	說明
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，也可以參見地區和Endpoint查看對應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保持一致。

使用DLF 1.0（舊版）

catalog_name：Paimon Catalog的名稱，必選參數。命名要求如下：
- 必須由字母（a~z或A~Z）、數字（0~9）或底線（_）組成，並且只能以字母開頭。
- 總長度不能超過64個字元。
comment：Paimon Catalog的描述。此參數為可選。
type：資料來源的類型。設定為paimon。

CatalogParams：StarRocks訪問Paimon叢集中繼資料的相關參數配置。Paimon叢集使用的中繼資料類型不同，參數的配置也不同。

屬性	是否必須	說明
paimon.catalog.type	是	資料來源類型，取值為`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.catalog.id`參數的值，則系統將使用預設的DLF Catalog。

StorageCredentialParams：StarRocks訪問Paimon叢集檔案儲存體的相關參數配置。

如果您使用HDFS作為儲存系統，則不需要配置StorageCredentialParams。

如果您使用OSS或OSS-HDFS，則必須配置StorageCredentialParams。

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

涉及參數說明如下表所示。

屬性

說明

aliyun.oss.endpoint

使用OSS或OSS-HDFS，相應的Endpoint資訊如下：

OSS：您可以前往Bucket的概覽頁的訪問連接埠地區獲Endpoint，也可以參見地區和Endpoint查看對應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保持一致。

使用DLF

說明

僅支援3.3.8及以上版本的執行個體使用DLF，建議升級至最新版本。

catalog_name：Paimon Catalog的名稱，必選參數。命名要求如下：
- 必須由字母（a~z或A~Z）、數字（0~9）或底線（_）組成，並且只能以字母開頭。
- 總長度不能超過64個字元。
comment：Paimon Catalog的描述。此參數為可選。
type：資料來源的類型。設定為paimon。

CatalogParams：StarRocks訪問Paimon叢集中繼資料的相關參數配置。Paimon叢集使用的中繼資料類型不同，參數的配置也不同。

重要

如果使用DLF，則必須使用已配置好的RAM使用者串連StarRocks Manager進行相應的操作，詳情請參見使用DLF Catalog。

參數	是否必須	說明
`<catalog_name>`	是	DLF資料目錄（Catalog）的名稱，例如，`dlf_catalog`。
`type`	是	Catalog類型，填寫固定值`paimon`。
`uri`	是	DLF的REST API地址。填寫的格式為`http://<VPC網路Endpoint>`，其中 `<VPC網路Endpoint>`是DLF服務在指定地區的VPC網路訪問網域名稱。例如，`http://cn-hangzhou-vpc.dlf.aliyuncs.com`。
`paimon.catalog.type`	是	Paimon Catalog類型，填寫固定值`rest`。
`paimon.catalog.warehouse`	是	Paimon Catalog的名稱，您可以在資料湖構建控制台的資料目錄頁面擷取。
`token.provider`	是	Rest服務提供者，填寫固定填`dlf`。

StorageCredentialParams：StarRocks訪問Paimon叢集檔案儲存體的相關參數配置。

如果您使用HDFS作為儲存系統，則不需要配置StorageCredentialParams。

如果您使用OSS或OSS-HDFS，則必須配置StorageCredentialParams。

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

涉及參數說明如下表所示。

屬性

說明

aliyun.oss.endpoint

使用OSS或OSS-HDFS，相應的Endpoint資訊如下：

OSS：您可以前往Bucket的概覽頁的訪問連接埠地區獲Endpoint，也可以參見地區和Endpoint查看對應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資料來源裡的資料。

使用HMS

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

使用filesystem

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

使用DLF 1.0（舊版）

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

使用DLF

CREATE EXTERNAL CATALOG dlf_catalog
PROPERTIES
(
   "type"= "paimon",
   "uri" = "http://cn-hangzhou-vpc.dlf.aliyuncs.com",
   "paimon.catalog.type" = "rest",
   "paimon.catalog.warehouse" = "test_paimon",
   "token.provider" = "dlf"
);

查看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_catalog的Paimon 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參數如下表所示。

key	說明
file.format	定義表的資料存放區格式，預設為`parquet`。
bucket	設定表的桶數，用於資料分布和查詢最佳化，預設為-1，意味著不使用桶表。
bucket_key	指定用於分配記錄到各個桶的列。

使用限制

建立分區表時，所有分區列必須放置在列定義的最末端。
對於含有分區的表，所有分區列都必須包含在主鍵定義中。
指定的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表

說明

在StarRocks中，寫入Paimon表的方式為批量寫入（Batch Write）。由於Paimon的限制，無法對Bucket Mode為HASH_DYNAMIC或CROSS_PARTITION的表進行寫入。一個典型的情境是，當寫入主鍵表時，如果該表的建表語句中的PROPERTIES未指定bucket，預設值將為-1（即Dynamic Bucket Mode），這將導致無法執行寫入操作。
Paimon SDK要求寫入的資料中的分區鍵或主鍵列不可為空白值，而StarRocks在寫入Paimon表時不會對即將寫入的資料進行預檢查，因此如果嘗試將空值寫入到包含值的Chunk時，將會拋出異常。

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>;

E-MapReduce：Paimon Catalog

背景資訊

使用限制

建立Paimon Catalog

文法

參數說明

使用HMS

使用filesystem

使用DLF 1.0（舊版）

使用DLF

樣本

使用HMS

使用filesystem

使用DLF 1.0（舊版）

使用DLF

查看Paimon Catalog

刪除Paimon Catalog

建立Paimon資料庫

建立Paimon表

文法

參數說明

使用限制

樣本

查看Paimon表結構

查詢Paimon表資料

寫入Paimon資料

寫入Paimon表

匯入Paimon資料至內表

相關文檔

背景資訊

使用限制

建立Paimon Catalog

文法

參數說明

使用HMS

使用filesystem

使用DLF 1.0（舊版）

使用DLF

樣本

使用HMS

使用filesystem

使用DLF 1.0（舊版）

使用DLF

查看Paimon Catalog

刪除Paimon Catalog​

建立Paimon資料庫

建立Paimon表

文法

參數說明

使用限制

樣本

查看Paimon表結構

查詢Paimon表資料

寫入Paimon資料

寫入Paimon表

匯入Paimon資料至內表

相關文檔

刪除Paimon Catalog