Migrate external project 1.0 to Data Lakehouse Solution 2.0 - MaxCompute

Évolutions apportées par Data Lakehouse Solution 2.0

Data Lakehouse Solution 1.0 prend en charge deux modèles de fédération via des projets externes :

Data Lake Formation (DLF) + Object Storage Service (OSS) : le projet externe stocke directement les informations de connexion. MaxCompute se connecte aux métadonnées DLF et aux données OSS grâce aux propriétés du projet externe.
Hive Metastore Service (HMS) + Hadoop Distributed File System (HDFS) : un objet Foreign Server conserve les informations de connexion. MaxCompute utilise cette source de données externe pour lire les métadonnées Hive et les données associées.

Dans les deux cas, le niveau projet correspond à une base de données dans DLF ou Hive, et les tables sont stockées directement dans le projet (Project.Table).

Data Lakehouse Solution 2.0 introduit une structure Project.Schema.Table et remplace le modèle de connexion par projet par un Foreign Server unifié ainsi qu'un schéma externe.

	Data Lakehouse Solution 1.0	Data Lakehouse Solution 2.0
Source de données externe	Les informations de connexion varient selon les scénarios de fédération. Aucune abstraction partagée n'existe pour le contrôle d'accès au niveau du locataire.	Un Foreign Server unique sépare les autorisations au niveau du locataire de celles au niveau des données et simplifie le partage.
Modèle de projet	Les tables sont stockées directement dans les projets (`Project.Table`). Chaque base de données d'une source de données nécessite un projet externe distinct.	Les projets prennent en charge une couche de schéma (`Project.Schema.Table`). Un seul projet peut mapper plusieurs bases de données ou sources de données.
Calcul	Le projet externe dépend d'un projet d'entrepôt de données distinct pour exécuter les tâches, ce qui complexifie l'autorisation inter-projets.	Les schémas externes utilisent les ressources de calcul du projet d'entrepôt de données auquel ils appartiennent.

Choisir une stratégie de migration

Avant d'activer les modes de schéma, déterminez quel projet hébergera le schéma externe.

Scénario	Stratégie recommandée
L'activation du mode de schéma pour le projet `p1` (qui exécute les tâches existantes) est acceptable	Cas d'utilisation 1 : Créer le schéma externe dans le même projet
L'activation du mode de schéma pour `p1` perturberait trop de tâches existantes	Cas d'utilisation 2 : Créer le schéma externe dans un projet distinct

Important

L'activation du mode de schéma pour les métadonnées au niveau du projet est irréversible. Une fois activé, la structure du projet passe de Project.Table à Project.Schema.Table et ne peut pas être annulée. Cela peut interrompre les tâches existantes qui référencent des tables avec la syntaxe p.t si le mode de schéma pour la syntaxe SQL est également activé. Testez au niveau de la session avant d'appliquer les modifications au niveau du locataire.

Modes de schéma

MaxCompute propose deux commutateurs de schéma fonctionnant conjointement :

Mode de schéma pour les métadonnées au niveau du projet : modifie la structure du projet en Project.Schema.Table et crée un schéma Default intégré. Toutes les tables internes existantes sont déplacées vers le schéma Default. Le schéma Default ne peut pas être supprimé. Irréversible une fois activé.
Mode de schéma pour la syntaxe SQL : contrôle l'analyse des références de table dans les instructions SQL (par exemple, si p.t est interprété comme project.table ou schema.table). Peut être activé au niveau de la session ou du locataire.

Activer le mode de schéma pour les métadonnées au niveau du projet

Connectez-vous à la console MaxCompute et sélectionnez une région dans le coin supérieur gauche.console MaxCompute
Dans le volet de navigation de gauche, choisissez Manage Configurations > Projects.
Sur la page Projects, localisez le projet cible et cliquez sur Enable Schema dans la colonne Actions.

Après l'activation, un schéma Default est créé automatiquement. Toutes les tables internes du projet appartiennent à ce schéma. Pour accéder aux schémas personnalisés, activez également le mode de schéma pour la syntaxe SQL.

Activer le mode de schéma pour la syntaxe SQL

Le mode de schéma pour la syntaxe SQL peut être activé à deux niveaux :

Niveau de la session — Affecte uniquement la session actuelle. Prédomine sur les paramètres au niveau du locataire. Utilisez cette option pour tester la compatibilité avant d'appliquer une modification plus large. Vous pouvez activer ou désactiver le mode de schéma pour la syntaxe SQL au niveau de la session.

SET odps.namespace.schema= true | false;

Niveau du locataire — S'applique à tous les projets et à toutes les tâches sous le locataire. Les nouveaux projets prennent en charge le mode de schéma pour les métadonnées au niveau du projet par défaut. Ne peut pas être désactivé après activation.

Pour activer au niveau du locataire :

Connectez-vous à la console MaxCompute et sélectionnez une région dans le coin supérieur gauche.console MaxCompute
Dans le volet de navigation de gauche, choisissez Manage Configurations > Tenants.
Sur la page Tenants, cliquez sur l'onglet Tenant Property.
- Si aucun projet n'existe sous le locataire actuel : activez Tenant-level Schema Syntax.
- Si des projets existent sous le locataire actuel : ne modifiez pas ce paramètre.

Pour plus d'informations, consultez Propriétés du locataire.

Référence de compatibilité

Des erreurs de compatibilité surviennent lorsque les deux modes de schéma présentent des états différents. Les tableaux ci-dessous illustrent l'impact de chaque combinaison sur les tâches existantes et nouvelles, en prenant comme référence un projet d'entrepôt de données p avec la table t.

Mode de métadonnées désactivé, mode de syntaxe SQL activé

Type de tâche	Expression SQL	Interprétée comme	Compatible ?	Action
Existante	`FROM t`	`current_project(p).table(t)`	Oui	Aucune
Existante	`FROM p.t`	`current_project.schema(p).table(t)` — le schéma `p` n'existe pas	Non	Remplacer par `FROM p.default.t`
Nouvelle	`p.default.t`	`project(p).schema(default).table(t)`	Oui	Aucune
Nouvelle	`default.t`	`current_project.schema(default).table(t)`	Oui	Aucune
Nouvelle	`t`	`current_project.current_schema.table(t)`	Oui	Aucune
Nouvelle	`p.s.t`	`project(p).schema(s).table(t)` — erreur si le schéma `s` n'existe pas	Conditionnel	Vérifier que le schéma `s` existe

Mode de métadonnées activé, mode de syntaxe SQL désactivé

Type de tâche	Expression SQL	Interprétée comme	Compatible ?	Action
Existante	`FROM t`	`current_project(p).schema(default).table(t)`	Oui	Aucune
Existante	`FROM p.t`	`project(p).schema(default).table(t)` — le schéma Default est ajouté automatiquement	Oui	Aucune
Nouvelle	`p.t`	`project(p).schema(default).table(t)`	Oui	Aucune
Nouvelle	`t`	`project.schema(default).table(t)`	Oui	Aucune
Remarque	—	Les schémas personnalisés ne sont pas accessibles dans cet état. `USE SCHEMA <schema_name>` n'est pas pris en charge.	—	Activez le mode de syntaxe SQL pour accéder aux schémas personnalisés

Mode de métadonnées activé, mode de syntaxe SQL activé

Type de tâche	Expression SQL	Interprétée comme	Compatible ?	Action
Existante	`FROM t`	`current_project(p).schema(default).table(t)`	Oui	Aucune
Existante	`FROM p.t`	`current_project.schema(p).table(t)` — le schéma `p` n'existe pas	Non	Remplacer par `FROM p.default.t`
Nouvelle	Toute	Suit les règles complètes de la syntaxe `Project.Schema.Table`	Oui	Aucune

Guide de migration

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

Un projet MaxCompute servant d'entrepôt de données (pour exécuter les tâches de calcul)
Un accès à la console MaxCompute avec des autorisations de gestion de projet
Avoir consulté la référence de compatibilité et identifié les tâches existantes nécessitant des mises à jour SQL

Pour obtenir des détails sur la création d'un Foreign Server et d'un schéma externe, consultez le Guide d'utilisation de Data Lakehouse Solution 2.0. Pour les concepts et opérations liés aux schémas, voir Schéma et Opérations sur les schémas.

Cas d'utilisation 1 : Créer un schéma externe dans le projet qui exécute les tâches existantes

Suivez cette procédure si l'activation du mode de schéma pour le projet de tâches existantes (p1) est acceptable.

Scénario : Le projet p1 exécute les tâches existantes. Les requêtes ciblent external_project(e).table(t). Après la migration, les mêmes données sont accessibles via project(p1).external_schema(e).table(t).

Étape 1 : Activez le mode de schéma pour les métadonnées au niveau du projet sur p1.

Après l'activation, le schéma Default est créé automatiquement. Toutes les tables internes existantes dans p1 appartiennent à p1.default.

Étape 2 : Créez un schéma externe dans p1 portant le même nom que le projet externe (e).

Définissez le nom du schéma externe pour qu'il corresponde au nom du projet externe. Cela permet aux requêtes existantes qui référencent e de se résoudre correctement après l'activation du mode de schéma pour la syntaxe SQL.

Étape 3 : Activez le mode de schéma pour la syntaxe SQL au niveau de la session et testez les tâches existantes.

Après l'activation du mode de schéma pour la syntaxe SQL :

SELECT * FROM e.t; — e.t est interprété comme external_schema(e).table(t). La requête s'exécute dans p1 sans modification.
SELECT * FROM e.t1 JOIN p1.t2; — p1.t2 est désormais interprété comme schema(p1).table(t2), et non project(p1).table(t2). Mettez à jour cette instruction en SELECT * FROM e.t1 JOIN p1.default.t2;.

Étape 4 : Après avoir vérifié que les tâches s'exécutent correctement, activez le mode de schéma pour la syntaxe SQL au niveau du locataire (facultatif).

Cas d'utilisation 2 : Créer un schéma externe dans un projet distinct

Suivez cette procédure si l'activation du mode de schéma pour p1 interromprait trop de tâches existantes, ou si vous souhaitez laisser p1 inchangé pendant la migration.

Scénario : Le projet p1 exécute les tâches existantes. Les requêtes ciblent external_project(e).table(t). Vous créez (ou sélectionnez) un projet distinct p2 pour héberger le schéma externe. Après la migration, les données fédérées sont accessibles via project(p2).external_schema(e).table(t).

Étape 1 : Activez le mode de schéma pour les métadonnées au niveau du projet sur p2.

p1 n'est pas affecté. Les tâches existantes dans p1 continuent de s'exécuter normalement.

Étape 2 : Créez un schéma externe dans p2 portant le même nom que le projet externe (e).

Étape 3 : Activez le mode de schéma pour la syntaxe SQL et mettez à jour les instructions SQL dans p1.

Après l'activation du mode de schéma pour la syntaxe SQL :

SELECT * FROM e.t; dans p1 — remplacez par SELECT * FROM p2.e.t;, car e se résout désormais en un schéma à l'intérieur de p1, et non en tant que projet externe.
Exécution de SELECT * FROM e.t; directement dans p2 — aucune modification requise.
Jointure inter-projets dans p1 : SELECT * FROM e.t1 JOIN p1.t2; — remplacez par SELECT * FROM p2.e.t1 JOIN p1.default.t2;.

Étapes suivantes

Guide d'utilisation de Data Lakehouse Solution 2.0 — créer des Foreign Servers et des schémas externes pour les sources DLF+OSS et HMS+HDFS
Schéma — concepts et structure des schémas dans MaxCompute
Opérations sur les schémas — créer, gérer et supprimer des schémas
Propriétés du locataire — configurer les paramètres de syntaxe de schéma au niveau du locataire