Een externe tabel converteren naar een beheerde Unity Catalog-tabel

Op deze pagina wordt beschreven hoe u een externe tabel converteert naar een door Unity Catalog beheerde tabel in Azure Databricks met behulp van de ALTER TABLE ... SET MANAGED opdracht of Catalog Explorer.

SET MANAGED Overzicht

Hiermee SET MANAGED converteert u een externe tabel naar een beheerde unity-catalogustabel. Hoewel u CREATE TABLE AS SELECT (CTAS) ook kunt gebruiken voor conversie, raadt Databricks SET MANAGED aan vanwege de volgende voordelen:

• Minimaliseert de downtime van lezer en schrijver.
• Verwerkt gelijktijdige schrijfbewerkingen tijdens de conversie.
• Behoudt de tabelgeschiedenis.
• Behoudt dezelfde tabelconfiguraties, waaronder naam, instellingen, machtigingen en weergaven.
• Ondersteunt het terugdraaien van een geconverteerde beheerde tabel naar een externe tabel.

Prerequisites

• Alle lezers en schrijvers voor de externe tabellen moeten toegang op basis van naam gebruiken. Voorbeeld:

  SELECT * FROM catalog_name.schema_name.table_name;
  

  Padgebaseerde toegang wordt niet ondersteund en kan mislukken nadat de tabel is geconverteerd.

• U moet Databricks Runtime 17.0 of hoger of serverloze rekenkracht gebruiken om te gebruiken SET MANAGED of UNSET MANAGED.

• Als u Unity Catalog-tabellen wilt converteren waarvoor Iceberg-leesbewerkingen (UniForm) al zijn ingeschakeld, moet u Databricks Runtime 17.2 of hoger of serverloze rekenkracht gebruiken om te gebruiken TRUNCATE UNIFORM HISTORY.

• Azure Databricks-lezers en schrijvers moeten Databricks Runtime 15.4 LTS of hoger gebruiken. Als uw lezers of schrijvers 14.3 LTS of lager gebruiken, raadpleegt u alternatieve optie voor lezers en schrijvers in Databricks Runtime 14.3 LTS of lager.

• De SET MANAGED opdracht mislukt met een DELTA_TRUNCATED_TRANSACTION_LOG fout als uw tabel minReaderVersion=2, minWriterVersion=7en tableFeatures={..., columnMapping}. U kunt controleren of uw tabel deze eigenschappen heeft met behulp van DESCRIBE DETAIL.

• Externe clients (niet-Databricks) moeten leesbewerkingen ondersteunen voor beheerde tabellen in Unity Catalog. Zie Tabellen lezen met Delta-clients.

  • Gebruik het Access Insights-dashboard om te zien of lezers en schrijvers die toegang hebben tot uw tabellen Databricks Runtime of externe niet-Databricks zijn.

Important

Als u conflicten wilt voorkomen, annuleert u alle bestaande OPTIMIZE opdrachttaken (liquid clustering, compressie, ZORDER) die op de tabel worden uitgevoerd en plant u geen taken terwijl u uw externe tabellen converteert naar beheerde tabellen.

Converteren van extern naar beheerde tabel

Important

Het converteren van externe naar beheerde tabellen met Behulp van Catalog Explorer bevindt zich in de bètaversie.

Catalogusverkenner

Wanneer u converteert met Catalog Explorer, wordt op naam gebaseerde toegang automatisch gebruikt. U kunt een of meer externe tabellen tegelijk in een schema converteren.

1. Ga naar de tabel of het schema dat u wilt converteren in Catalog Explorer.

2. Klik onder Over deze tabel (tabeldetailpagina) of Over dit schema (schemadetailpagina) op Optimalisaties verkennen.

3. Klik in het dialoogvenster Waarom migreren naar beheerde tabellen in Unity Catalog opDoorgaan.

   

4. Selecteer de externe tabellen die u wilt converteren. Als u het dialoogvenster vanaf een tabeldetailpagina hebt geopend, is de tabel vooraf geselecteerd. Gebruik de zoekbalk om aanvullende tabellen te zoeken. Beheerde tabellen kunnen niet worden geselecteerd.

   

5. Klik op Conversienotebook maken.

6. Voer desgewenst een naam in voor het notitieblok. Standaard wordt de notebook opgeslagen in uw persoonlijke map. Klik op Bladeren om het op te slaan op een andere locatie.

   

7. Controleer in het notebook de aanbevolen procedures en controleer of u aan alle vereisten voldoet.

8. Voer de SET cel MANAGED Query's uit.

Nadat de cel is uitgevoerd, wordt het tabeltype weergegeven als BEHEERD in plaats van EXTERNAL in Catalog Explorer. Vernieuw de pagina als de status niet onmiddellijk wordt bijgewerkt.

SQL

Voer een van de volgende opdrachten uit, afhankelijk van of de externe tabel Apache Iceberg-leesbewerkingen (UniForm) heeft ingeschakeld. Zie Controleren of Iceberg-leesbewerkingen (UniForm) zijn ingeschakeld om te controleren of de tabel Apache Iceberg-leesbewerkingen (UniForm) heeft ingeschakeld.

• Voor externe tabellen van Unity Catalog zonder Apache Iceberg-leesbewerkingen (UniForm) ingeschakeld:

  ALTER TABLE catalog.schema.my_external_table SET MANAGED;
  

  Na de conversie kunt u Iceberg-leesbewerkingen inschakelen voor uw beheerde tabel zonder problemen met compatibiliteit.

• Voor externe tabellen van Unity Catalog waarvoor Apache Iceberg-lezen (UniForm) al is ingeschakeld:

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

  Opnemen TRUNCATE UNIFORM HISTORY om optimale tabelprestaties en -compatibiliteit te behouden. TRUNCATE UNIFORM HISTORY kapt alleen de Geschiedenis van UniForm Iceberg af en verwijdert geen Delta-geschiedenis. Deze opdracht resulteert in een korte lees- en schrijfdowntime voor Iceberg na de truncatie.

Als de opdracht wordt onderbroken tijdens het kopiëren van gegevens, start u deze opnieuw op en gaat u verder vanaf waar de opdracht was gebleven.

Warning

Databricks raadt u aan om te voorkomen dat meerdere SET MANAGED opdrachten gelijktijdig in dezelfde tabel worden uitgevoerd, wat kan leiden tot een inconsistente tabelstatus.

Na de tabelconversie moet u het volgende doen:

• Start streamingtaken (lezen of schrijven) opnieuw met behulp van de externe tabel om te voorkomen dat er naar de vorige locatie wordt gelezen of geschreven. Stop de huidige taak en start een nieuwe taak met dezelfde configuratie.
• Controleer of uw lezers en schrijvers met de beheerde tabel werken.

Voorspellende optimalisatie wordt automatisch ingeschakeld na conversie, tenzij u deze handmatig hebt uitgeschakeld. Zie Controleren of voorspellende optimalisatie is ingeschakeld.

Als voorspellende optimalisatie is ingeschakeld, verwijdert Azure Databricks de gegevens automatisch na 14 dagen op de externe locatie van uw Unity Catalog. Als voorspellende optimalisatie is uitgeschakeld, voert u deze uit VACUUM (hiervoor is Databricks Runtime 17.0 of hoger of serverloze rekenkracht vereist) in de zojuist geconverteerde beheerde tabel na 14 dagen.

VACUUM my_converted_table

Note

In sommige gevallen worden de gegevens in de externe locatie van uw Unity Catalog mogelijk na 14 dagen niet verwijderd, zelfs niet als voorspellende optimalisatie is ingeschakeld, bijvoorbeeld als uw beheerde tabel niet vaak wordt gebruikt of erg klein is. In deze gevallen moet u VACUUM handmatig uitvoeren na 14 dagen om de vorige gegevens te verwijderen.

Azure Databricks verwijdert alleen de gegevens op de externe locatie. Het Delta-transactielogboek en de verwijzing naar de tabel in Unity Catalog worden bewaard.

Conversie controleren

Catalogusverkenner

Vernieuw de pagina. Op het tabblad Details , onder Over deze tabel, wordt het tabeltype weergegeven als Beheerd.

SQL

Voer de volgende opdracht uit om te controleren of de externe tabel is geconverteerd naar een beheerde tabel:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

De tabel Type wordt weergegeven als MANAGED.

Alternatieve optie voor lezers en schrijvers in Databricks Runtime 14.3 LTS of lager

Databricks raadt aan alle lezers en schrijvers te upgraden naar Databricks Runtime 15.4 LTS of hoger om te profiteren van SET MANAGED, inclusief de mogelijkheid om tabelgeschiedenis te behouden.

U kunt nog steeds gebruiken SET MANAGED als u lezers of schrijvers hebt voor Databricks Runtime 14.3 of lager. Na het converteren naar een beheerde tabel kunt u echter geen tijdreizen naar historische wijzigingen op basis van tijdstempels maken, alleen op basis van versies. Als u teruggaat naar een externe tabel in het venster van 14 dagen, gaat u terug naar historische doorvoeringen die zijn gemaakt voordat de conversie opnieuw wordt ingeschakeld.

In alle gevallen werkt het terugdraaien naar een externe tabel van Unity Catalog op basis van een tijdstempel niet voor commits die zijn gemaakt in de geconverteerde beheerde tabel van Unity Catalog tussen de conversie en het terugdraaien.

Voor het schrijven naar een tabel na conversie met Databricks Runtime 15.4 LTS of lager moet de inCommitTimestamp functie worden verwijderd:

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Problemen met conversiefouten oplossen

In deze sectie worden veelvoorkomende problemen beschreven bij het converteren van externe tabellen naar beheerde tabellen in Unity Catalog en hoe u deze kunt oplossen.

Consistentie van de Databricks Runtime-versie

Vermijd het uitvoeren of opnieuw proberen van de conversie van dezelfde tabel met behulp van verschillende Databricks Runtime-versies. Metagegevens kunnen verschillend worden geserialiseerd in verschillende versies, wat een VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED fout veroorzaakt. Als de conversie mislukt, probeert u altijd dezelfde Databricks Runtime-versie te gebruiken.

Cluster afsluiten tijdens conversie

Als uw cluster wordt afgesloten tijdens de conversie, kan de opdracht mislukken met DELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERROR. Voer de opdracht opnieuw uit om de conversie te hervatten.

Beschadigde externe tabel

Als de externe tabel al is beschadigd (bijvoorbeeld een ongeldige tabelstatus), kan de conversie mislukken met fouten zoals DELTA_TRUNCATED_TRANSACTION_LOG, DELTA_TXN_LOG_FAILED_INTEGRITYof DELTA_STATE_RECOVER_ERRORS. Voordat u een conversie uitvoert, moet u controleren of u basisbewerkingen kunt uitvoeren in de externe tabel, zoals DESCRIBE DETAIL.

Fout bij bestandsvalidatie

Met SET MANAGED de opdracht wordt gecontroleerd of alle bestanden in de meest recente momentopname van de tabel worden gekopieerd naar de nieuwe locatie van de beheerde tabel. Als er bestanden ontbreken, mislukt de opdracht met een DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED fout.

Ga als volgt te werk om dit probleem op te lossen:

1. Controleer uw Spark-stuurprogrammalogboeken om te bepalen welke bestanden niet kunnen worden gemigreerd.
2. Controleer of deze bestanden aanwezig zijn op de externe brontabellocatie en toegankelijk zijn.
3. Voer de ALTER TABLE ... SET MANAGED opdracht opnieuw uit.

Neem contact op met databricks-ondersteuning als het probleem zich blijft voordoen.

Terugdraaien naar een externe tabel

Important

Voor de UNSET MANAGED opdracht is Databricks Runtime 17.0 of hoger of serverloze rekenkracht vereist.

Nadat u een externe tabel naar een beheerde tabel hebt geconverteerd, kunt u binnen 14 dagen terugdraaien.

Wanneer u terugdraait, worden de metagegevens van de tabel bijgewerkt om terug te verwijzen naar de oorspronkelijke externe locatie. Alle schrijfbewerkingen die na de conversie naar de beheerde locatie zijn gemaakt, blijven behouden. Commits naar de beheerde locatie tussen conversie en herstellen kunnen per versie worden teruggezet, maar kunnen niet worden teruggezet met een tijdstempel.

Zeven dagen na terugdraaien verwijdert Azure Databricks automatisch gegevens op de beheerde locatie.

Voer de volgende opdracht uit om terug te keren naar een externe tabel:

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

Als de terugdraaiopdracht wordt onderbroken, voert u deze opnieuw uit om het opnieuw te proberen.

U moet uw streamingtaken ook opnieuw starten nadat u deze hebt teruggezet, vergelijkbaar met de conversie.

Terugdraaien controleren

Voer de volgende opdracht uit om te controleren of de conversie is teruggedraaid:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

De tabel Type wordt weergegeven als EXTERNAL.

Als u de tabel in Catalog Explorer bekijkt, vernieuwt u de pagina. Op het tabblad Details , onder Over deze tabel, wordt het tabeltype weergegeven als EXTERNAL.

Downtime en tijd voor het kopiëren van gegevens

De SET MANAGED opdracht minimaliseert of elimineert downtime in vergelijking met alternatieve benaderingen zoals DEEP CLONE. Het conversieproces maakt gebruik van een tweestapsbenadering:

1. Initiële gegevenskopie (geen downtime): De tabelgegevens en het Delta-transactielogboek worden gekopieerd van de externe locatie naar de beheerde locatie. Lezers en schrijvers blijven normaal werken zonder dat dit gevolgen heeft voor lopende bewerkingen.
2. Overschakelen naar beheerde locatie (korte downtime): Doorvoeringen naar de externe locatie tijdens de eerste stap worden verplaatst naar de beheerde locatie en de metagegevens van de tabel worden bijgewerkt om de nieuwe beheerde locatie te registreren. Tijdens deze stap worden alle schrijfoperaties naar de externe locatie tijdelijk geblokkeerd, wat resulteert in downtime voor schrijfbewerkingen. Lezers van Databricks Runtime 16.1 of hoger ervaren geen downtime; lezers van Databricks Runtime 15.4 kunnen downtime ondervinden.

Geschatte uitvaltijd

Tabelgrootte	Aanbevolen clustergrootte	Tijd voor het kopiëren van gegevens	Downtime voor lezer en schrijver
100 GB of minder	32-core / X-Large SQL Warehouse	~6 min of minder	~1-2 min of minder
1 terabyte	64-core / 2X-Large SQL warehouse	~30 min.	~1-2 min.
10 TB	256-core / 4X-Large SQL Warehouse	~1,5 uur	~1-5 min.

Bij de schattingen wordt uitgegaan van een doorvoersnelheid van 0,5-2 GB/CPU-kern/minuut.

Note

Downtime kan variëren op basis van factoren zoals de bestandsgrootte, het aantal bestanden en het aantal doorvoeringen.

Bekende beperkingen

• Streamingclients: U moet alle streamingtaken opnieuw starten na de conversie.

• Beperkingen voor tabelgeschiedenis na terugdraaien: De tabelgeschiedenis van doorvoeringen die na de conversie, maar vóór het terugdraaien zijn gemaakt, kan per versie worden bekeken, maar niet op basis van een tijdstempel.

• Beperkingen voor deltadeling: De SET MANAGED opdracht is niet volledig compatibel met Delta Sharing. Open Delta Sharing werkt zoals verwacht, maar Databricks-to-Databricks delen werkt de beheerde locatie van de ontvangertabel niet automatisch bij. De ontvanger blijft van de oude locatie lezen totdat de tabel opnieuw wordt gedeeld. De tabel opnieuw delen:

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

• Meerdere cloudregio's: Als de standaard beheerde locatie van uw Unity Catalog-metastore, catalogus of schema zich in een andere cloudregio bevindt dan de opslaglocatie van de externe tabel, kunnen er extra kosten voor gegevensoverdracht tussen regio's in rekening worden gebracht. De cloudprovider legt deze kosten buiten Databricks-beheer op.

  De locaties van uw schema, catalogus en metastore controleren:

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