FileSystem Catalog外部项目

步骤一：为RAM用户授权

如果操作用户是RAM用户，请确保已绑定如下权限策略。添加权限参考为为RAM用户授权。

• AliyunMaxComputeFullAccess：用来完成创建外部数据源和外部项目操作。

步骤二：创建Filesystem Catalog外部数据源

1. 开通OSS，并创建bucket存储了Paimon数据，详情请参见控制台快速入门。

2. 登录MaxCompute控制台，在左上角选择地域。

3. 在左侧导航栏，选择管理配置 > 外部数据源 。

4. 在外部数据源页面，单击创建外部数据源。

5. 在弹出的新增外部数据源对话框，根据界面提示配置相关参数。参数说明如下：

   参数	是否必填	说明
   外部数据源类型	必填	选择Filesystem Catalog。
   外部数据源名称	必填	可自定义命名。命名规则如下： 以字母开头，且只能包含小写字母、下划线和数字。 不能超过128个字符。 例如external_fs。
   外部数据源描述	选填	根据需要填写。
   地域	必填	默认为当前地域。
   认证和鉴权	必填	默认为阿里云RAM角色。
   RoleARN	必填	RAM角色的ARN信息。此角色需要包含能够访问OSS服务的权限。 登录RAM控制台。 在左侧导航栏选择身份管理 > 角色。 在基础信息区域，可以获取ARN信息。 示例：acs:ram::124****:role/aliyunodpsdefaultrole。
   存储类型	必填	OSS OSS-HDFS
   Endpoint	必填	自动生成，杭州地域为：oss-cn-hangzhou-internal.aliyuncs.com。
   外部数据源补充属性	选填	特殊声明的外部数据源补充属性。指定后，使用此外部数据源的任务可以按照参数定义的行为访问源系统。 说明 支持的具体参数请关注后续官网文档更新说明，具体参数将随产品能力演进逐步放开。

6. 单击确认，完成外部数据源的创建。

7. 在外部数据源页面，单击目标数据源对应的操作的详情，可查看数据源详细信息。

步骤三：创建外部项目

1. 登录MaxCompute控制台，在左上角选择地域。

2. 在左侧导航栏，选择管理配置 > 项目管理。

3. 在外部项目页签，单击新建项目。

4. 在弹出的新增项目对话框，根据界面提示文案配置项目信息，单击确认完成项目创建。

   参数	是否必填	说明
   项目类型	必填	默认为外部项目。
   地域	必填	默认为当前地域，此处无法修改。
   项目名称（全网唯一）	必填	字母开头，包含字母、数字及下划线（_），长度在3-28个字符。
   MaxCompute外部数据源类型	选填	选择Filesystem Catalog。
   MaxCompute外部数据源	选填	选择已有：会出现已经创建过的外部数据源。 新建外部数据源：即可新建并使用新的外部数据源。
   MaxCompute外部数据源名称	必填	选择已有：在下拉列表中选择已经创建好的外部数据源名称。 新建外部数据源：则会使用新建的外部数据源名称。
   Bucket 数据目录	必填	选择完整的OSS Bucket和至Catalog级别的文件系统目录。本示例中oss://paimon-fs/paimon-test/。
   表格式	必填	默认为Paimon。
   计算资源付费类型	必填	包年包月或按量付费。
   默认Quota	必填	选择已有Quota.
   描述	选填	自定义项目描述。

步骤四：使用SQL访问数据源系统

1. 选择连接工具登录外部项目。

2. 列出外部项目中的schema，默认只会列出存储Paimon表的DB路径。

   -- 打开session级别支持schema语法开关。
   SET odps.namespace.schema=true;
   SHOW schemas;
   
   -- 返回结果如下。
   ID = 20250922********wbh2u7
   default
   
   
   OK

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

   -- schema_name为外部项目中展示出来的Schema名称。
   USE SCHEMA <schema_name>; 
   SHOW tables;

4. 在外部项目中新建schema。

   CREATE schema <schema_name>;
   
   -- 示例如下。
   CREATE schema schema_test;

5. 使用新建的schema。

   use schema <schema_name>;
   
   -- 示例如下。
   use schema schema_test;

6. 在schema中新建表并插入数据。

   • 命令格式：

     -- 新建表。
     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>

   • 使用示例：

     CREATE TABLE new_table(id INT,name STRING);
     
     INSERT INTO new_table VALUES (101,'张三'),(102,'李四');
     
     -- 查询表new_table。
     SELECT * FROM new_table;
     
     -- 返回结果如下。
     +------------+------------+
     | id         | name       | 
     +------------+------------+
     | 101        | 张三        | 
     | 102        | 李四        | 
     +------------+------------+

参考示例

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下生成表的详情：