全部產品
Search

搜尋本產品

    Realtime Compute for Apache Flink：管理Paimon Catalog

    文件中心

    Realtime Compute for Apache Flink：管理Paimon Catalog

    更新時間：Aug 14, 2026

    Paimon Catalog 實現了 Flink 對 資料湖構建（DLF） 資料的直接存取。本文介紹 Catalog 的建立與管理，以及資料庫與表的操作流程。

    注意事項

    • 引擎版本要求

      • 基礎功能：建立 Paimon Catalog 和表，需使用Realtime Compute引擎 VVR 8.0.5 及以上版本。

      • DLF 整合：若將中繼資料存放區類型設定為 DLF，需使用 VVR 11.1 及以上版本。

      • OSS-HDFS 支援：使用 OSS-HDFS 作為 Paimon Filesystem Catalog 的儲存時，需使用 VVR 11.8 及以上版本。

    • OSS 儲存配置

      • 儲存類型：Paimon 資料檔案與中繼資料檔案儲存體於 OSS。必須使用標準儲存類型的 Bucket。詳情請參見儲存類型。

      • 部署建議：建議建立一個位於同一地區的獨立 Bucket。避免複用系統預設 Bucket，以防止資料混淆及誤操作。

    • 許可權管理
      配置 Catalog 時使用的 AccessKey，必須擁有目標 OSS Bucket 或 DLF 目錄的讀寫權限。

    • 格式相容性

      Paimon Catalog 專用於管理 Paimon 格式資料。它不支援訪問 Lance、Iceberg 等其他資料湖格式的表。

    • 中繼資料同步
      通過 SQL 陳述式建立或刪除 Catalog、資料庫及表後，控制台視圖可能不會立即變更。請點擊頁面上的重新整理image按鈕以擷取最新中繼資料狀態。

    • Paimon對應版本

      Paimon社區版本

      Realtime ComputeFlink版引擎版本（VVR ）

      1.3.1

      11.5、11.6、11.7、11.8

      1.3

      11.4

      1.2

      11.2、11.3

      1.1

      11.1

      1.0

      8.0.11

    建立Paimon Catalog

    建立Paimon Filesystem Catalog

    UI方式

    1. 進入資料管理頁面。

      1. 登入Realtime Compute管理主控台，單擊目標工作空間操作列下的控制台。

      2. 單擊資料管理。

    2. 單擊建立Catalog，選擇Apache Paimon，單擊下一步。

    3. 填寫參數配置資訊。

    SQL方式

    在資料查詢文本編輯地區，輸入以下命令。

    CREATE CATALOG `my-catalog` WITH (
  'type' = 'paimon',
  'metastore' = 'filesystem',
  'warehouse' = '<warehouse>',
  'fs.oss.endpoint' = '<fs.oss.endpoint>',
  'fs.oss.accessKeyId' = '<fs.oss.accessKeyId>',
  'fs.oss.accessKeySecret' = '<fs.oss.accessKeySecret>'
);

    配置項參數說明如下。

    • 通用

      配置項

      說明

      是否必填

      備忘

      my-catalog

      Paimon Catalog名稱。

      是

      請填寫為自訂的英文名。

      type

      Catalog類型。

      是

      固定值為paimon。

      metastore

      中繼資料存放區類型。

      是

      參數取值如下：

      • filesystem：配置為Paimon Filesystem Catalog類型時填寫。

      • dlf：配置為Paimon DLF Catalog類型時填寫。

    • OSS

      配置項

      說明

      是否必填

      備忘

      warehouse

      OSS服務中所指定的數倉目錄。

      是

      格式為oss://<bucket>/<object>。其中：

      • bucket：表示您建立的OSS Bucket名稱。

      • object：表示您存放資料的路徑。

      請在OSS管理主控台上查看您的bucket和object名稱。

      fs.oss.endpoint

      OSS服務的串連地址。

      是

      • 如果Flink與DLF位於同一地區，則使用VPC網路Endpoint，否則使用公網Endpoint。

      • 當warehouse指定的OSS Bucket與Flink工作空間不在同一地區，或使用其它帳號下的OSS Bucket時需要填寫。

      擷取方法請參見地區和Endpoint和建立AccessKey。

      fs.oss.accessKeyId

      擁有讀寫OSS許可權的阿里雲帳號或RAM帳號的Accesskey ID。

      是

      fs.oss.accessKeySecret

      擁有讀寫OSS許可權的阿里雲帳號或RAM帳號的Accesskey secret。

      是

    • OSS-HDFS（VVR 11.8及以上版本）

      使用 OSS-HDFS 作為 Paimon Filesystem Catalog 儲存時，SQL 樣本如下：

      CREATE CATALOG `my_catalog` WITH (
  'type' = 'paimon',
  'metastore' = 'filesystem',
  'warehouse' = 'dls://<bucket>.<dls-endpoint>/<warehouse-path>',
  'fs.oss.endpoint' = '<dls-endpoint>',
  'fs.oss.accessKeyId' = '<access-key-id>',
  'fs.oss.accessKeySecret' = '<access-key-secret>',
  'fs.dls.client.mode.enabled' = 'false',
  'fs.dls.data.endpoint' = '<oss-data-endpoint>'
);

      配置項參數說明如下。

      配置項

      說明

      是否必填

      備忘

      warehouse

      OSS-HDFS服務中所指定的數倉目錄。

      是

      格式為dls://<bucket>.<dls-endpoint>/<warehouse-path>。其中<dls-endpoint>同fs.oss.endpoint。

      fs.oss.endpoint

      OSS-HDFS服務的串連地址。

      是

      在OSS管理主控台目標 Bucket 的"概覽 > 訪問連接埠"地區，查看 HDFS 服務 Endpoint。

      fs.oss.accessKeyId

      擁有讀寫OSS-HDFS許可權的阿里雲帳號或RAM帳號的AccessKey ID。

      是

      —

      fs.oss.accessKeySecret

      AccessKey ID對應的AccessKey Secret。

      是

      —

      fs.dls.client.mode.enabled

      是否啟用DLS Client Mode。

      是

      固定設定為false。

      fs.dls.data.endpoint

      DLS協議訪問底層OSS資料時使用的資料Endpoint。

      是

      在OSS管理主控台目標 Bucket 的"概覽 > 訪問連接埠"地區，查看 OSS 內網 Endpoint。也可查詢地區和Endpoint文檔。

    建立Paimon DLF Catalog

    DLF

    1. 在DLF上建立Paimon Catalog，詳情請參見快速使用DLF。

      1. DLF Catalog需要和Flink工作空間位於同一地區，否則無法在後續流程中完成關聯。

    2. 在Realtime Compute開發控制台上，建立Paimon Catalog。

      說明

      這裡僅用於建立與DLF Catalog的映射串連，建立或刪除Catalog僅影響映射關係，不會對DLF中的實際資料產生影響。

      1. 登入Realtime Compute控制台。

      2. 單擊Flink全託管工作空間列表中的工作空間名稱，進入對應的工作空間。

      3. 可以通過UI或者SQL方式來添加Catalog。

        UI方式

        1. 在左側導覽列，單擊資料管理。

        2. 在Catalog列表頁，單擊建立Catalog。

        3. 選擇Apache Paimon，單擊下一步。

        4. metastore 選擇 dlf，catalog name 選擇需要關聯版本的DLF Catalog，單擊確定，即可建立Catalog。

        SQL命令

        在資料查詢文本編輯地區，輸入以下SQL並執行，即可建立Catalog。

        CREATE CATALOG `flink_catalog_name` 
WITH (
  'type' = 'paimon',
  'metastore' = 'rest',
  'token.provider' = 'dlf',
  'uri' = 'http://cn-hangzhou-vpc.dlf.aliyuncs.com',
  'warehouse' = 'dlf_test'
);

        參數說明如下：

        參數

        描述

        是否必填

        樣本

        type

        Catalog類型，固定為paimon。

        是

        paimon

        metastore

        metastore類型，固定為rest。

        是

        rest

        token.provider

        Token提供方，固定為dlf。

        是

        dlf

        uri

        訪問DLF Rest Catalog Server的URI，格式為http://[region-id]-vpc.dlf.aliyuncs.com。詳見地區與服務存取點中的Region ID。

        是

        http://cn-hangzhou-vpc.dlf.aliyuncs.com

        warehouse

        DLF Catalog名稱。

        是

        dlf_test

    DLF-Legacy

    1. 在DLF上建立Paimon Catalog，詳情請參見快速入門。

      1. DLF Catalog需要和Flink工作空間位於同一地區，否則無法在後續流程中完成關聯。

    2. 在Realtime Compute開發控制台上，建立Paimon Catalog。

      UI方式

      1. 進入資料管理頁面。

        1. 登入Realtime Compute控制台，單擊目標工作空間操作列下的控制台。

        2. 單擊資料管理。

      2. 單擊建立Catalog，選擇Apache Paimon，單擊下一步。

      3. metastore 選擇 dlf，catalog name 選擇需要關聯的V1.0版本的DLF Catalog，然後填寫參數配置（所需參數與SQL方式一致）。

      SQL命令

      在資料查詢文本編輯地區，輸入以下命令。

      CREATE CATALOG `my-catalog` WITH (
  'type' = 'paimon',
  'metastore' = 'dlf',
  'warehouse' = '<warehouse>',
  'dlf.catalog.id' = '<dlf.catalog.id>',
  'dlf.catalog.accessKeyId' = '<dlf.catalog.accessKeyId>',
  'dlf.catalog.accessKeySecret' = '<dlf.catalog.accessKeySecret>',
  'dlf.catalog.endpoint' = '<dlf.catalog.endpoint>',
  'dlf.catalog.region' = '<dlf.catalog.region>',
  'fs.oss.endpoint' = '<fs.oss.endpoint>',
  'fs.oss.accessKeyId' = '<fs.oss.accessKeyId>',
  'fs.oss.accessKeySecret' = '<fs.oss.accessKeySecret>'
);

      配置項參數說明如下。

      • 通用

        配置項

        說明

        是否必填

        備忘

        my-catalog

        Paimon Catalog名稱。

        是

        請填寫為自訂的英文名。

        type

        Catalog類型。

        是

        固定值為paimon。

        metastore

        中繼資料存放區類型。

        是

        固定值為dlf。

      • OSS

        配置項

        說明

        是否必填

        備忘

        warehouse

        OSS服務中所指定的數倉目錄。

        是

        格式為oss://<bucket>/<object>。其中：

        • bucket：表示您建立的OSS Bucket名稱。

        • object：表示您存放資料的路徑。

        請在OSS管理主控台上查看您的bucket和object名稱。

        fs.oss.endpoint

        OSS服務的串連地址。

        是

        • 如果Flink與DLF位於同一地區，則使用VPC網路Endpoint，否則使用公網Endpoint。

        • 如果需要將Paimon表格儲存體在OSS-HDFS中，則fs.oss.endpoint的值為cn-<region>.oss-dls.aliyuncs.com，例如cn-hangzhou.oss-dls.aliyuncs.com。

        fs.oss.accessKeyId

        擁有讀寫OSS許可權的阿里雲帳號或RAM帳號的Accesskey ID。

        是

        擷取方法請參見地區和Endpoint和建立AccessKey。

        fs.oss.accessKeySecret

        擁有讀寫OSS許可權的阿里雲帳號或RAM帳號的Accesskey secret。

        是

      • DLF

        配置項

        說明

        是否必填

        備忘

        dlf.catalog.id

        DLF資料目錄ID。

        是

        請在資料湖構建控制台上查看資料目錄對應的ID。

        dlf.catalog.accessKeyId

        訪問DLF服務所需的Access Key ID。

        是

        擷取方法請參見建立AccessKey。

        dlf.catalog.accessKeySecret

        訪問DLF服務所需的Access Key Secret。

        是

        擷取方法請參見建立AccessKey。

        dlf.catalog.endpoint

        DLF服務的Endpoint。

        是

        詳情請參見已開通的地區和訪問網域名稱。

        說明

        如果Flink與DLF位於同一地區，則使用VPC網路Endpoint，否則使用公網Endpoint。

        dlf.catalog.region

        DLF所在地區。

        是

        詳情請參見已開通的地區和訪問網域名稱。

        說明

        請和dlf.catalog.endpoint選擇的地區保持一致

    管理Paimon資料庫

    在資料查詢文本編輯地區輸入如下命令，選中代碼後單擊運行。

    • 建立資料庫

      建立Paimon Catalog後，Catalog中會自動建立名為default的資料庫。

      --my-catalog需要替換為您建立的Paimon Catalog名稱。
USE CATALOG `my-catalog`;

--my_db需要替換為自訂的database英文名稱。
CREATE DATABASE `my_db`;

    • 刪除資料庫

      重要

      無法刪除DLF類型Catalog下的default資料庫，允許刪除Filesystem類型Catalog下的default資料庫。

      --my-catalog需要替換為您建立的Paimon Catalog名稱。
USE CATALOG `my-catalog`;

--my_db需要替換為您想要刪除的資料庫名稱。
DROP DATABASE `my_db`; --只需要刪除內部沒有任何錶的資料庫。
DROP DATABASE `my_db` CASCADE; --刪除資料庫且同時刪除資料庫下的所有表。

    管理Paimon表

    建立表

    說明

    Paimon Catalog配置完成後，您就可以在作業中引用Paimon Catalog表資訊，作為源表、結果表和維表時，無需聲明表的DDL。在SQL命令方式中，您可以直接使用Paimon Catalog表名稱的完整格式${Paimon-catalog-name}.${Paimon-db-name}.${Paimon-table-name}，也可以用use catalog ${Paimon-catalog-name}和use ${Paimon-db-name}語句先聲明Catalog名稱和資料庫名稱，後面的SQL裡唯寫表名稱${Paimon-table-name}即可。

    • 通過CREATE TABLE語句建立表

      在資料查詢文本編輯地區輸入如下命令後，選中代碼後單擊運行。

      在名為my-catalog的Catalog下的my_db的資料庫中，建立一張分區表，其中分區鍵為dt，主鍵為dt、shop_id和user_id，分桶數固定為4。程式碼範例如下。

      --my-catalog需要替換為您建立的Paimon Catalog名稱。
--my_db需要替換為您想要使用的database名稱。
--my_tbl也可以改為自訂的英文名稱。
CREATE TABLE `my-catalog`.`my_db`.`my_tbl` (
  dt STRING,
  shop_id BIGINT,
  user_id BIGINT,
  num_orders INT,
  total_amount INT,
  PRIMARY KEY (dt, shop_id, user_id) NOT ENFORCED
) PARTITIONED BY (dt) WITH (
  'bucket' = '4'
);

      關於Paimon表的更多參數與使用方式，詳情請參見流式資料湖倉Paimon和Paimon主鍵表和Append Only表。

    • 通過CREATE TABLE AS（CTAS）語句（退役中）或CREATE DATABASE AS（CDAS）語句建立表

      CTAS與CDAS語句不僅會自動同步資料，還會同步表結構的變更。通過CTAS與CDAS語句，您可以方便地將MySQL、Kafka等資料來源中的表同步至Paimon Catalog中。

      由於CTAS與CDAS語句涉及資料的同步，您需要部署並啟動作業，具體操作請參見作業開發地圖和作業啟動。

      說明

      • 通過CTAS與CDAS語句建立的Paimon表時，暫不支援設定'bucket' = '-1'以使用動態分桶的Paimon主鍵表或Paimon Append Only表（非主鍵表）。

      • CTAS與CDAS支援在WITH參數中設定物理表屬性，在建立目標表時，同時在表上設定對應的屬性。當作業啟動時，這些參數將被應用到需要同步的下遊表中。具體支援的表屬性參數詳情，請參見流式資料湖倉Paimon。

      • 建立指定表並同步表中的資料

        例如，根據mysql.tpcds.web_sales表的結構，自動建立`my-catalog`.`my_db`.`web_sales`Paimon表，並同步表中的資料。另外指定Paimon表的分桶數為4，以及使用input變更資料產生機制。

        CREATE TABLE IF NOT EXISTS `<catalog name>`.`<db name>`.`<table name>`
WITH (
  'bucket' = '4',
  'changelog-producer' = 'input'
) AS TABLE mysql.tpcds.web_sales;

      • 建立整個資料庫的表

        例如，根據mysql.tpcds資料庫中每張表的結構，自動在`my-catalog`.`my_db`中建立對應的Paimon表，並同步表中的資料。另外指定Paimon表使用input變更資料產生機制。

        CREATE DATABASE IF NOT EXISTS `<catalog name>`.`<db name>`
WITH (
  'changelog-producer' = 'input'
) AS DATABASE mysql.tpcds INCLUDING ALL TABLES;

      • 同步列類型變更

        通過CTAS/CDAS語句建立的Paimon表不僅支援列的增加，還支援特定的列類型變更。您可以根據需要，選擇是否使用欄位類型寬容模式。

        • 預設情況下

          通過CTAS/CDAS語句建立的Paimon表的列類型與源表的列類型一致，並支援以下列類型變更：

          • 支援整數類型TINYINT、SMALLINT、INT、BIGINT變更為精度相同或更高的整數類型，其中TINYINT精度最低，BIGINT精度最高。

          • 支援浮點類型FLOAT、DOUBLE變更為精度相同或更高的浮點類型，其中FLOAT精度最低，DOUBLE精度最高。

          • 支援字串類型CHAR、VARCHAR和STRING變更為精度相同或更高的字串類型。

        • 使用欄位類型寬容模式

          在CTAS與CDAS情境中，Paimon Catalog支援在WITH參數中設定'enableTypeNormalization' = 'true'後，將使用欄位類型寬容模式。在上遊發生資料類型修改事件時，只要所修改的類型與原類型的歸一化類型相同，都視作修改成功。目前類型歸一化規則如下：

          • TINYINT、SMALLINT、INT和BIGINT歸一化為BIGINT。

          • FLOAT和DOUBLE歸一化為DOUBLE。

          • CHAR、VARCHAR和STRING歸一化為STRING。

          • 其他資料類型不進行歸一化。

          例如：

          • SMALLINT修改為INT，兩者的歸一化類型都是BIGINT，視為修改成功，作業正常運行。

          • 從FLOAT改為BIGINT，兩者的歸一化類型分別為DOUBLE和BIGINT，屬於不相容的情況，會拋出異常。

          Paimon表中儲存的資料類型將統一為歸一化後的類型。例如，MySQL中類型分別為SMALLINT和INT的兩列，在Paimon表中均儲存為BIGINT類型。

    修改表結構

    在資料查詢文本編輯地區輸入如下命令，選中代碼後單擊運行。

    操作

    程式碼範例

    添加或修改表參數

    將表的write-buffer-size參數值修改為256 MB，並將write-buffer-spillable參數值修改為true。

    ALTER TABLE my_table SET (
  'write-buffer-size' = '256 MB',
  'write-buffer-spillable' = 'true'
);

    臨時修改表參數

    您可以通過在表名後添加SQL Hint的方式，在寫入表時臨時修改表參數。臨時修改的表參數僅對當前SQL作業生效。

    • 在寫入my_table表時，臨時將write-buffer-size設為256 MB，將write-buffer-spillable設為true。

      INSERT INTO my_table /*+ OPTIONS('write-buffer-size' = '256 MB', 'write-buffer-spillable' = 'true') */
SELECT ...;

    • 在消費my_table表時，臨時將scan.mode設為latest，將scan.parallelism設為10。

      SELECT * FROM t /*+ OPTIONS('scan.mode' = 'latest', 'scan.parallelism' = '10') */;

    重新命名表

    將表的名稱從my_table修改為my_table_new。

    ALTER TABLE my_table RENAME TO my_table_new;
    重要

    由於Object Storage Service的重新命名操作不具有原子性，因此如果您使用Object Storage Service儲存Paimon表檔案，請謹慎進行重新命名表操作。推薦您使用OSS-HDFS服務以保證檔案操作的原子性。

    添加新列

    • 將類型為INT的c1列和類型為STRING的c2列添加在my_table表的末尾。

      ALTER TABLE my_table ADD (c1 INT, c2 STRING);

    • 將類型為STRING的c2列添加在my_table表中c1的列後面。

      ALTER TABLE my_table ADD c2 STRING AFTER c1;

    • 將類型為INT的c1列添加在my_table表的開頭。

      ALTER TABLE my_table ADD c1 INT FIRST;

    重新命名列

    將my_table表中名稱為c0的列重新命名為c1。

    ALTER TABLE my_table RENAME c0 TO c1;

    刪除列

    將my_table表中c1和c2兩列刪除。

    ALTER TABLE my_table DROP (c1, c2);

    刪除分區

    將my_table表中dt=20240108,hh=06與dt=20240109,hh=07兩個分區刪除。

    ALTER TABLE my_table DROP PARTITION (`dt` = '20240108', `hh` = '08'), PARTITION (`dt` = '20240109', `hh` = '07');

    修改列注釋

    將my_table表中buy_count列的注釋改為this is buy count。

    ALTER TABLE my_table MODIFY buy_count BIGINT COMMENT 'this is buy count';

    修改列順序

    • 將my_table表中名稱為col_a，類型為DOUBLE的列移動到開頭。

      ALTER TABLE my_table MODIFY col_a DOUBLE FIRST;

    • 將my_table表中名稱為col_a，類型為DOUBLE的列移動到col_b列的後面。

      ALTER TABLE my_table MODIFY col_a DOUBLE AFTER col_b;

    修改列類型

    將my_table表中的col_a列類型改為DOUBLE。

    ALTER TABLE my_table MODIFY col_a DOUBLE;

    Paimon表支援的列類型修改情況請參見下表。下圖中的〇表示支援類型轉換，空儲存格代表不支援類型轉換。

    image

    刪除表

    在資料查詢文本編輯地區輸入如下命令，選中代碼後單擊運行。

    --my-catalog需要替換為您建立的Paimon Catalog名稱。
--my_db需要替換為您想要使用的database名稱。
--my_tbl需要替換為您建立的Paimon Catalog表名稱。
DROP TABLE `my-catalog`.`my_db`.`my_tbl`;

    出現The following statement has been executed successfully!的提示資訊說明Paimon表刪除成功。

    查看或刪除Paimon Catalog

    1. 在Realtime Compute管理主控台，單擊目標工作空間操作列的控制台。

    2. 在資料管理頁面，查看或刪除Paimon Catalog。

      • 查看：在Catalog列表頁面，查看Catalog名稱和類型。如果您需要查看Catalog下的資料庫和表，請單擊查看。

      • 刪除：在Catalog列表頁面，單擊目標Catalog名稱對應操作列的刪除。

        說明

        刪除Paimon Catalog只會刪除Flink專案空間資料管理中的記錄，不會影響Paimon表的資料檔案。刪除Catalog後，只需要重新執行建立Paimon Catalog，即可重新使用Catalog中的Paimon表。

        您也可以在資料查詢文本編輯地區輸入DROP CATALOG <catalog name>;，選中代碼後單擊運行。

    相關文檔

    • 建立Paimon表後，您可以從Paimon表中消費資料或向Paimon表中寫入資料，詳情請參見Paimon表資料寫入和消費。

    • 如果內建的Catalog無法滿足您的業務需求，您可以使用自訂Catalog，詳情請參見管理自訂Catalog。

    • 不同情境下Paimon主鍵表和Append Scalable表的常用最佳化，詳情請參見Paimon效能最佳化。