MaxCompute：使用外部項目基於FileSystem Catalog讀寫湖上Paimon資料

步驟一：來源資料準備

如在OSS中已有Paimon表資料，可跳過此步驟。

1. 登入OSS控制台，建立Bucket，本樣本中Bucket名為paimon-fs。詳情請參見建立儲存空間。在Bucket下建立目錄paimon-test。

2. 登入Flink控制台，在左上方選擇地區。

3. 單擊目標工作空間名稱，然後在左側導覽列，選擇資料管理。

4. 在右側Catalog列表 介面，單擊建立Catalog 。在彈出的建立 Catalog 對話方塊裡，選擇Apache Paimon，單擊下一步 並配置如下參數：

   參數	是否必填	說明
   metastore	必填	中繼資料存放區類型。本樣本中選擇filesystem。
   catalog name	必填	自訂catalog名稱，例如paimon-fs-catalog。
   warehouse	必填	OSS服務中所指定的數倉目錄。本樣本中oss://paimon-fs/paimon-test/。
   fs.oss.endpoint	必填	OSS服務的endpoint，例如杭州地區為oss-cn-hangzhou-internal.aliyuncs.com。
   fs.oss.accessKeyId	必填	訪問OSS服務所需的Access Key ID。
   fs.oss.accessKeySecret	必填	訪問OSS服務所需的Access Key Secret。

5. 基於Paimon Catalog建立Paimon表並寫入資料。

   1. 在左側導覽列，選擇資料開發 > 資料查詢。

   2. 在查詢指令碼頁簽，單擊，建立查詢指令碼。

      運行如下代碼，注意根據實際命名修改代碼中的相關命名：

      說明

      由於Flink使用Paimon Catalog，所以會預設遵守Paimon Catalog在檔案系統上的組織形式，即paimon_catalog_name/database_name.db/xxxx。若使用其他引擎讀寫OSS此目錄的Paimon資料，也需要遵守Paimon Catalog在檔案系統上的組織形式，並且只存放Paimon格式資料，否則會被識別為異常資料報錯。

      CREATE TABLE `paimon-fs-catalog`.`default`.test_tbl (
          id BIGINT,
          data STRING,
          dt STRING,
          PRIMARY KEY (dt, id) NOT ENFORCED
      ) PARTITIONED BY (dt)
      WITH (
          'bucket' = '3'
      );
      INSERT INTO `paimon-fs-catalog`.`default`.test_tbl 
        VALUES (1,'CCC','2024-07-18'), (2,'DDD','2024-07-18'),(3,'EEE','2025-06-18');

6. 查看產生的檔案。登入OSS控制台，查看Paimon Catalog綁定的OSS目錄下產生的Paimon表。

   在 OSS 目錄 /paimon-test/default.db/test_tbl/ 下，可以看到分區目錄 dt=2024-07-18/、dt=2025-06-18/，以及中繼資料目錄 manifest/、schema/、snapshot/。

步驟二：MaxCompute建立外部資料源

1. 登入MaxCompute控制台，在左上方選擇地區。

2. 在左側導覽列，選擇管理配置 > 外部数据源 。

3. 在外部数据源頁面，單擊创建外部数据源。

4. 在彈出的新增外部数据源對話方塊，根據介面提示配置相關參數。參數說明如下：

   參數	是否必填	說明
   外部数据源类型	必填	選擇Filesystem Catalog。
   外部数据源名称	必填	可自訂命名。命名規則如下： 以字母開頭，且只能包含小寫字母、底線和數字。 不能超過128個字元。 例如external_fs。
   外部数据源描述	選填	根據需要填寫。
   地域	必填	預設為當前地區。
   认证和鉴权	必填	預設為阿里雲RAM角色。
   RoleARN	必填	RAM角色的ARN資訊。此角色需要包含能夠同時訪問DLF和OSS服務的許可權。 登入RAM控制台。 在左側導覽列選擇身份管理 > 角色。 在基础信息地區，可以擷取ARN資訊。 樣本：acs:ram::124****:role/aliyunodpsdefaultrole。
   存储类型		OSS OSS-HDFS
   Endpoint		自動產生，杭州地區為：oss-cn-hangzhou-internal.aliyuncs.com。
   外部数据源补充属性	選填	特殊聲明的外部資料源補充屬性。指定後，使用此外部資料源的任務可以按照參數定義的行為訪問源系統。 說明 支援的具體參數請關注後續官網文檔更新說明，具體參數將隨產品能力演化逐步放開。

5. 單擊确认，完成外部資料源的建立。

6. 在外部数据源頁面，單擊目標資料來源對應的操作的详情，可查看資料來源詳細資料。

步驟三：MaxCompute建立外部項目

1. 登入MaxCompute控制台，在左上方選擇地區。

2. 在左側導覽列，選擇管理配置 > 项目管理。

3. 在外部项目頁簽，單擊新建项目。

4. 在彈出的新增项目對話方塊，根據介面提示文案設定項目資訊，單擊确认完成專案建立。

   參數	是否必填	說明
   项目类型	必填	預設為外部項目。
   地域	必填	預設為當前地區，此處無法修改。
   项目名称（全网唯一）	必填	字母開頭，包含字母、數字及底線（_），長度在3-28個字元。
   MaxCompute外部数据源类型	選填	選擇Filesystem Catalog。
   MaxCompute外部数据源	選填	选择已有：會出現已經建立過的外部資料源。 新建外部数据源：即可建立並使用新的外部資料源。
   MaxCompute外部数据源名称	必填	選擇已有：在下拉式清單中選擇已經建立好的外部資料源名稱。 建立外部資料源：則會使用建立的外部資料源名稱。
   认证和鉴权	必填	任務執行者身份，如未建立服務關聯角色，需要先建立才可以使用此模式。
   RoleARN	必填	RAM角色的ARN資訊。此角色需要包含能夠同時訪問DLF和OSS服務的許可權。 登入RAM控制台。 在左側導覽列選擇身份管理 > 角色。 在基础信息地區，可以擷取ARN資訊。 樣本：acs:ram::124****:role/aliyunodpsdefaultrole。
   存储类型		OSS OSS-HDFS
   Endpoint	必填	預設產生。
   Bucket 数据目录	必填	選擇完整的OSS Bucket和至Catalog層級的檔案系統目錄。本樣本中oss://paimon-fs/paimon-test/。
   表格式	必填	預設為Paimon。
   计算资源付费类型	必填	包年包月或按量付费。
   默认Quota	必填	選擇已有Quota.
   描述	選填	自訂專案描述。

步驟四：讀寫Paimon表

1. 選擇串連工具登入外部項目。

2. 進入新建立的外部項目，查看已有的Paimon schemas。

   -- 開啟session層級支援schema文法開關。
   SET odps.namespace.schema=true;
   SHOW schemas;
   -- 返回結果如下。
   ID = 20250922********wbh2u7
   default
   OK

3. 讀取default schema下的表。

   SET odps.sql.allow.fullscan=true; 
   SELECT * FROM <external_project_name>.default.test_tbl;
   -- 返回結果如下。
   +------------+------------+------------+
   | id         | data       | dt         | 
   +------------+------------+------------+
   | 1          | CCC        | 2024-07-18 | 
   | 2          | DDD        | 2024-07-18 | 
   | 3          | EEE        | 2025-06-18 | 
   +------------+------------+------------+

4. 向已存在的Paimon表中寫入資料。

   INSERT INTO test_tbl PARTITION(dt='2025-08-26') VALUES(4,'FFF');
   SELECT * FROM test_tbl;
   -- 返回結果如下。
   +------------+------------+------------+
   | id         | data       | dt         | 
   +------------+------------+------------+
   | 1          | CCC        | 2024-07-18 | 
   | 2          | DDD        | 2024-07-18 | 
   | 3          | EEE        | 2025-06-18 | 
   | 4          | FFF        | 2025-08-26 | 
   +------------+------------+------------+

5. 在建立的schema中建立表，並寫入資料。

   建立一張表寫入資料，MaxCompute也會按照Paimon Catalog在檔案系統上的組織形式寫入新資料。

   -- 建立schema。
   CREATE schema testschema;
   -- 在建立的schema中建表。
   use schema testschema;
   CREATE TABLE table_test(id INT, name STRING);
   -- 在建立的表中插入資料，並讀取。
   INSERT INTO table_test VALUES (101,'張三'),(102,'李四');
   SELECT * FROM table_test;
   -- 返回結果如下。
   +------------+------------+
   | id         | name       | 
   +------------+------------+
   | 101        | 張三        | 
   | 102        | 李四        | 
   +------------+------------+

6. 登入OSS控制台，在OSS中找到外部項目的Bucket目錄，可以看到建立的schema和表。