Utilisation et limites de l'instruction IMPORT FOREIGN SCHEMA - Hologres

IMPORT FOREIGN SCHEMA crée des tables distantes en masse en mappant automatiquement les schémas de table d'une source de données distante vers Hologres. Utilisez cette instruction au lieu de créer chaque table distante manuellement.

Deux sources de données sont prises en charge :

Tables MaxCompute : importez des tables distantes à partir des modèles à deux ou trois couches de MaxCompute.
Tables Paimon dans Data Lake Formation (DLF) : importez des tables distantes à partir des tables Paimon dans DLF.

Syntaxe

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

Paramètres

Paramètre	Description
`remote_schema`	Nom du schéma distant à importer. Pour le modèle à deux couches de MaxCompute : nom du projet. Pour le modèle à trois couches de MaxCompute : `odps_project_name#odps_schema_name`. Pour DLF : nom de la base de données de métadonnées.
`table_name`	Noms des tables à importer. À utiliser avec `LIMIT TO` pour spécifier un sous-ensemble, ou avec `EXCEPT` pour exclure des tables spécifiques.
`server_name`	Nom du serveur distant. Pour MaxCompute : utilisez `odps_server`, précréé dans Hologres. Pour DLF : utilisez le nom du serveur distant associé à votre catalogue Paimon.
`local_schema`	Nom du schéma Hologres dans lequel les tables distantes sont créées, par exemple `public`.
`options`	Contrôle le comportement lors de l'importation. Consultez la section Options ci-dessous.

Options

Option	Valeurs	Description
`if_table_exist`	`error` (par défaut), `ignore`, `update`	Action à entreprendre lorsqu'une table distante portant le même nom existe déjà. `error` arrête la création de cette table. `ignore` ignore la table et poursuit l'importation des autres. `update` réimporte et écrase la table existante.
`if_unsupported_type`	`skip` (par défaut), `error`	Action à entreprendre lorsqu'une table contient des types de données non pris en charge par Hologres. `skip` ignore les tables concernées et consigne celles qui ont été ignorées. `error` arrête l'importation et signale les tables contenant des types non pris en charge.
`prefix`	Toute chaîne de caractères	Préfixe ajouté aux noms des tables distantes Hologres créées. Nécessite Hologres V1.1.26 ou une version ultérieure.
`suffix`	Toute chaîne de caractères	Suffixe ajouté aux noms des tables distantes Hologres créées. Nécessite Hologres V1.1.26 ou une version ultérieure.

Notes d'utilisation

Incluez toujours la clause LIMIT TO pour spécifier les tables à importer. Si vous l'omettez, Hologres crée des tables distantes pour toutes les tables du projet MaxCompute cible.
Hologres prend uniquement en charge la création de tables distantes MaxCompute. Les noms des tables distantes doivent correspondre aux noms des tables MaxCompute associées.
Les options prefix et suffix nécessitent Hologres V1.1.26 ou une version ultérieure. Pour les versions antérieures, consultez la rubrique Erreurs courantes lors de la préparation d'une mise à niveau ou contactez le support via le support en ligne.
Le modèle à trois couches de MaxCompute nécessite Hologres V1.3 ou une version ultérieure. L'utilisation de la syntaxe à deux couches sur un modèle à trois couches renvoie une erreur semblable à celle-ci :
```
failed to import foreign schema:Table not found - table_xxx
```
Pour les versions antérieures, consultez la rubrique Erreurs courantes lors de la préparation d'une mise à niveau.
Pour plus d'informations sur le modèle à trois couches de MaxCompute, consultez la rubrique Opérations sur les schémas.

Exemples

Modèle à deux couches de MaxCompute

Les exemples suivants importent des tables distantes depuis le projet MaxCompute public_data vers Hologres.

Importer une table et la mettre à jour si elle existe :

IMPORT FOREIGN SCHEMA public_data LIMIT TO
  (customer)
  FROM SERVER odps_server INTO public
  OPTIONS (if_table_exist 'update');

Importer plusieurs tables en masse :

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

Importer dans un schéma personnalisé :

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;

Renvoyer une erreur si une table existe déjà :

IMPORT FOREIGN SCHEMA public_data LIMIT TO (
  customer,
  customer_address
)
FROM SERVER odps_server INTO public
OPTIONS (if_table_exist 'error');

Ignorer les tables qui existent déjà :

IMPORT FOREIGN SCHEMA public_data LIMIT TO (
  customer,
  customer_address
)
FROM SERVER odps_server INTO public
OPTIONS (if_table_exist 'ignore');

Modèle à trois couches de MaxCompute

Le modèle à trois couches ajoute une couche de schéma entre le projet et la table. Spécifiez remote_schema sous la forme odps_project_name#odps_schema_name.

L'exemple suivant importe la table odps_region_10g depuis le schéma tpch_10g du projet MaxCompute odps_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');

Source de données DLF

Pour une source de données DLF, spécifiez le nom de la base de données de métadonnées comme remote_schema et le serveur distant de votre catalogue Paimon comme server_name.

L'exemple suivant importe la table customer depuis la base de données de métadonnées DLF github_events. Pour les étapes de configuration, consultez la rubrique Accéder à un catalogue Paimon basé sur DLF.

IMPORT FOREIGN SCHEMA github_events LIMIT TO (
  customer
)
FROM SERVER paimon_server INTO public
OPTIONS (if_table_exist 'update');

Étapes suivantes

Postgres FDW — comprendre les principes du wrapper de données étrangères utilisés par Hologres
Accéder à un catalogue Paimon basé sur DLF — configurer le serveur distant DLF avant d'importer les tables DLF
Opérations sur les schémas — comprendre le fonctionnement du modèle à trois couches de MaxCompute