Filesystem Catalog Iceberg外部项目

更新时间:
复制 MD 格式

MaxCompute推出外部项目功能,通过映射存储在阿里云对象存储(OSS)上的Apache Iceberg目录(Iceberg Hadoop Catalog),构建与标准Iceberg文件系统层级一致的外部项目。访问权限基于用户RAMRole对OSS Bucket的授权,支持对Iceberg湖格式的元数据和数据进行读写。该方式实现数据目录级整体映射,需用户确保文件系统层级合规,由用户自主管理权限与湖格式文件存储,适用于权限可控、具备自主维护能力的流批一体场景,使数仓与Spark、Flink、Hive等开源引擎无缝共享同一份Iceberg表数据。

重要

删除外部项目的操作属于物理删除,过程中会清理一些历史信息(但不会删除源端数据),因此删除操作耗时较长,请耐心等待操作完成。

注意事项

对MaxCompute管理的Iceberg表执行以下操作会导致数据丢失或不可读:

禁止操作

后果

正确做法

通过非MaxCompute的写接口(例如storage api 或sql等)在OSS上更新或修改管理目录下的Iceberg表数据

在外部修改或替换 Iceberg数据,会导致表无法通过一致性检查,并且变得不可读从而查询失败。

仅通过MaxCompute SQL修改数据

向OSS的Iceberg 表管理路径上传数据或添加新文件

上传的文件会被后台服务作为孤儿文件回收

不在管理路径下上传数据

基于同一OSS路径多次创建MaxCompute管理的Iceberg表

各表的垃圾回收进程会互相删除对方的文件

每个表使用不同的OSS路径,若在同一目录多次建表,需使用干净路径重新建表并copy数据到新表,避免数据丢失。

在具有父子目录关系的OSS路径上创建不同的MaxCompute管理的Iceberg表

每个表的后台垃圾回收进程都会将另一个表的文件视为脏数据或者孤儿文件,并将其删除,从而导致数据丢失。

避免在存在父子关系的路径上分别建表,每个MaxCompute管理的Iceberg 表使用不同的路径。

适用范围

权限说明

  • 管控面权限

    • 即通过MaxCompute控制台操作时需要校验的权限,主要发生在创建MaxCompute的外部项目,绑定OSS目录的过程中。

    • 这部分权限由RAM访问控制管理,需要由主账号登录RAM控制台配置相关操作并管理RAM用户的权限。

  • 数据面权限

    • 即登录创建好的外部项目后,读写OSS上的Iceberg表时需要校验的权限,主要发生在创建、维护或使用被绑定的OSS目录中的Schema、Table以及其他资源的过程中,该权限通常在MaxCompute的SQL中执行。

    • 这部分权限集成在RAM Role中,由RAM访问控制管理,使用RAM Role身份的权限实现对OSS上的Iceberg湖格式数据的读写操作,配置方法请参见OSS/OTS的RAM普通角色授权。

操作步骤

步骤一:创建外部项目

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

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

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

    参数

    是否必填

    描述

    项目类型

    必填

    默认为外部项目。

    地域

    必填

    默认为当前地域,此处无法修改。

    项目名称(全网唯一)

    必填

    名称全局唯一,创建后不可修改。

    字母开头,包含字母、数字以及下划线(_),长度应在3到28个字符之间。

    MaxCompute外部数据源类型

    选填

    选择Filesystem Catalog Iceberg。

    RoleARN

    必填

    RAM角色的ARN信息。此角色需要包含能够同时访问OSS服务的权限。

    1. 登录RAM控制台。

    2. 在左侧导航栏选择身份管理 > 角色。

    3. 在基础信息区域,可以获取ARN信息。

    示例:acs:ram::124****:role/aliyunodpsdefaultrole。

    存储类型

    必填

    OSS。

    Endpoint

    必填

    自动生成,杭州地域为:oss-cn-hangzhou-internal.aliyuncs.com。

    Bucket 数据目录

    必填

    选择完整的OSS Bucket和至Catalog级别的文件系统目录,若OSS已存在Iceberg数据,则需要指定目录到Schema的上一级。示例中oss://iceberg-fs/iceberg-test/。

    计算资源付费类型

    必填

    包年包月或按量付费。

    默认Quota

    必填

    选择已有Quota.

    描述

    选填

    自定义项目描述。

步骤二:使用SQL访问数据源系统

重要

由于外部项目和数据源之间是映射关系,所以删除外部项目并不会删除任何数据;与普通外部表不同,如果在外部项目中执行DROP TABLE 或 DROP SCHEMA 操作,该请求会发送到对端服务,因此会真正删除对应表或数据库中的数据,请谨慎执行DROP操作。

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

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

    -- 打开session级别支持schema语法开关。
    SET odps.namespace.schema=true;
    SHOW schemas;
  3. 在外部项目中列出schema下的表。

    -- 打开session级别支持schema语法开关。
    SET odps.namespace.schema=true;
    -- schema_name为外部项目中展示出来的Schema名称。
    USE SCHEMA <schema_name>; 
    SHOW tables;
  4. 在外部项目中新建schema。

    -- 打开session级别支持schema语法开关。
    SET odps.namespace.schema=true;
    CREATE schema <schema_name>;

使用示例

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

Iceberg建表语法,可参考MaxCompute管理的Iceberg表(beta)的建表语法结构。因为Filesystem Catalog Iceberg外部项目已经映射OSS目录,所以在外部项目中建表时无需指定location参数,只需要指定表字段和分区字段即可。

-- 创建表。
SET odps.namespace.schema=true;
USE SCHEMA <schema_name>;
CREATE TABLE IF NOT EXISTS test_iceberg_partition_table (
    id BIGINT,
    name STRING,
    age INT,
    salary DOUBLE,
    is_active BOOLEAN,
    created_at TIMESTAMP,
    dt STRING,
    region STRING
) COMMENT 'Test partitioned table for Iceberg filesystem external project'
PARTITIONED BY (dt, region);

-- 插入数据。
SET odps.namespace.schema=true;
USE SCHEMA <schema_name>;
INSERT INTO test_iceberg_partition_table VALUES 
    (1, '张三', 28, 8000.0, TRUE, TIMESTAMP '2026-10-09 12:00:00', '2026-10-09', 'shanghai'),
    (2, '李四', 32, 12000.0, TRUE, TIMESTAMP '2026-10-09 13:00:00', '2026-10-09', 'shanghai'),
    (3, '王五', 25, 6500.0, FALSE, TIMESTAMP '2026-10-09 14:00:00', '2026-10-09', 'beijing'),
    (4, '赵六', 35, 15000.0, TRUE, TIMESTAMP '2026-10-09 15:00:00', '2026-10-10', 'shanghai'),
    (5, '孙七', 29, 9000.0, TRUE, TIMESTAMP '2026-10-09 16:00:00', '2026-10-10', 'beijing');

-- 查表。
SET odps.namespace.schema=true;
USE SCHEMA <schema_name>;
SELECT * FROM test_iceberg_partition_table;

-- 返回结果如下。
+------------+------+------+------------+-----------+------------+----+--------+
| id         | name | age  | salary     | is_active | created_at | dt | region |
+------------+------+------+------------+-----------+------------+----+--------+
| 1          | 张三 | 28   | 8000.0     | true      | 2026-10-09 12:00:00 | 2026-10-09 | shanghai |
| 2          | 李四 | 32   | 12000.0    | true      | 2026-10-09 13:00:00 | 2026-10-09 | shanghai |
| 3          | 王五 | 25   | 6500.0     | false     | 2026-10-09 14:00:00 | 2026-10-09 | beijing |
| 4          | 赵六 | 35   | 15000.0    | true      | 2026-10-09 15:00:00 | 2026-10-10 | shanghai |
| 5          | 孙七 | 29   | 9000.0     | true      | 2026-10-09 16:00:00 | 2026-10-10 | beijing |
+------------+------+------+------------+-----------+------------+----+--------+