Partager via

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

Cette page décrit l’utilisation de la ALTER TABLE ... SET MANAGED commande pour convertir une table externe en table managée Unity Catalog dans Azure Databricks.

Vue d’ensemble de SET MANAGED

Utilisez la SET MANAGED fonctionnalité pour convertir une table externe en table managée Unity Catalog dans Azure Databricks. SET MANAGED offre les avantages suivants :

  • Réduction du temps d'inactivité du lecteur et de l'auteur.
  • Gestion des écritures simultanées pendant la conversion.
  • Conservation de l’historique des tables.
  • Conservez les mêmes configurations de table, notamment le même nom, les mêmes paramètres, autorisations et vues.
  • Possibilité de restaurer une table managée convertie en table externe.

Prerequisites

Pour utiliser la fonctionnalité de conversion de table, vous devez remplir les conditions préalables suivantes :

  • 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 ultérieur ou un calcul serverless, 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 pour utiliser TRUNCATE UNIFORM HISTORY.

  • 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.

Important

Pour éviter les conflits, annulez les travaux de commande existants OPTIMIZE (clustering liquide, compactage, ZORDER) fonctionnant sur votre table et ne planifiez aucun travail pendant que vous convertissez vos tables externes en tables managées.

Convertir de l’externe en table managée

Important

La SET MANAGED commande est disponible dans Databricks Runtime 17.0 ou ultérieur et dans le mode de calcul serverless.

La TRUNCATE UNIFORM HISTORY commande est disponible dans Databricks Runtime 17.2 ou supérieur et le calcul sans serveur.

Exécutez l’une des commandes suivantes pour convertir votre table externe catalogue Unity en table gérée par le catalogue Unity.

  • 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 Iceberg (UniForm) déjà activées :

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

    Dans ce cas, incluez TRUNCATE UNIFORM HISTORY pour maintenir des performances et une 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 votre commande est interrompue lors de la copie des données, vous pouvez la redémarrer et continuer à partir de l’endroit où vous vous êtes arrêté.

Warning

Databricks recommande de ne pas exécuter plusieurs SET MANAGED commandes simultanément sur la même table, ce qui peut entraîner un état de table incohérent.

Après la conversion de table, vous devez :

  • Redémarrez les travaux de streaming (lecture ou écriture) à l’aide de la table externe.
  • Assurez-vous que vos lecteurs et écrivains travaillent avec la table gérée.

L’optimisation prédictive est automatiquement activée, sauf si vous l’avez désactivée 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, vous pouvez exécuter 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

Note

Dans certains cas, les données de votre emplacement externe du catalogue Unity ne peuvent pas être supprimées après 14 jours, même avec l’optimisation prédictive activée. Par exemple, si votre table managée Catalogue Unity n’est pas fréquemment utilisée ou est très petite, la suppression automatique peut ne pas se produire. Dans ce cas, après 14 jours, exécutez VACUUM manuellement (nécessite Databricks Runtime 17.0 ou version ultérieure ou un calcul serverless) sur la table managée nouvellement convertie pour supprimer les anciennes données.

Azure Databricks supprime uniquement les données dans l’emplacement externe. Le journal des transactions Delta et la référence à la table dans le catalogue Unity sont conservés.

Vérifier la conversion

Vous pouvez vérifier que votre table externe a été convertie en table managée :

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Vérifiez la sortie de cette commande pour vérifier que la table a été convertie. La table Type doit s’afficher sous la forme MANAGED.

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

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

Databricks vous recommande de mettre à niveau tous les lecteurs et enregistreurs vers Databricks Runtime 15.4 LTS ou version ultérieure pour tirer parti de la SET MANAGED commande, notamment la possibilité de conserver l’historique des tables.

Vous pouvez toujours utiliser la SET MANAGED commande si vous avez des lecteurs ou des enregistreurs avec Databricks Runtime 14.3 ou inférieur. Toutefois, après la conversion en table managée, vous ne pouvez pas parcourir le temps vers des validations historiques par horodatage. Vous ne pouvez faire cela que par version. Si vous revenez à une table externe dans la fenêtre de 14 jours, le voyage dans le temps vers les validations historiques effectuées avant la conversion sera à nouveau possible.

Dans tous les cas (quelle que soit la version DBR), le retour à l'UC externe par timestamp ne fonctionne pas pour les validations effectuées dans votre table UC gérée que vous avez convertie, entre la fin de la conversion et avant votre tentative de retour.

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 DBR

É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 non 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.

Revenir à une table externe

Important

La UNSET MANAGED commande est disponible dans Databricks Runtime 17.0 ou ultérieur et le calcul sans serveur.

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

Si vous annulez, les validations effectuées à l’emplacement externe entre la conversion et l’annulation sont consultables dans le passé par version, mais pas par horodatage. Sept jours après l'annulation, les données de la localisation gérée seront supprimées.

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, vous pouvez la réexécuter pour réessayer, de manière similaire à la commande SET MANAGED.

Vérifier la restauration

Vous pouvez confirmer que votre conversion a été annulée :

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Vérifiez la sortie de cette commande pour vérifier que la table a été restaurée. La table Type doit s’afficher sous la forme EXTERNAL.

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

Vous devez également redémarrer vos travaux de diffusion en continu après la restauration vers une table externe, comme lors de la conversion.

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

Une interruption peut se produire lorsque les lecteurs ou les écrivains accèdent à la table pendant la conversion. Toutefois, par rapport à la commande « DEEP CLONE », la commande SET MANAGED réduit ou élimine les temps d’arrêt pour les lecteurs et les écrivains. Les utilisateurs de Databricks Runtime 16.1 ou version ultérieure ne rencontrent aucune interruption. Les lecteurs et les auteurs ne sont pas impactés lors de la première étape, lorsque les données de la table et le journal delta sont copiés.

Lors de la deuxième étape, les écritures dans l’emplacement externe du catalogue Unity sont bloquées et les validations effectuées sur l’emplacement externe lors de la première copie de données seront déplacées. Cette deuxième étape de copie de données entraînera un temps d’arrêt pour les éditeurs et les lecteurs dans Databricks Runtime 15.4 LTS ou une version inférieure.

Après cela, les lecteurs et les auteurs sont déplacés vers l’emplacement géré du Unity Catalog, et le nouvel emplacement de table gérée est inscrit dans Unity Catalog. Les lecteurs utilisant Databricks Runtime 16.1 ou version ultérieure ne connaîtront aucun temps d'arrêt.

Le temps d’arrêt estimé est le suivant :

Taille de la table Taille de cluster recommandée Durée de la copie des données Temps d’arrêt du lecteur et du graveur
100 Go ou moins 32 cœurs / "DBSQL" petit ~6 minutes ou moins ~1 à 2 minutes ou moins
1 To 64 cœurs / Médium DBSQL ~30 min ~1-2min
10 To 256 cœurs / DBSQL x-large ~1,5 heures ~1-5min

Les estimations supposent un débit de 0,5 à 2 Go par minute et par cœur de CPU.

Note

Les temps d’arrêt peuvent varier. Les performances de la conversion dépendent de facteurs tels que la taille du fichier, le nombre de fichiers et le nombre de validations.

Limitations connues

La conversion de tables externes en tables managées présente les limitations suivantes :

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

  • Contraintes d’historique de table après restauration : pour les lecteurs/enregistreurs dans Databricks Runtime 15.4 LTS ou versions ultérieures, l’historique des tables pour les validations effectuées après la conversion, mais avant la restauration sera modifiable par version, mais pas par horodatage.

  • Limitations du partage Delta : la SET MANAGED commande n’est pas entièrement compatible avec le partage Delta. Bien que l’ouverture du partage Delta fonctionne comme prévu, le partage Databricks à Databricks ne met pas automatiquement à jour l’emplacement managé 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 Unity Catalog se trouve dans une région cloud différente de l’emplacement de stockage de la table externe en cours de conversion, vous pouvez 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, vous pouvez utiliser les commandes suivantes :

    DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;

DESC CATALOG EXTENDED <catalog_name>;

SELECT * FROM system.information_schema.metastores;
  • Last updated on