Convertir une table externe en table de catalogue Unity managée

Cette page explique comment convertir une table externe en table managée Unity Catalog dans Azure Databricks à l’aide de la ALTER TABLE ... SET MANAGED commande ou de l’Explorateur de catalogues.

SET MANAGED Aperçu

Permet SET MANAGED de convertir une table externe en table gérée par le catalogue Unity. Bien que vous puissiez également utiliser CREATE TABLE AS SELECT (CTAS) pour la conversion, Databricks recommande SET MANAGED les avantages suivants :

• Réduit le temps d’arrêt du lecteur et de l’enregistreur.
• Gère les écritures simultanées pendant la conversion.
• Conserve l’historique des tables de la base de données.
• Conserve les mêmes configurations de table, notamment le nom, les paramètres, les autorisations et les vues.
• Permet la réversion d’une table managée convertie en table externe.

Prerequisites

• Tous les lecteurs et les écrivains des tables externes doivent utiliser un accès basé sur le nom. Par exemple:

  SELECT * FROM catalog_name.schema_name.table_name;
  

  L’accès basé sur le chemin n’est pas pris en charge et peut échouer une fois la table convertie.

• Vous devez utiliser Databricks Runtime 17.0 ou une version supérieure ou un calcul sans serveur pour utiliser SET MANAGED ou UNSET MANAGED.

• Pour convertir des tables de catalogue Unity avec des lectures Iceberg (UniForm) déjà activées, vous devez utiliser Databricks Runtime 17.2 ou une version ultérieure ou un calcul sans serveur.

• Les lecteurs et les enregistreurs Azure Databricks doivent utiliser Databricks Runtime 15.4 LTS ou version ultérieure. Si vos lecteurs ou enregistreurs utilisent 14.3 LTS ou ci-dessous, consultez l’option alternative pour les lecteurs et les enregistreurs sur Databricks Runtime 14.3 LTS ou ci-dessous.

• La SET MANAGED commande échoue avec une DELTA_TRUNCATED_TRANSACTION_LOG erreur si votre table a minReaderVersion=2, minWriterVersion=7et tableFeatures={..., columnMapping}. Vous pouvez vérifier si votre table possède ces propriétés à l’aide DESCRIBE DETAILde .

• Les clients externes (non Databricks) doivent prendre en charge les opérations de lecture sur les tables gérées par Unity Catalog. Consultez Lire les tables avec des clients Delta.

  • Utilisez le tableau de bord Access Insights pour déterminer si les lecteurs et les enregistreurs qui accèdent à vos tables sont Databricks Runtime ou externes non-Databricks.

Convertir de l’externe en table managée

Explorateur de catalogues

Lorsque vous convertissez à l’aide de l’Explorateur de catalogues, l’accès basé sur le nom est utilisé automatiquement. Vous pouvez convertir une ou plusieurs tables externes dans un schéma à la fois.

1. Accédez à la table ou au schéma que vous souhaitez convertir dans l’Explorateur de catalogues.

2. Sous À propos de ce tableau (page détails du tableau) ou à propos de ce schéma (page détails du schéma), cliquez sur Explorer les optimisations.

3. Dans la boîte de dialogue Pourquoi migrer vers des tables gérées par le catalogue Unity ? Cliquez sur Continuer.

   

4. Sélectionnez les tables externes à convertir. Si vous avez ouvert la boîte de dialogue à partir d’une page de détails de tableau, votre table est pré-sélectionnée. Utilisez la barre de recherche pour rechercher des tables supplémentaires. Les tables managées ne sont pas sélectionnables.

   

5. Cliquez sur Créer un bloc-notes de conversion.

6. Si vous le souhaitez, entrez un nom pour le bloc-notes. Par défaut, le bloc-notes est enregistré dans votre dossier d’accueil. Cliquez sur Parcourir pour le sauvegarder à un autre emplacement.

   

7. Dans le notebook, passez en revue les bonnes pratiques et vérifiez que vous remplissez tous les prérequis.

8. Exécutez la SET cellule Requêtes MANAGÉes .

Une fois la cellule exécutée, le type de tableau s’affiche sous la forme MANAGED au lieu d’EXTERNAL dans l’Explorateur de catalogues. Actualisez la page si l’état ne se met pas à jour immédiatement.

SQL

En fonction de si les lectures Apache Iceberg (UniForm) sont activées pour votre table externe, exécutez l’une des commandes suivantes. Consultez Vérifier que les lectures Iceberg (UniForm) sont activées pour vérifier si votre table a activé les lectures Apache Iceberg (UniForm).

• Pour les tables externes du catalogue Unity sans capacité de lecture de Apache Iceberg (UniForm) activée :

  ALTER TABLE catalog.schema.my_external_table SET MANAGED;
  

  Après la conversion, vous pouvez activer les lectures Iceberg sur votre table managée sans problèmes de compatibilité.

• Pour les tables externes du catalogue Unity avec les lectures Apache Iceberg (UniForm) déjà activées :

  ALTER TABLE catalog.schema.my_external_table SET MANAGED TRUNCATE UNIFORM HISTORY;
  

  Inclure TRUNCATE UNIFORM HISTORY pour maintenir les performances et la compatibilité optimales des tables. TRUNCATE UNIFORM HISTORY tronque l’historique UniForm Iceberg uniquement et ne supprime pas l’historique Delta. Cette commande entraîne un court temps d’arrêt de lecture et d’écriture pour Iceberg après la troncation.

Si la commande est interrompue lors de la copie des données, redémarrez-la et continuez à partir de l’endroit où elle s’est arrêtée.

Après la conversion de table, vous devez :

• Redémarrez les travaux de streaming (lecture ou écriture) à l’aide de la table externe pour éviter la lecture ou l’écriture à l’emplacement précédent. Arrêtez le travail actuel et démarrez un nouveau travail avec la même configuration.
• Vérifiez que vos lecteurs et auteurs fonctionnent avec la table gérée.

L’optimisation prédictive est automatiquement activée après la conversion, sauf si vous l’avez désactivé manuellement. Consultez Vérifier si l’optimisation prédictive est activée.

Avec l’optimisation prédictive activée, Azure Databricks supprime automatiquement les données dans votre emplacement externe du catalogue Unity après 14 jours. Si l’optimisation prédictive est désactivée, exécutez VACUUM (nécessite Databricks Runtime 17.0 ou version ultérieure ou un calcul serverless) sur la table managée nouvellement convertie après 14 jours.

VACUUM my_converted_table

Vérifier la conversion

Explorateur de catalogues

Actualisez la page. Sous l’onglet Détails , sous À propos de ce tableau, le type de tableau s’affiche en tant que géré.

SQL

Exécutez la commande suivante pour vérifier que votre table externe a été convertie en table managée :

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Le tableau s’affiche sous la forme TypeMANAGED.

Option alternative pour les lecteurs et les auteurs sur Databricks Runtime 14.3 LTS ou version antérieure

Databricks recommande de mettre à jour tous les lecteurs et écrivains vers Databricks Runtime 15.4 LTS ou une version ultérieure pour tirer parti de SET MANAGED, y compris la possibilité de conserver l'historique des tables.

Vous pouvez toujours utiliser SET MANAGED si vous avez des lecteurs ou des enregistreurs sur Databricks Runtime 14.3 ou inférieur. Toutefois, après la conversion en table managée, vous ne pouvez revenir à des validations historiques que par version, et non par horodatage. Si vous rétablissez une table externe dans la fenêtre de 14 jours, la réactivation de l'accès temporel vers les commits historiques effectués avant que la conversion ne soit à nouveau possible est rendue possible.

Dans tous les cas, la restauration d'une table externe du Unity Catalog par horodatage ne fonctionne pas pour les commits effectués sur votre table gérée Unity Catalog convertie entre la conversion et la restauration.

L'écriture dans une table après la conversion avec Databricks Runtime 15.4 LTS ou antérieur nécessite l'abandon de la fonctionnalité inCommitTimestamp :

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Résolution des échecs de conversion

Cette section décrit les problèmes courants lors de la conversion de tables externes en tables gérées par le catalogue Unity et comment les résoudre.

Cohérence des versions de Databricks Runtime

Évitez d’exécuter ou de réessayer la conversion de la même table à l’aide de différentes versions de Databricks Runtime. Les métadonnées peuvent être sérialisées différemment entre les versions, ce qui provoque une VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED défaillance. Si la conversion échoue, réessayez toujours à l’aide de la même version de Databricks Runtime.

Arrêt du cluster pendant la conversion

Si votre cluster s’arrête pendant la conversion, la commande peut échouer avec DELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERROR. Réessayez la commande pour reprendre la conversion.

Table externe endommagée

Si la table externe est déjà endommagée (par exemple, l’état de la table n’est pas valide), la conversion peut échouer avec des erreurs telles que DELTA_TRUNCATED_TRANSACTION_LOG, DELTA_TXN_LOG_FAILED_INTEGRITYou DELTA_STATE_RECOVER_ERRORS. Avant de tenter la conversion, vérifiez que vous pouvez exécuter des opérations de base sur la table externe, telles que DESCRIBE DETAIL.

Échec de validation de fichier

La SET MANAGED commande valide que tous les fichiers de la dernière capture instantanée de la table sont copiés vers le nouvel emplacement de la table managée. Si des fichiers sont manquants, la commande échoue avec une DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED erreur.

Pour résoudre ce problème :

1. Vérifiez les journaux de votre pilote Spark pour identifier les fichiers qui n’ont pas pu être migrés.
2. Vérifiez que ces fichiers existent à l’emplacement de la table externe source et sont accessibles.
3. Réessayez la ALTER TABLE ... SET MANAGED commande.

Si le problème persiste, contactez le support Databricks.

Revenir à une table externe

Après avoir converti une table externe en table managée, vous pouvez revenir en arrière dans un délai de 14 jours.

Lorsque vous effectuez un retour arrière, les métadonnées de la table sont mises à jour pour pointer vers l'emplacement externe d'origine. Toutes les écritures effectuées à l’emplacement managé après la conversion sont conservées. Les validations effectuées à l’emplacement géré entre la conversion et la restauration restent consultables dans le temps par version, mais pas par horodatage.

Sept jours après la restauration, Azure Databricks supprime automatiquement les données dans l’emplacement managé.

Pour revenir à une table externe, exécutez la commande suivante :

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

Si la commande de restauration est interrompue, réexécutez-la pour réessayer.

Vous devez également redémarrer vos travaux de diffusion en continu après avoir restauré, tout comme lors d'une conversion.

Vérifier l'annulation

Exécutez la commande suivante pour vérifier que votre conversion a été restaurée :

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Le tableau s’affiche sous la forme TypeEXTERNAL.

Si vous affichez la table dans l’Explorateur de catalogues, actualisez la page. Dans l’onglet Détails , sous À propos de ce tableau, le type de tableau s’affiche sous EXTERNAL.

Temps d’arrêt et temps de copie des données

La SET MANAGED commande réduit ou élimine les temps d’arrêt par rapport à d’autres approches comme DEEP CLONE. Le processus de conversion utilise une approche en deux étapes :

1. Copie initiale des données (sans temps d’arrêt) : Les données de table et le journal des transactions Delta sont copiés à partir de l’emplacement externe vers l’emplacement managé. Les lecteurs et les rédacteurs continuent de fonctionner normalement sans impact sur les opérations en cours.
2. Basculez vers un emplacement managé (temps d’arrêt rapide) : Les validations effectuées à l’emplacement externe lors de la première étape sont déplacées vers l’emplacement managé, et les métadonnées de la table sont mises à jour pour inscrire le nouvel emplacement managé. Pendant cette étape, toutes les écritures de données dans l’emplacement externe sont temporairement bloquées, ce qui entraîne une interruption de service pour le processus d’écriture. Les lecteurs sur Databricks Runtime 16.1 ou version ultérieure n’ont pas de temps d’arrêt ; les lecteurs sur Databricks Runtime 15.4 peuvent rencontrer des temps d’arrêt.

Temps d’arrêt estimé :

Les estimations supposent un débit de 0,5 à 2 Go par minute et par cœur d'unité centrale (UC).

Limitations connues

• Clients de diffusion en continu : Vous devez redémarrer tous les travaux de streaming après la conversion.

• Contraintes d'historique des tables après restauration : L'historique des tables pour les validations réalisées après la conversion mais avant la restauration peut être consulté par version mais pas par horodatage.

• Limitations du partage delta : La SET MANAGED commande n’est pas entièrement compatible avec le partage Delta. Le partage Delta fonctionne comme prévu, mais le partage de Databricks à Databricks ne met pas automatiquement à jour l'emplacement géré de la table du destinataire. Le destinataire continue de lire à partir de l’ancien emplacement jusqu’à ce que la table soit repartagée. Pour partager à nouveau la table :

  ALTER SHARE <share_name> REMOVE TABLE <table_name>;
  ALTER SHARE <share_name> ADD TABLE <table_name> AS <table_share_name> WITH HISTORY;
  

• Plusieurs régions cloud : Si l’emplacement managé par défaut de votre metastore, catalogue ou schéma du catalogue Unity se trouve dans une région cloud différente de l’emplacement de stockage de la table externe, vous risquez d’entraîner des coûts de transfert de données interrégions supplémentaires. Le fournisseur de cloud impose ces frais en dehors du contrôle Databricks.

  Pour vérifier les emplacements de votre schéma, catalogue et metastore :

  DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;
  
  DESC CATALOG EXTENDED <catalog_name>;
  
  SELECT * FROM system.information_schema.metastores;