IMPORT FOREIGN SCHEMA语句的用法和使用限制 - 实时数仓Hologres

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

使用限制

使用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三层模型：需要导入的MaxCompute的项目名称和Schema名称，格式为`odps_project_name#odps_schema_name`。如果您MaxCompute的Project是三层模型模式，您仍使用两层模型的写法调用，则会报错，报错样例如下。 `failed to import foreign schema:Table not found - table_xxx`
table_name	需要导入的MaxCompute表名称。
server_name	MaxCompute表所在的外部服务器名称，默认为odps_server。您可以直接调用Hologres底层已创建的名为odps_server的外部表服务器。详细原理请参见Postgres FDW。
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');

HoloWeb可视化批量创建外部表

HoloWeb提供可视化批量创建外部表功能，无需写SQL命令就能创建外部表，步骤如下。

进入HoloWeb页面，详情请参见连接HoloWeb并执行查询。
在HoloWeb开发页面的顶部菜单栏，选择元数据管理 > MaxCompute加速，单击批量创建外部表。
您也可以在元数据管理界面的已登录实例列表。单击目标数据库，鼠标右击数据库下已创建的目标模式，选择批量创建外部表。

在批量创建外部表页面，配置各项参数。

类别	参数	描述
MaxCompute 数据源	项目名	MaxCompute的项目名称。
MaxCompute 数据源	Schema Name	MaxCompute的Schema名称，对于使用两层模型的MaxCompute项目，默认不展示；对于使用三层模型的MaxCompute项目，此处可下拉选择当前项目下有权限的所有Schema。
目标表位置	Schema Name	模式名称。您可以选择默认创建的public模式，也可以选择新建的模式名称。
高级选项	选择要直接加速的表	整库加速：批量创建所选项目或Schema下的所有表。部分加速：您可以通过搜索表名称或关键字，选择需要创建的表。说明部分加速最多支持显示200张表，超出部分将不显示，但是也会创建成功。例如，目标项目中共有203个名称中包含test的表，搜索test时，此处最多只会显示200个相关的表，但实际上203个表都会创建成功。
	表名冲突	忽略，继续创建其他表：创建表时，如果数据库中已存在当前创建的表名称，则忽略当前创建的表，继续创建其他表。更新，修改同名表：创建表时，如果数据库中已存在当前创建的表名称，则更新已有表的数据。报错，不再重复创建：创建表时，如果数据库中已存在当前创建的表名称，则发送报错，不再重复创建。
	数据类型不支持	报错，导入失败：如果创建表时存在不支持的数据类型，则产生报错，导入数据失败。忽略，跳过不支持字段：如果创建表时存在不支持的数据类型，则忽略不支持的字段，继续导入数据。

单击运行，批量创建外部表。