IMPORTFOREIGNSCHEMA語句的用法和使用限制 - 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以下版本，請您使用常見升級準備失敗報錯或加入HologresDingTalk交流群反饋，詳情請參見如何擷取更多的線上支援？。
僅Hologres V1.3及以上版本支援MaxCompute的三層模型模式（即在原先的Project和Table之間增加了一層Schema的概念），更多描述請參見Schema操作。如果您想在Hologres中使用MaxCompute的三層模型的專案建立外部表格，且您的Hologres版本較低，請您使用常見升級準備失敗報錯或加入HologresDingTalk交流群反饋，詳情請參見如何擷取更多的線上支援？。

命令格式

在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');
```