建立MaxCompute Paimon外部表格 -

MaxCompute支援通過建立Paimon外部表格來與儲存在OSS上的Paimon表目錄建立映射關係，並訪問其中的資料。本文將介紹如何建立Paimon外部表格並通過MaxCompute訪問Paimon外部表格。

背景資訊

Apache Paimon是一種流批一體的湖儲存格式，具備高吞吐的寫入和低延後查詢能力。阿里雲Realtime ComputeFlink版、開源巨量資料平台E-MapReduce的常見計算引擎（如Spark、Hive或Trino）都與Paimon有完善的整合。藉助Apache Paimon，您可以快速構建自己的資料湖儲存服務在儲存服務OSS上，並接入MaxCompute實現資料湖的分析。關於Apache Paimon的詳細資料，請參見Apache Paimon。

前提條件

當前執行操作的帳號已具備建立MaxCompute表（CreateTable）的許可權。更多表許可權資訊，請參見MaxCompute許可權。
已建立MaxCompute專案。具體操作，請參見建立MaxCompute專案。
已建立儲存空間（Bucket）以及對應的檔案目錄。具體操作，請參見建立儲存空間。
說明
由於MaxCompute只在部分地區部署，跨地區的資料連通性可能存在問題，因此建議Bucket與MaxCompute專案所在地區保持一致。
已購買Flink全託管，具體操作請參見開通Realtime ComputeFlink版。

注意事項

當前MaxCompute僅支援對Paimon外部表格的讀取操作，暫時不支援寫入和自動跟隨Paimon表結構變更等操作。
Paimon當前暫時不支援開啟了Schema操作的MaxCompute專案。
Paimon外部表格不支援cluster屬性。
Paimon外部表格暫不支援查詢回溯歷史版本的資料等特性。

建立Paimon外部表格命令文法

MaxCompute建立Paimon外部表格的文法定義如下：

CREATE EXTERNAL TABLE  [if NOT EXISTS] <mc_oss_extable_name>
(
<col_name> <data_type>,
...
)
[partitioned BY (<col_name> <data_type>, ...)]
stored BY 'org.apache.paimon.hive.PaimonStorageHandler'
WITH serdeproperties (
    'odps.properties.rolearn'='acs:ram::xxxxxxxxxxxxx:role/aliyunodpsdefaultrole'
)
location '<oss_location>'
USING 'paimon_maxcompute_connector.jar';

若您建立的Paimon外部表格為分區表時，需要額外執行引入分區資料的操作。命令詳情，請參見補全OSS外部表格分區資料文法。

方式一（推薦）：自動解析OSS目錄結構，識別分區，為OSS外部表格添加分區資訊。
```
msck repair TABLE <mc_oss_extable_name> ADD partitions;
```
方式二：手動執行如下命令為OSS外部表格添加分區資訊。
```
ALTER TABLE <mc_oss_extable_name> ADD PARTITION (<col_name>= <col_value>);
```

參數說明如下：

參數名稱	可選/必填	說明
mc_oss_extable_name	必填	待建立的Paimon外部表格的名稱。表名大小寫不敏感，在查詢外部表格時，無需區分大小寫，且不支援強制轉換大小寫。
col_name	必填	Paimon外部表格的列名稱。在讀取Paimon資料情境，建立的Paimon外部表格結構必須與Paimon資料檔案結構保持一致，否則無法成功讀取Paimon資料。
data_type	必填	Paimon外部表格的列資料類型。在讀取Paimon資料情境，建立的Paimon外部表格各列資料類型必須與Paimon資料檔案各列資料類型保持一致，否則無法成功讀取Paimon資料。
odps.properties.rolearn	必填	指定RAM中Role（具有訪問OSS許可權）的ARN資訊。您可以通過RAM控制台中的角色詳情擷取。
oss_location	必填	資料檔案所在OSS路徑。格式為`oss://<oss_endpoint>/<Bucket名稱>/<OSS目錄名稱>/`。MaxCompute預設會讀取該路徑下的所有資料檔案。 oss_endpoint：OSS訪問網域名稱資訊。您需要使用OSS提供的內網網域名稱，否則將產生OSS流量費用。例如`oss://oss-cn-beijing-internal.aliyuncs.com/xxx`。更多OSS內網網域名稱資訊，請參見OSS地區和訪問網域名稱。說明建議資料檔案存放的OSS地區與MaxCompute專案所在地區保持一致。由於MaxCompute只在部分地區部署，跨地區的資料連通性可能存在問題。 Bucket名稱：OSS儲存空間名稱，即Bucket名稱。更多查看儲存空間名稱資訊，請參見列舉儲存空間。目錄名稱：OSS目錄名稱。目錄後不需要指定檔案名稱。樣本如下： `oss://oss-cn-shanghai-internal.aliyuncs.com/oss-mc-test/Demo1/`

使用說明

步驟一：在Flink中準備資料

建立Paimon Catalog和Paimon表，並在表中插入資料，參考樣本操作步驟如下。如果您在Flink中已有Paimon表和資料，可以跳過此步。

登入Realtime Compute控制台，建立Paimon Catalog。具體操作，請參見建立Paimon Catalog。
建立Paimon表。具體操作，請參見管理Paimon表。
1. 在中繼資料管理頁面，選擇已建立Paimon Catalog下的default，然後單擊建立表，如下圖所示。
2. 在添加表對話方塊，選擇Apache Paimon連接器，輸入以下語句，單擊確定。本文以test_tbl表為例。
```
CREATE TABLE `catalogname`.`default`.test_tbl (
    dt STRING,
    id BIGINT,
    data STRING,
    PRIMARY KEY (dt, id) NOT ENFORCED
) PARTITIONED BY (dt);
```
3. 在SQL 開發頁面，建立包含如下語句的SQL作業，部署並運行作業。關於如何建立並運行SQL作業詳情，請參見SQL作業開發。
```
INSERT INTO `catalogname`.`default`.test_tbl VALUES ('2023-04-21', 1, 'AAA'), ('2023-04-21', 2, 'BBB'), ('2023-04-22', 1, 'CCC'), ('2023-04-22', 2, 'DDD');
```
  說明
  - 請確認SQL作業的引擎版本為vvr-8.0.1-flink-1.17及以上版本。
  - 若SQL作業有限流作業（例如執行INSERT INTO ... VALUES ...語句），需要在作業營運頁面，編輯運行參數配置，在其他配置設定execution.checkpointing.checkpoints-after-tasks-finish.enabled: true代碼。關於如何配置作業的運行參數詳情，請參見配置作業部署資訊。

步驟二：在MaxCompute專案中上傳Paimon外掛程式

您可以選擇以下其中一種方式，在已建立的MaxCompute專案中上傳Paimon外掛程式。

使用MaxCompute用戶端

通過用戶端（odpscmd）訪問已建立的MaxCompute專案，並執行以下代碼，將paimon_maxcompute_connector.jar上傳至MaxCompute專案中。

ADD JAR <path_to_paimon_maxcompute_connector.jar>;

使用DataWorks

登入DataWorks控制台，在左側導覽列選擇工作空間，單擊目標工作空間操作列中的快速進入 > 資料開發。
在資料開發頁面，單擊建立按鈕，選擇建立資源 > JAR。
在建立資源對話方塊，配置建立資源參數，上傳paimon_maxcompute_connector.jar，單擊建立。建立資源操作詳情，請參見步驟一：建立或上傳資源。
資源建立完成後，您需在資源編輯頁面，單擊工具列中的表徵圖，提交資源至調度程式開發伺服器端。

步驟三：通過MaxCompute建立Paimon外表

使用本地用戶端（odpscmd）串連或其他可以運行MaxCompute SQL的工具，建立MaxCompute Paimon外部表格。本文以oss_extable_paimon_1pt為例。

CREATE EXTERNAL TABLE oss_extable_paimon_1pt
(
    id BIGINT,
    data STRING
)
PARTITIONED BY (dt STRING )
stored BY 'org.apache.paimon.hive.PaimonStorageHandler'
WITH serdeproperties (
    'odps.properties.rolearn'='acs:ram::124*********:role/aliyunodpsdefaultrole'
)
location 'oss://oss-cn-beijing-internal.aliyuncs.com/paimon_flink/test_db_y.db/test_tbl/'
USING 'paimon_maxcompute_connector.jar'
;

步驟四：通過MaxCompute讀取Paimon外部表格

使用本地用戶端（odpscmd）或其他可以運行MaxCompute SQL的工具，執行以下命令。
```
SET odps.sql.common.table.planner.ext.hive.bridge = true;
SET odps.sql.hive.compatible = true;
```

執行以下命令，查詢MaxCompute Paimon外部表格oss_extable_paimon_1pt。

SELECT * FROM oss_extable_paimon_1pt;

樣本返回結果如下。

+------------+------------+------------+
| id         | data       | dt         |
+------------+------------+------------+
| 1          | AAA        | 2023-04-21 |
| 2          | BBB        | 2023-04-21 |
+------------+------------+------------+

說明

若返回結果中沒有顯示分區資訊，您可以通過如下命令追加分區資訊：

msck repair table oss_extable_paimon_1pt add partitions;

：Paimon外部表格