基于文件的外表配置

云平台普遍支持通用的对象存储系统，提供对文件的可扩展读写能力，是广泛使用的一类面向湖场景的数据存储平台，本文介绍基于文件的外部表配置方法。

安装扩展

安装 extension，仅需要安装一次，如果已经安装过，可以忽略。

CREATE EXTENSION file_fdw;

创建文件存储外部服务器

创建阿里云 OSS 的外部服务器

CREATE SERVER <server_name> FOREIGN DATA WRAPPER file_fdw
OPTIONS (
 REGION 'region-id',
 OSS_ENDPOINT 'endopint-url'
);

REGION 云存储服务的 REGION ID，具体的 ID 参考阿里云 OSS Region 和 Endpoint 对照表 (opens in a new tab)
OSS_ENDPOINT 云存储服务的 Endpoint，具体的 Endpoint 参考阿里云 OSS Region 和 Endpoint 对照表 (opens in a new tab)。如果 ProtonBase 与云存储部署在同一个 Region，建议使用内网 Endpoint。

-- 参考示例
CREATE SERVER oss_server FOREIGN DATA WRAPPER file_fdw
OPTIONS (
 REGION 'oss-cn-beijing',
 OSS_ENDPOINT 'https://oss-cn-beijing-internal.aliyuncs.com/' -- 同一区域建议使用 oss 内网地址
);

创建 AWS S3 的外部服务器

CREATE SERVER <server_name> FOREIGN DATA WRAPPER file_fdw
OPTIONS (
 REGION 'region-id'
);

REGION 云存储服务的 REGION ID，具体的 ID 参考AWS S3 Endpoint (opens in a new tab)。

-- 参考示例
CREATE SERVER s3_server FOREIGN DATA WRAPPER file_fdw
OPTIONS (
 REGION 'cn-north-1'
);

创建用户映射

为本地用户账号授予对应的对象存储的访问权限，通过 access_id 和 access_key 授权。

CREATE USER MAPPING FOR <local_user> SERVER oss_server
OPTIONS (
 ACCESS_ID 'access-id',
 ACCESS_KEY 'access-key'
);

创建外表

CREATE FOREIGN TABLE <table_name> (
    <column_name> <data_type>,
     ...
    )
SERVER <server_name>
OPTIONS (
   DIR '<path_to_oss>',
   FORMAT '<parquet|orc>'
);

OPTIONS 中的 DIR 指定外部对象存储的目录路径
OPTIONS 中的 FORMAT 指定文件格式，可以是 parquet，orc

-- create parquet table on OSS
CREATE FOREIGN TABLE f_t1(
  col1 INT,
  col2 TEXT  -- 手动定义 schema
)
SERVER oss_server
OPTIONS
(
 FORMAT 'parquet',  -- 或者 orc
 DIR 'oss://demo-hz/data/'
);
 
-- create parquet table on S3
CREATE FOREIGN TABLE f_t2(
  col1 INT,
  col2 TEXT  -- 手动定义 schema
)
SERVER s3_server
OPTIONS
(
 FORMAT 'parquet',  -- 或者 orc
 DIR 's3://demo-bj/data/'
);
 
-- 从外表导入到 ProtonBase 内表
INSERT INTO local_t1 SELECT * FROM f_t1;
 
-- 从 ProtonBase 内表导出到外表
INSERT INTO f_t1 SELECT * FROM local_t1;

批量创建外表（IMPORT FOREIGN SCHEMA）

file_fdw 扩展支持使用 IMPORT FOREIGN SCHEMA 命令批量创建外表，简化了对外部文件的管理。

IMPORT FOREIGN SCHEMA remote_schema
    [ { LIMIT TO | EXCEPT } ( table_name [, ...] ) ]
    FROM SERVER server_name
    INTO local_schema
    [ OPTIONS ( option 'value' [, ... ] ) ]

支持的参数说明

remote_schema：在 file_fdw 中，我们扩展了这个参数的语义，目前支持两个内置值：
- parquet：用于批量创建 Parquet 格式的外表
- orc：用于批量创建 ORC 格式的外表
LIMIT TO：限制只导入指定的表
EXCEPT：排除指定的表不导入
server_name：之前创建的外部服务器名称
local_schema：外表元数据保存在本地对应的 schema
OPTIONS：可选参数，用于指定额外的配置选项

使用示例

-- 批量创建 OSS 上的 Parquet 文件外表
IMPORT FOREIGN SCHEMA parquet
    FROM SERVER oss_server
    INTO public
    OPTIONS (
        DIR 'oss://demo-hz/data/'
    );
 
-- 批量创建 S3 上的 ORC 文件外表，只导入指定的表
IMPORT FOREIGN SCHEMA orc
    LIMIT TO (table1, table2)
    FROM SERVER s3_server
    INTO public
    OPTIONS (
        DIR 's3://demo-bj/data/'
    );

注意事项

目前仅支持 Parquet 和 ORC 两种文件格式
不支持分区表
不支持其他文件格式（如 CSV、JSON 等）