Konvertera en extern tabell till en hanterad Unity Catalog-tabell

Den här sidan beskriver hur du konverterar en extern tabell till en hanterad tabell i Unity Catalog i Azure Databricks med hjälp av kommandot ALTER TABLE ... SET MANAGED eller Catalog Explorer.

SET MANAGED Översikt

Använd SET MANAGED för att konvertera en extern tabell till en hanterad Unity Catalog-tabell. Även om du också kan använda CREATE TABLE AS SELECT (CTAS) för konvertering, rekommenderar Databricks SET MANAGED för följande fördelar:

• Minimerar läs- och skrivaravbrott.
• Hanterar samtidiga skrivningar under konverteringen.
• Behåller tabellhistoriken.
• Behåller samma tabellkonfigurationer, inklusive namn, inställningar, behörigheter och vyer.
• Stöder återställning av en konverterad hanterad tabell till en extern tabell.
• Omdirigerar sökvägsbaserade läsningar och skrivningar så att äldre kod kan fungera efter konverteringen.

Prerequisites

• Du måste använda Databricks Runtime 17.0 eller senare eller Serverlös beräkning för att använda SET MANAGED eller UNSET MANAGED.
• Om du vill konvertera Unity Catalog-tabeller med redan aktiverade Isbergsläsningar (UniForm), måste du använda Databricks Runtime 17.2 eller senare eller serverlös databehandling för att kunna använda TRUNCATE UNIFORM HISTORY.
• Azure Databricks läsare och författare måste använda Databricks Runtime 15.4 LTS eller senare. Om dina läsare eller författare använder 14.3 LTS eller nedan, se Alternativ alternativ för läsare och författare på Databricks Runtime 14.3 LTS eller nedan.
• Kommandot SET MANAGED misslyckas med ett DELTA_TRUNCATED_TRANSACTION_LOG fel om tabellen har minReaderVersion=2, minWriterVersion=7och tableFeatures={..., columnMapping}. Du kan kontrollera om tabellen har dessa egenskaper med hjälp av DESCRIBE DETAIL.
• Externa (icke-Databricks)-klienter måste ha stöd för läsningar till hanterade Unity Catalog-tabeller. Se Åtkomsttabeller med Delta-klienter.
  • Använd Instrumentpanelen för Access Insights för att avgöra om de användare som har tillgång till dina tabeller använder Databricks Runtime eller externa system som inte är Databricks.

Efter konverteringen omdirigeras sökvägsbaserade läsningar och skrivningar automatiskt till den nya hanterade platsen med mindre prestandakostnader. Databricks rekommenderar att du migrerar all sökvägsbaserad åtkomst till namnbaserad åtkomst för att undvika prestandakostnader. Se Sökvägsbaserad omdirigering.

Konvertera från extern till hanterad tabell

Katalogutforskaren

När du konverterar med Hjälp av Katalogutforskaren används namnbaserad åtkomst automatiskt. Du kan konvertera en eller flera externa tabeller i ett schema i taget.

1. Gå till den tabell eller det schema som du vill konvertera i Katalogutforskaren.

2. Under Om den här tabellen (tabellinformationssida) eller Om det här schemat (schemainformationssidan) klickar du på Utforska optimeringar.

3. I dialogrutan Varför migrera till hanterade Unity Catalog-tabeller? klickar du på Fortsätt.

   

4. Välj de externa tabeller som du vill konvertera. Om du öppnade dialogrutan från en tabellinformationssida är tabellen förvald. Använd sökfältet för att hitta ytterligare tabeller. Hanterade tabeller kan inte väljas.

   

5. Klicka på Skapa konverteringsanteckningsbok.

6. Du kan också ange ett namn för notebook-filen. Som standard sparas anteckningsboken i din hemmapp. Klicka på Bläddra för att spara den på en annan plats.

   

7. Granska rekommenderade metoder i notebook-filen och kontrollera att du uppfyller alla krav.

8. Kör cellen SET MANAGED Queries (HANTERADE frågor ).

När cellen har körts visas tabelltypen som HANTERAd i stället för EXTERN i Katalogutforskaren. Uppdatera sidan om statusen inte uppdateras omedelbart.

SQL

Beroende på om din externa tabell har aktiverade Apache Iceberg-avläsningar (UniForm) kör något av följande kommandon. Se Kontrollera att Iceberg-läsningar (UniForm) är aktiverade för att kontrollera om Apache Iceberg-läsningar (UniForm) är aktiverade i tabellen.

• För externa Unity Catalog-tabeller utan Apache Iceberg-läsningar (UniForm) aktiverade:

  ALTER TABLE catalog.schema.my_external_table SET MANAGED;
  

  Efter konverteringen kan du aktivera Iceberg-läsningar i den hanterade tabellen utan kompatibilitetsproblem.

• För externa Unity Catalog-tabeller med Apache Iceberg-läsningar (UniForm) redan aktiverade:

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

  Inkludera TRUNCATE UNIFORM HISTORY för att upprätthålla optimala tabellprestanda och kompatibilitet. TRUNCATE UNIFORM HISTORY trunkerar endast UniForm Iceberg-historiken och tar inte bort Delta-historiken. Det här kommandot resulterar i en kort nedtid för både läsning och skrivning för Iceberg efter trunkeringen.

Om kommandot avbryts när data kopieras startar du om det och fortsätter där det slutade.

Efter tabellkonvertering misslyckas läs- och skrivströmmar. Starta om strömmar med samma konfigurationer för att automatiskt använda sökvägsbaserad omdirigering. Kontrollera att läsarna och författarna arbetar med den hanterade tabellen. Se Beteende för direktuppspelning.

Förutsägande optimering aktiveras automatiskt efter konverteringen om du inte inaktiverade den manuellt. Se Kontrollera om förutsägelseoptimering är aktiverat.

När förutsägande optimering är aktiverat tar Azure Databricks automatiskt bort data på den externa platsen i Unity Catalog efter 14 dagar. Om förutsägelseoptimering är inaktiverad, kör du VACUUM (kräver Databricks Runtime 17.0 eller senare eller serverlös beräkning) på den nyligen konverterade hanterade tabellen efter 14 dagar.

VACUUM my_converted_table

Verifiera konvertering

Katalogutforskaren

Uppdatera sidan. På fliken Information under Om den här tabellen visas tabelltypen som Hanterad.

SQL

Kör följande kommando för att bekräfta att den externa tabellen har konverterats till en hanterad tabell:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Tabellen Type visas som MANAGED.

Alternativt alternativ för läsare och skrivare på Databricks Runtime 14.3 LTS eller nedan

Databricks rekommenderar att du uppgraderar alla läsare och skrivare till Databricks Runtime 15.4 LTS eller senare för att dra nytta av SET MANAGED, inklusive möjligheten att behålla tabellhistoriken.

Du kan fortfarande använda SET MANAGED om du har läsare eller författare på Databricks Runtime 14.3 eller lägre. Men när du har konverterat till en hanterad tabell kan du inte göra tidsresor till tidigare åtaganden med tidsstämpel – endast med versioner. Om du återställer till en extern tabell inom 14-dagarsfönstret återaktiveras tidsresor till historiska åtaganden som gjordes före konverteringen.

Att återställa till en extern Unity Catalog-tabell efter tidsstämpel fungerar inte i något fall för ändringar som gjorts till din konverterade Unity Catalog-hanterade tabell mellan konvertering och återställning.

Om du skriver till en tabell efter konverteringen med Databricks Runtime 15.4 LTS eller senare måste du ta bort inCommitTimestamp funktionen:

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Sökvägsbaserad omdirigering

I Databricks Runtime 18.1 och senare omdirigeras sökvägsbaserade läsningar och skrivningar till den tidigare externa platsen automatiskt till den nya hanterade platsen när du har konverterat en extern tabell till en hanterad Unity Catalog-tabell. Sökvägsbaserad omdirigering minskar den tid och det arbete som krävs för att migrera till hanterade tabeller eftersom den tillåter äldre kod som kommer åt tabeller efter lagringssökväg att fortsätta fungera utan att du behöver omstrukturera.

För användningsfall med låg latens rekommenderar Azure Databricks att du migrerar sökvägsbaserad åtkomst till namnbaserad åtkomst. Sökvägsbaserad omdirigering lägger till flera hundra millisekunder i tid för varje sökvägsbaserad läsning eller skrivning, och kräver att du behåller gamla Delta-loggar aktiva på din externa plats i Unity Catalog. Namnbaserade läsningar och skrivningar har inte ytterligare prestandakostnader.

Beteende för direktuppspelning

För direktuppspelning med sökvägsbaserad omdirigering:

• Läsningar stöds i Databricks Runtime 18.1 och senare.
• Skrivoperationer stöds i Databricks Runtime 18.2 och senare.

Efter konverteringen måste du starta om alla direktuppspelningsjobb för att undvika att läsa från eller skriva till den tidigare tabellplatsen.

Sökvägsbaserade direktuppspelningsläsningar och skrivningar misslyckas och stoppas vid nästa kontrollpunkt med ett migreringsmeddelande:

• Vid läsningar genererar strömmen ett fel: DELTA_STREAMING_INTERRUPTED_BY_MANAGED_TABLE_CONVERSION: The table at <path> has been converted to a Unity Catalog managed table. The stream has been stopped to ensure data consistency. Restart the stream and it will automatically resume from the last committed offset using the converted table.
• För skrivningar genererar den första mikrobatchen efter konverteringen ett fel: Operation not allowed: STREAMING WRITE cannot be performed on a table with redirect feature. The no redirect rules are not satisfied [].

Lös fel genom att starta om strömmar med samma konfigurationer. Sökvägsbaserad åtkomst omdirigeras automatiskt till den hanterade tabellen.

Begränsningar

• Sökvägsbaserad omdirigering ger endast bakåtkompatibilitet för migreringsprocessen och aktiverar inte ny sökvägsbaserad åtkomst till hanterade Unity Catalog-tabeller.

Felsöka konverteringsfel

I det här avsnittet beskrivs vanliga problem när du konverterar externa tabeller till hanterade Unity Catalog-tabeller och hur du löser dem.

Databricks Runtime-versionskonsekvens

Undvik att köra eller försöka konvertera samma tabell igen med hjälp av olika Databricks Runtime-versioner. Metadata kan serialiseras på olika sätt mellan olika versioner, vilket orsakar ett VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED fel. Om konverteringen misslyckas försöker du alltid igen med samma Databricks Runtime-version.

Avstängning av kluster under konvertering

Om klustret stängs av under konverteringen kan kommandot misslyckas med DELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERROR. Försök igen med kommandot för att återuppta konverteringen.

Skadad extern tabell

Om den externa tabellen redan är skadad (till exempel inte giltigt tabelltillstånd) kan konverteringen misslyckas med fel som DELTA_TRUNCATED_TRANSACTION_LOG, DELTA_TXN_LOG_FAILED_INTEGRITYeller DELTA_STATE_RECOVER_ERRORS. Innan du försöker konvertera kontrollerar du att du kan köra grundläggande åtgärder i den externa tabellen, till exempel DESCRIBE DETAIL.

Filvalideringsfel

Kommandot SET MANAGED verifierar att alla filer i den senaste ögonblicksbilden av tabellen kopieras till den nya hanterade tabellplatsen. Om några filer saknas misslyckas kommandot med ett DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED fel.

Så här löser du problemet:

1. Kontrollera Spark-drivrutinsloggarna för att identifiera vilka filer som inte kunde migreras.
2. Kontrollera att dessa filer finns på platsen för den externa källtabellen och att de är tillgängliga.
3. Försök igen med ALTER TABLE ... SET MANAGED kommandot.

Om problemet kvarstår kontaktar du Databricks-supporten.

Rulla tillbaka till en extern tabell

När du har konverterat en extern tabell till en hanterad tabell kan du återställa inom 14 dagar.

När du rullar tillbaka uppdateras tabellmetadata så att de pekar tillbaka till det ursprungliga externa lagringsstället. Alla skrivningar som görs till den hanterade platsen efter konvertering bevaras. Incheckningar som gjorts till den hanterade platsen mellan konvertering och återställning förblir tidsresbara med avseende på version, men inte med avseende på tidsstämpel.

Sju dagar efter återställningen tar Azure Databricks automatiskt bort data på den hanterade platsen.

Kör följande kommando för att återställa till en extern tabell:

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

Om återställningskommandot avbryts kör du det igen för att försöka igen.

Du måste också starta om dina direktuppspelningsjobb efter återställning, ungefär som konvertering.

Verifiera återställning

Kör följande kommando för att bekräfta att konverteringen har återställts:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Tabellen Type visas som EXTERNAL.

Om du visar tabellen i Katalogutforskaren uppdaterar du sidan. På fliken Information under Om den här tabellen visas tabelltypen som EXTERNAL.

Stilleståndstid och datakopieringstider

Kommandot SET MANAGED minimerar eller eliminerar stilleståndstid jämfört med alternativa metoder som DEEP CLONE. Konverteringsprocessen använder en tvåstegsmetod:

1. Inledande datakopiering (ingen stilleståndstid): Tabelldata och Delta-transaktionsloggen kopieras från den externa platsen till den hanterade platsen. Läsare och skrivare fortsätter att fungera normalt utan att påverka pågående operationer.
2. Växla till hanterad plats (kort stilleståndstid): Incheckningar som görs till den externa platsen under det första steget flyttas till den hanterade platsen och tabellmetadata uppdateras för att registrera den nya hanterade platsen. Under det här steget blockeras alla skrivningar till den externa platsen tillfälligt, vilket resulterar i skrivaravbrott. Läsare på Databricks Runtime 16.1 eller senare upplever ingen stilleståndstid; läsare på Databricks Runtime 15.4 kan uppleva stilleståndstid.

Uppskattad stilleståndstid:

Uppskattningarna förutsätter en dataflödeshastighet på 0,5–2 GB/CPU-kärna/minut.

Begränsningar

• Du måste starta om alla direktuppspelningsjobb efter konverteringen. Se Beteende för direktuppspelning.

• Tabellhistorik för commit som gjorts efter konverteringen men innan återställningen möjliggör tidsresor via version men inte via tidsstämpel.

• Deltadelning är inte helt kompatibelt med SET MANAGED kommandot . Öppna Deltadelning fungerar som förväntat, men Databricks-till-Databricks-delning uppdaterar inte mottagartabellens hanterade plats automatiskt. Mottagaren fortsätter att läsa från den gamla platsen tills tabellen delas på nytt. För att dela tabellen igen:

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

• Om standardplatsen för enhetskatalogens metaarkiv, katalog eller schema finns i en annan molnregion än den externa tabellens lagringsplats kan det medföra ytterligare kostnader för dataöverföring mellan regioner från molnleverantören.

  Så här verifierar du platserna för schemat, katalogen och metaarkivet:

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