MaxCompute：Paimon_DLF外部項目

步驟一：授權

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

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

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

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

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

   參數	是否必填	說明
   外部数据源类型	必填	選擇Paimon_DLF。
   外部数据源名称	必填	可自訂命名。命名規則如下： 以字母開頭，且只能包含小寫字母、底線和數字。 不能超過128個字元。 例如paimon_dlf。
   外部数据源描述	選填	根據需要填寫。
   地域	必填	預設為當前地區。
   认证和鉴权	必填	預設為阿里雲RAM角色。
   关联服务角色	必填	預設產生。
   Endpoint	必填	自動產生，杭州地區為：cn-hangzhou-intranet.dlf.aliyuncs.com
   外部数据源补充属性	選填	特殊聲明的外部資料源補充屬性。指定後，使用此外部資料源的任務可以按照參數定義的行為訪問源系統。 說明 支援的具體參數請關注後續官網文檔更新說明，具體參數將隨產品能力演化逐步放開。

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

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

步驟三：建立外部項目

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

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

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

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

   參數	是否必填	說明
   项目类型	必填	預設為外部項目。
   地域	必填	預設為當前地區，此處無法修改。
   项目名称（全网唯一）	必填	字母開頭，包含字母、數字及底線（_），長度在3-28個字元。
   MaxCompute外部数据源类型	選填	預設為Paimon_DLF。
   MaxCompute外部数据源	選填	选择已有：會出現已經建立過的外部資料源。 新建外部数据源：即可建立並使用新的外部資料源。
   MaxCompute外部数据源名称	必填	選擇已有：在下拉式清單中選擇已經建立好的外部資料源名稱。 建立外部資料源：則會使用建立的外部資料源名稱。
   数据目录	必填	DLF資料目錄。
   计算资源付费类型	必填	包年包月或按量付费。
   默认Quota	必填	選擇已有Quota.
   描述	選填	自訂專案描述。

步驟四：使用SQL訪問資料來源系統

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

   如下為DataWorks新版工作空間資料開發SQL節點操作樣本。

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

   2. 在左側導覽列選擇工作空間。

   3. 在工作空間列表頁面，單擊建立工作空間或單擊已有目標工作空間名稱。

   4. 在空間詳情頁面，單擊左側導覽列計算資源。

   5. 在計算資源頁面，單擊綁定計算資源，選擇MaxCompute。

   6. 填寫綁定MaxCompute計算資源的基本信息。

      其中MaxCompute專案選擇外部項目。

2. 列出外部項目中的schema。

   -- 開啟session層級支援schema文法開關。
   SET odps.namespace.schema=true;
   SHOW schemas;
   -- 樣本返回結果。 
   ID = 20250919****am4qb
   default
   system
   OK

3. 在外部項目中列出schema下的表。

   如果需要在當前環境訪問生產外部項目的表，需要在所有SQL前加上use externao_project_pro;

   -- schema_name為外部項目中show出來的Schema名稱。
   SET odps.namespace.schema=true;
   USE schema <schema_name>;
   SHOW tables;
   -- 返回結果。
   ID = 20250919****am4qb
   acs:ram::<uid>:root  emp
   OK

4. 在外部項目中建立schema。

   -- 本樣本中schema_name為schema_demo_test。
   CREATE schema <schema_name>;

5. 使用建立的schema。

   USE schema <schema_name>;

6. 在schema中建立表並插入資料。

   如果是RAM使用者登入，此操作需要有DLF Catalog的操作許可權，授權操作見資料授權管理。

   • 命令格式：

     -- 建立表。
     CREATE TABLE [IF NOT EXISTS] <table_name> 
     (
       <col_name> <data_type>,
       ...
     )
     [COMMENT <table_comment>]
     [PARTITIONED BY (<col_name> <data_type>, ...)] 
     ;
     -- 插入資料。
     INSERT {INTO|OVERWRITE} TABLE <table_name> [PARTITION (<pt_spec>)] [(<col_name> [,<col_name> ...)]]
     <select_statement>
     FROM <from_statement>

   • 使用樣本：

     說明

     針對Paimon源表TIMESTAMP低精度類型，在寫入時會截斷處理。0～3按照3位截斷，4～6按照6位截斷，7～9按照9位截斷。

     CREATE TABLE schema_table(id int,name string);
     INSERT INTO schema_table VALUES (101,'張三'),(102,'李四');
     -- 查詢表schema_table。
     SELECT * FROM schema_table;
     -- 返回結果。
     +------------+------------+
     | id         | name       | 
     +------------+------------+
     | 101        | 張三        | 
     | 102        | 李四        | 
     +------------+------------+

7. 切換為已有的default schema。

   use schema default;
   SHOW tables;
   -- 返回結果樣本。
   ID = 20250919*******yg5
   acs:ram::<uid>:root	emp
   acs:ram::<uid>:root	emp_detail
   acs:ram::<uid>:root	test_table
   OK
   -- 讀取表。
   SELECT * FROM test_table;
   -- 返回結果。
   +------------+------------+
   | id         | name       | 
   +------------+------------+
   | 101        | 張三        | 
   | 102        | 李四        | 
   +------------+------------+
   -- 寫入表並查詢寫入是否成功。
   INSERT INTO test_table VALUES (103,'王五');
   SELECT * FROM test_table;
   -- 返回結果。
   +------------+------------+
   | id         | name       | 
   +------------+------------+
   | 101        | 張三        | 
   | 102        | 李四        | 
   | 103        | 王五        | 
   +------------+------------+

參考樣本

Paimon外表設定bucket>0、主鍵列為id和分區欄位。

1. 建立表，配置外部表格參數

   -- 進入到外部項目，如已經在外部項目內，可不加。
   use <your external project>;
   -- 開啟session層級支援schema文法開關。
   SET odps.namespace.schema=true;
   -- 選擇要使用的schema。
   use schema <your schema>;
   CREATE TABLE oss_extable_bucket_pk_pt_bucket
   (
       id BIGINT,
       name STRING,
       dt STRING
   )tblproperties (
       'mcfed.bucket'='3', -- bucket數量
       'mcfed.bucket-key'='id', -- bucket key，有primary-key時可不寫
       "mcfed.primary-key"="dt,id", -- primary-key
       "mcfed.partition"="dt" -- 分區欄位
       );

2. 向外部表格插入資料

   INSERT INTO oss_extable_bucket_pk_pt_bucket PARTITION (dt='2025-06-18') 
     VALUES (1, 'Alice'),(2, 'Bob');
   INSERT INTO oss_extable_bucket_pk_pt_bucket PARTITION (dt='2025-06-19') 
     VALUES (3, 'Charlie'),(4, 'David'),(5, 'Eva');

3. 查詢外部表格

   SELECT * FROM oss_extable_bucket_pk_pt_bucket;
   -- 返回結果：
   +------------+---------+------------+
   | id         | name    | dt         |
   +------------+---------+------------+
   | 1          | Alice   | 2025-06-18 |
   | 2          | Bob     | 2025-06-18 |
   | 4          | David   | 2025-06-19 |
   | 3          | Charlie | 2025-06-19 |
   | 5          | Eva     | 2025-06-19 |
   +------------+---------+------------+
   

4. 登入資料湖構建（DLF）控制台，在左上方選擇地區。

   查看該catalog下產生表的詳情：

   表名為 oss_extable_bucket_pk_pt_bucket，表格式為 Paimon PK 表，表類型為 Managed，檔案格式為 parquet，所屬資料庫 default。Table Properties 中關鍵配置：bucket: 3、manifest.merge-min-count: 10。欄位列表包含：id（BIGINT，非空，PK 欄位，非分區）、name（STRING，可空，非 PK，非分區）、dt（STRING，非空，PK 欄位，分區欄位）。

問題一：點擊建立外部項目報錯

問題描述：在建立外部項目時提示錯誤：“You are not authorized to perform this action.”

錯誤詳情中錯誤碼為 NoMCPermission。

解決方案：

1. 如果是RAM使用者，首先確認已經賦予RAM使用者AliyunMaxComputeFullAccess許可權，詳情見操作步驟一。

2. 由於該入口會選擇到DLF的catalog，確認已經授予DLF相關操作許可權，詳情見操作步驟一。

問題二：在外部項目的default schema下執行show tables報錯

問題描述：外部項目的default schema下執行show tables，提示錯誤：“Forbidden:User acs: ram: :<uid>:user/** doesn't have privilege LIST on DATABASE default”。

解決方案：

1. 登入資料湖構建（DLF）控制台，在左上方選擇地區。

2. 在左側導覽列選擇系统和安全

3. 在访问控制 > 用户頁簽，重新整理查看當前RAM是否存在。

4. 若存在，則在访问控制 > 角色給RAM使用者授權。

問題三：報錯ivalid database operations on two-tier

問題描述：外部項目內執行show schemas報錯invalid database operations on two-tier。

解決方案：

1. 首先確認當前使用的專案為外部項目。

   1. 若用DataWorks的SQL節點，點擊右側調試配置/調試配置，查看綁定的計算資源是否為外部項目。

   2. 若用DataWorks的SQL分析，點擊右上方資料來源，查看繫結資料源是否為外部項目。

   3. 若用MaxCompute的SQL分析，點擊右側回合組態，查看計算資源處選擇的專案是否為外部項目。

   4. 若用odpscmd，查看odps_config.ini檔案中的project_name參數值是否為外部項目。

2. 確認使用的是外部項目後，執行如下SQL，需選中一起執行。

   -- 開啟session層級支援schema文法開關。
   SET odps.namespace.schema=true;
   SHOW schemas;

問題四：執行show schemas只有default schema

問題描述：在外部項目內執行show schemas，返回結果只有default。

解決方案：

1. 首先確認當前使用的專案是外部項目。

   1. 若用DataWorks的SQL節點，點擊右側調試配置/調試配置，查看綁定的計算資源是否為外部項目。

   2. 若用DataWorks的SQL分析，點擊右上方資料來源，查看繫結資料源是否為外部項目。

   3. 若用MaxCompute的SQL分析，點擊右側回合組態，查看計算資源處選擇的專案是否為外部項目。

   4. 若用odpscmd，查看 odps_config.ini 檔案中的project_name參數值是否為外部項目。

2. 確認是外部項目後，登入資料湖構建（DLF）控制台確認當前外部項目綁定的catalog下是否有其他資料庫。

3. 如以上1和2確認完成，show schemas結果仍沒有預期的資料庫，可以提交工單反饋問題。

問題五：報錯You should use dynamic bucket (bucket = -1) mode in cross partition update

問題描述：外部項目內執行show tables報錯ODPS-0110005: com.aliyun.odps.meta.exception.MetaException: com.aliyun.odps.common.table.na.NativeException: common/table/jni/utils/jni_helper.cpp(79): UnretryableException: Common table connector exception - ExceptionType: java.lang.IllegalArgumentException - Message: You should use dynamic bucket (bucket = -1) mode in cross partition update case (Primary key constraint [sending_time, symbol, sequence_number] not include all partition fields [pt]).[pt])

解決方案：

MaxCompute目前不支援“固定bucket的cross partition pk表”，所以在show tables的時候會報錯。

臨時繞過方案：通過資料湖構建（DLF）控制台刪除不支援的cross partition pk表。

問題六：報錯Can't set default schema if odps.namespace.schema is false

問題描述：執行show tables/show schemas報錯 FAILED: Can't set default schema if odps.namespace.schema is false.

解決方案：

1. 優先查看SQL前是否加了session層級支援schema文法開關 SET odps.namespace.schema=true;。

2. 如果開啟開關後還是報錯，需要確認指令順序，若要讀其他外部項目的表，參數正確順序如下：

   USE external_project;
   SET odps.namespace.schema=true;
   USE schema schema_name;
   SHOW tables;

問題七：報錯Failed to connect to cn-hangzhou-intranet.dlf.aliyuncs.com

問題描述：讀 Paimon_DLF 外部項目的表報錯：Caused by: java.net.ConnectException: Failed to connect to cn-hangzhou-intranet.dlf.aliyuncs.com/xx.xx.xx.xx:80

上述報錯表示當前讀表方式需給當前執行作業的內部專案加白名單，地址為cn-hangzhou-intranet.dlf.aliyuncs.com。

解決方案：

1. 通過申請連結或搜尋（DingTalk群號：11782920）加入MaxCompute開發人員社區釘群，聯絡MaxCompute支援人員團隊，將報錯地址加入白名單。

2. 加入白名單後，需在讀表前加如下參數。

   set odps.security.outbound.intranetlist=cn-hangzhou-intranet.dlf.aliyuncs.com:80;
   set odps.internet.access.list=cn-hangzhou-intranet.dlf.aliyuncs.com:80；