IMPORT FOREIGN SCHEMA语句的用法和使用限制-实时数仓 Hologres(Hologres)-阿里云帮助中心

IMPORT FOREIGN SCHEMA语句用于批量创建外部表。本文为您介绍IMPORT FOREIGN SCHEMA语句的用法和使用限制。

功能详情

IMPORT FOREIGN SCHEMA 是 Hologres 提供的批量创建外部表的功能，可将远程数据源中的表结构自动映射为 Hologres 外部表，无需逐一手动建表。目前，该功能支持以下两类数据源：

MaxCompute 表：支持从 MaxCompute 两层模型或三层模型中批量导入外部表。
DLF 中 Paimon 表：支持从阿里云 DLF 中的 Paimon 表批量创建 Hologres 外部表。

使用限制

使用IMPORT FOREIGN SCHEMA语句时，建议您添加LIMIT TO限制，并使用括号将需要添加限制的表名称括起来。如果不添加该限制，系统则将目标MaxCompute工作空间中的所有表批量创建至Hologres中。
仅Hologres V1.1.26及以上版本支持对使用IMPORT FOREIGN SCHEMA创建的外部表名称增加前缀和后缀，如果您的实例是V1.1.26以下版本，请您使用常见升级准备失败报错或加入Hologres钉钉交流群反馈，详情请参见如何获取更多的在线支持？。
仅Hologres V1.3及以上版本支持MaxCompute的三层模型模式（即在原先的Project和Table之间增加了一层Schema的概念），更多描述请参见Schema操作。如果您想在Hologres中使用MaxCompute的三层模型的项目创建外部表，且您的Hologres版本较低，请您使用常见升级准备失败报错或加入Hologres钉钉交流群反馈，详情请参见如何获取更多的在线支持？。

命令格式

在Hologres中批量创建外部表的命令格式如下。

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

参数说明

参数说明如下表所示。

参数	描述
remote_schema	MaxCompute 两层模型：需要导入的MaxCompute表所在的项目名称。三层模型：需要导入的MaxCompute的项目名称和Schema名称，格式为`odps_project_name#odps_schema_name`。如果您MaxCompute的Project是三层模型模式，您仍使用两层模型的写法调用，则会报错，报错样例如下。 `failed to import foreign schema:Table not found - table_xxx` DLF：对应DLF中创建的元数据库名称。
table_name	MaxCompute：需要导入的MaxCompute表的名称。 DLF：需要导入的DLF表名称。
server_name	MaxCompute表所在的外部服务器名称，默认为odps_server。您可以直接调用Hologres底层已创建的名为odps_server的外部表服务器，详细原理请参见Postgres FDW。 DLF：DLF表所在的外部服务器名称，详细操作请参见基于DLF访问Paimon Catalog。
local_schema	Hologres外部表所在的Schema名（如public）。
options	Hologres支持如下四个option： if_table_exist：表示导入时已经存在该表。取值如下： error：默认值，表示已有同名外部表，不再重复创建。 ignore：忽略该同名表，跳过该表的导入，使导入的表不重复。 update：更新并重新导入该表。 if_unsupported_type：表示导入的外部表中存在Hologres不支持的数据类型。取值如下： error：报错，导入失败，并提示哪些表存在不支持的类型。 skip：默认值，表示跳过导入的存在不支持类型的表，并提示哪些表被跳过。 prefix：表示导入时生成的Hologres外部表的前缀，自Hologres V1.1.26版本新增。 suffix：表示导入时生成的Hologres外部表的后缀，自Hologres V1.1.26版本新增。

说明

Hologres仅支持创建MaxCompute外部表。新建的外部表名称需要同MaxCompute表的名称一致。

使用示例

MaxCompute两层模型。

示例选取MaxCompute公共数据集public_data中的表，在Hologres中批量创建外部表。您可以参照使用公开数据集描述，登录并查询数据集。

示例1：为public Schema新建一张外部表，若表存在则更新表。

IMPORT FOREIGN SCHEMA public_data LIMIT TO
(customer) 
  FROM server odps_server INTO PUBLIC options(if_table_exist 'update');

示例2：为public Schema批量新建外部表。

 IMPORT FOREIGN SCHEMA public_data LIMIT TO(
  customer,
  customer_address,
  customer_demographics,
  inventory,item,
  date_dim,
  warehouse) 
  FROM server odps_server INTO PUBLIC options(if_table_exist 'update');

示例3：新建一个testdemo Schema并批量新建外部表。

CREATE schema testdemo;

IMPORT FOREIGN SCHEMA public_data LIMIT TO(
  customer,
  customer_address,
  customer_demographics,
  inventory,item,
  date_dim,
  warehouse) 
  FROM server odps_server INTO testdemo options(if_table_exist 'update');
  
SET search_path TO testdemo;

示例4：在public Schema批量创建外部表，已有外表则报错。

IMPORT FOREIGN SCHEMA public_data LIMIT to
(customer,
  customer_address) 
  FROM server odps_server INTO PUBLIC options(if_table_exist 'error');

示例5：在public Schema中批量创建外部表，已有外表则跳过该外部表。

IMPORT FOREIGN SCHEMA public_data LIMIT to
(customer,
  customer_address) 
  FROM server odps_server INTO PUBLIC options(if_table_exist 'ignore');

MaxCompute三层模型。

基于MaxComputeodps_hologres项目的tpch_10g这个Schema中的odps_region_10g表创建Hologres中的外部表。

IMPORT FOREIGN SCHEMA "odps_hologres#tpch_10g" LIMIT to
(
    odps_region_10g
)
FROM SERVER odps_server INTO public OPTIONS(if_table_exist 'error',if_unsupported_type 'error');

DLF数据源。
DLF 数据源通过指定数据源名称（如github_events）直接创建Hologres外部表。
- 示例：为public Schema新建一张外部表，若表存在则更新表。详细操作请参见基于DLF访问Paimon Catalog。
```
IMPORT FOREIGN SCHEMA github_events
limit to (customer) 
FROM SERVER paimon_server into public
options (if_table_exist 'update');
```