Udostępnij za pośrednictwem

Konwersja tabeli zewnętrznej do zarządzanej tabeli Unity Catalog

Na tej stronie opisano sposób konwertowania tabeli zewnętrznej na tabelę zarządzaną Unity Catalog w usłudze Azure Databricks przy użyciu polecenia ALTER TABLE ... SET MANAGED lub Eksploratora katalogu.

SET MANAGED Przegląd

Służy SET MANAGED do konwertowania tabeli zewnętrznej na tabelę zarządzaną przez Katalog Unity. Mimo że można również użyć CREATE TABLE AS SELECT (CTAS) do konwersji, usługa Databricks zaleca użycie SET MANAGED ze względu na następujące korzyści:

  • Minimalizuje przestoje użytkowników czytnika i zapisującego.
  • Obsługuje współbieżne zapisy podczas konwersji.
  • Zachowuje historię tabel.
  • Przechowuje te same konfiguracje tabeli, w tym nazwy, ustawień, uprawnień i widoków.
  • Obsługuje wycofywanie przekonwertowanej tabeli zarządzanej na tabelę zewnętrzną.

Prerequisites

  • Wszyscy czytelnicy i autorzy tabel zewnętrznych muszą używać dostępu opartego na nazwach. Przykład:

    SELECT * FROM catalog_name.schema_name.table_name;

    Dostęp oparty na ścieżkach nie jest obsługiwany i może zakończyć się niepowodzeniem po przekonwertowaniu tabeli.

  • Aby używać SET MANAGED lub UNSET MANAGED, musisz użyć środowiska Databricks Runtime 17.0 lub nowszego albo przetwarzania bezserwerowego.

  • Aby przekonwertować tabele katalogu Unity z włączonymi odczytami Iceberg (UniForm), należy użyć środowiska Databricks Runtime 17.2 lub nowszego lub obliczeń bezserwerowych, aby użyć TRUNCATE UNIFORM HISTORY.

  • Czytelnicy i autorzy usługi Azure Databricks muszą używać środowiska Databricks Runtime 15.4 LTS lub nowszego. Jeśli czytelnicy lub autorzy używają wersji 14.3 LTS lub nowszej, zobacz Alternatywna opcja dla czytelników i pisarzy w środowisku Databricks Runtime 14.3 LTS lub nowszym.

  • Polecenie SET MANAGED kończy się błędem DELTA_TRUNCATED_TRANSACTION_LOG, jeśli tabela ma minReaderVersion=2, minWriterVersion=7 oraz tableFeatures={..., columnMapping}. Możesz sprawdzić, czy tabela ma te właściwości przy użyciu polecenia DESCRIBE DETAIL.

  • Zewnętrzni klienci (spoza usługi Databricks) muszą obsługiwać odczyty z tabel zarządzanych przez Unity Catalog. Zobacz Odczytywanie tabel za pomocą klientów Delta.

    • Użyj pulpitu nawigacyjnego Access Insights, aby sprawdzić, czy czytelnicy i autorzy uzyskujący dostęp do Twoich tabel korzystają z Databricks Runtime, czy pochodzą z zewnętrznych źródeł spoza Databricks.

Important

Aby uniknąć konfliktów, anuluj wszystkie istniejące OPTIMIZE zadania poleceń (płynne klastrowanie, kompaktowanie, ZORDER) działające w tabeli i nie planuj żadnych zadań podczas konwertowania tabel zewnętrznych na tabele zarządzane.

Konwertowanie z tabeli zewnętrznej na zarządzaną

Important

Konwertowanie tabel zewnętrznych na zarządzane przy użyciu Eksploratora katalogów jest w wersji beta.

Eksplorator wykazu

Podczas konwertowania przy użyciu Eksploratora wykazu automatycznie jest używany dostęp oparty na nazwach. Można przekonwertować jedną lub więcej tabel zewnętrznych w schemacie jednocześnie.

  1. Przejdź do tabeli lub schematu, który chcesz przekonwertować w Eksploratorze wykazu.

  2. W obszarze Informacje o tej tabeli (strona szczegółów tabeli) lub Informacje o tym schemacie (strona szczegółów schematu) kliknij pozycję Eksploruj optymalizacje.

  3. W oknie dialogowym Dlaczego przeprowadzić migrację do tabel zarządzanych w Unity Catalog? kliknij przycisk Kontynuuj.

    Okno dialogowe

  4. Wybierz tabele zewnętrzne, które chcesz przekonwertować. Jeśli okno dialogowe zostało otwarte na stronie szczegółów tabeli, tabela zostanie wstępnie wybrana. Użyj paska wyszukiwania, aby znaleźć dodatkowe tabele. Tabele zarządzane nie są wybieralne.

    Ekran wyboru tabeli przedstawiający wstępnie wybraną tabelę zewnętrzną i niedostępną zarządzaną tabelę

  5. Kliknij pozycję Utwórz notes konwersji.

  6. Opcjonalnie wprowadź nazwę notesu. Domyślnie notes jest zapisywany w folderze głównym. Kliknij przycisk Przeglądaj , aby zapisać go w innej lokalizacji.

    Okno dialogowe Tworzenie notesu konwersji z polem nazwy i opcją Przeglądaj

  7. W notesie przejrzyj najlepsze rozwiązania i sprawdź, czy spełniasz wszystkie wymagania wstępne.

  8. Uruchom komórkę SET ZAPYTANIA ZARZĄDZANE.

Po uruchomieniu komórki typ tabeli jest wyświetlany jako MANAGED zamiast EXTERNAL w Eksploratorze katalogu. Odśwież stronę, jeśli stan nie zostanie natychmiast zaktualizowany.

SQL

W zależności od tego, czy tabela zewnętrzna ma włączone odczyty Apache Iceberg (UniForm), uruchom jedno z następujących poleceń. Zobacz Zweryfikuj, czy odczyty Iceberg (UniForm) są włączone, aby sprawdzić, czy tabela ma włączone odczyty Apache Iceberg (UniForm).

  • W przypadku tabel zewnętrznych Unity Catalog bez włączonego UniForm do odczytu Apache Iceberg:

    ALTER TABLE catalog.schema.my_external_table SET MANAGED;

    Po konwersji można włączyć odczyty Iceberg w zarządzanej tabeli bez problemów ze zgodnością.

  • W przypadku zewnętrznych tabel w Katalogu Unity z odczytów Apache Iceberg (UniForm) jest już włączona:

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

    Uwzględnij TRUNCATE UNIFORM HISTORY, aby zachować optymalną wydajność i zgodność tabeli. TRUNCATE UNIFORM HISTORY Truncuje tylko historię UniForm Iceberg i nie usuwa historii Delta. To polecenie powoduje krótki przestój w odczycie i zapisie dla Iceberg po przycięciu.

Jeśli polecenie zostanie przerwane podczas kopiowania danych, uruchom je ponownie i będzie kontynuowane od miejsca, w którym zostało to przerwane.

Warning

Usługa Databricks zaleca unikanie jednoczesnego uruchamiania wielu SET MANAGED poleceń w tej samej tabeli, co może prowadzić do niespójnego stanu tabeli.

Po konwersji tabeli należy wykonać następujące czynności:

  • Uruchom ponownie wszystkie zadania przesyłania strumieniowego (odczyt lub zapis) przy użyciu tabeli zewnętrznej, aby uniknąć odczytu lub zapisu w poprzedniej lokalizacji. Zatrzymaj bieżące zadanie i uruchom nowe zadanie z tą samą konfiguracją.
  • Sprawdź, czy czytelnicy i autorzy współpracują z zarządzaną tabelą.

Optymalizacja predykcyjna jest automatycznie włączana po konwersji, chyba że została ona ręcznie wyłączona. Zobacz Sprawdzanie, czy optymalizacja predykcyjna jest włączona.

Po włączeniu optymalizacji predykcyjnej usługa Azure Databricks automatycznie usuwa dane w zewnętrznej lokalizacji Unity Catalog po upływie 14 dni. Jeśli optymalizacja predykcyjna jest wyłączona, uruchom polecenie VACUUM (wymaga środowiska Databricks Runtime 17.0 lub nowszego lub bezserwerowego) w nowo przekonwertowanej tabeli zarządzanej po 14 dniach.

VACUUM my_converted_table

Note

W niektórych przypadkach dane w zewnętrznej lokalizacji Unity Catalog mogą nie zostać usunięte po 14 dniach, nawet przy włączonej optymalizacji predykcyjnej — na przykład jeżeli zarządzana tabela nie jest często używana lub jest bardzo mała. W takich przypadkach uruchom ręcznie VACUUM po 14 dniach, aby usunąć poprzednie dane.

Usługa Azure Databricks usuwa tylko dane w lokalizacji zewnętrznej. Dziennik transakcji Delta i odwołanie do tabeli w wykazie Unity Catalog są przechowywane.

Weryfikowanie konwersji

Eksplorator wykazu

Odśwież stronę. Na karcie Szczegóły w obszarze Informacje o tej tabeli zostanie wyświetlona tabela Typ jako Zarządzana.

SQL

Uruchom następujące polecenie, aby potwierdzić, że tabela zewnętrzna została przekonwertowana na tabelę zarządzaną:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Type Tabela jest wyświetlana jako MANAGED.

Alternatywna opcja dla czytelników i pisarzy w środowisku Databricks Runtime 14.3 LTS lub nowszym

Usługa Databricks zaleca uaktualnienie wszystkich readerów i writerów do środowiska Databricks Runtime 15.4 LTS lub nowszego, aby skorzystać z SET MANAGED, w tym możliwości zachowania historii tabel.

Nadal możesz użyć SET MANAGED , jeśli masz czytelników lub pisarzy w środowisku Databricks Runtime 14.3 lub nowszym. Jednak po przekonwertowaniu na tabelę zarządzaną nie można cofnąć się do historycznych zatwierdzeń według znacznika czasu — tylko według wersji. Jeśli cofniesz się do tabeli zewnętrznej w ciągu 14-dniowego okna, podróż w czasie do historycznych zatwierdzeń sprzed konwersji zostanie ponownie włączona.

We wszystkich przypadkach wycofywanie tabeli zewnętrznej Unity Catalog według znacznika czasu nie działa dla żadnych zatwierdzeń dokonanych w przekonwertowanej tabeli zarządzanej Unity Catalog między konwersją a wycofaniem.

Zapisywanie w tabeli po konwersji za pomocą środowiska Databricks Runtime 15.4 LTS lub wcześniejszego wymaga usunięcia funkcji inCommitTimestamp.

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Rozwiązywanie problemów z błędami konwersji

W tej sekcji opisano typowe problemy występujące podczas konwertowania tabel zewnętrznych na tabele zarządzane przez Unity Catalog i jak je rozwiązać.

Spójność wersji środowiska Databricks Runtime

Unikaj uruchamiania lub ponawiania próby konwersji tej samej tabeli przy użyciu różnych wersji środowiska Databricks Runtime. Metadane mogą być serializowane inaczej w różnych wersjach, co powoduje awarię VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED . Jeśli konwersja nie powiedzie się, zawsze spróbuj ponownie użyć tej samej wersji środowiska Databricks Runtime.

Zamykanie klastra podczas konwersji

Jeśli klaster zostanie zamknięty podczas konwersji, polecenie może zakończyć się niepowodzeniem z DELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERROR. Spróbuj ponownie wykonać polecenie, aby wznowić konwersję.

Uszkodzona tabela zewnętrzna

Jeśli tabela zewnętrzna jest już uszkodzona (na przykład nieprawidłowy stan tabeli), konwersja może zakończyć się niepowodzeniem z błędami, takimi jak DELTA_TRUNCATED_TRANSACTION_LOG, DELTA_TXN_LOG_FAILED_INTEGRITYlub DELTA_STATE_RECOVER_ERRORS. Przed podjęciem próby konwersji sprawdź, czy możesz uruchomić podstawowe operacje w tabeli zewnętrznej, takie jak DESCRIBE DETAIL.

Niepowodzenie walidacji pliku

Polecenie SET MANAGED sprawdza, czy wszystkie pliki w najbardziej aktualnej migawce tabeli zostały skopiowane do nowej zarządzanej lokalizacji tabeli. Jeśli brakuje jakichkolwiek plików, polecenie kończy się niepowodzeniem z powodu błędu DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED .

Aby rozwiązać ten problem:

  1. Sprawdź dzienniki sterowników platformy Spark, aby określić, których plików nie można migrować.
  2. Sprawdź, czy te pliki istnieją w lokalizacji źródłowej tabeli zewnętrznej i są dostępne.
  3. Spróbuj ponownie wykonać ALTER TABLE ... SET MANAGED polecenie.

Jeśli problem będzie się powtarzać, skontaktuj się z pomocą techniczną usługi Databricks.

Cofanie do tabeli zewnętrznej

Important

Polecenie UNSET MANAGED wymaga środowiska Databricks Runtime w wersji 17.0 lub nowszej lub bezserwerowej.

Po konwersji tabeli zewnętrznej na tabelę zarządzaną można wycofać tę zmianę w ciągu 14 dni.

Po wycofaniu metadane tabeli są aktualizowane, aby wskazywały oryginalną lokalizację zewnętrzną. Wszystkie zapisy w zarządzanej lokalizacji po konwersji są zachowywane. Zatwierdzenia wprowadzone w zarządzanej lokalizacji pomiędzy konwersją a wycofaniem nadal można przeglądać według wersji, ale nie według znacznika czasu.

Siedem dni po wycofaniu usługa Azure Databricks automatycznie usuwa dane w lokalizacji zarządzanej.

Aby powrócić do poprzedniej wersji tabeli zewnętrznej, uruchom następujące polecenie:

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

Jeśli polecenie wycofywania zostanie przerwane, uruchom go ponownie, aby ponowić próbę.

Należy również ponownie uruchomić zadania przesyłania strumieniowego po wycofaniu, podobnie jak trzeba to zrobić w przypadku konwersji.

Weryfikowanie cofania zmian

Wykonaj następujące polecenie, aby potwierdzić, że konwersja została wycofana:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Type Tabela jest wyświetlana jako EXTERNAL.

Jeśli wyświetlasz tabelę w Eksploratorze wykazu, odśwież stronę. Na karcie Szczegóły w obszarze Informacje o tej tabeli tabela Type jest wyświetlana jako EXTERNAL.

Czas przestoju i kopiowania danych

Polecenie SET MANAGED minimalizuje lub eliminuje przestój w porównaniu z alternatywnymi metodami, takimi jak DEEP CLONE. Proces konwersji używa podejścia dwuetapowego:

  1. Początkowa kopia danych (bez przestoju): Dane tabeli i dziennik transakcji delty są kopiowane z lokalizacji zewnętrznej do lokalizacji zarządzanej. Czytelnicy i autorzy nadal działają normalnie bez wpływu na bieżące operacje.
  2. Przełącz się do lokalizacji zarządzanej (krótki przestój): Zatwierdzenia dokonane w lokalizacji zewnętrznej w pierwszym kroku są przenoszone do lokalizacji zarządzanej, a metadane tabeli są aktualizowane w celu zarejestrowania nowej lokalizacji zarządzanej. W tym kroku wszystkie zapisy w lokalizacji zewnętrznej są tymczasowo blokowane, co powoduje przestój zapisu. Czytelnicy na Databricks Runtime 16.1 lub nowszego nie mają przestoju; czytelnicy na Databricks Runtime 15.4 mogą doświadczać przestoju.

Szacowany przestój:

Rozmiar tabeli Zalecany rozmiar klastra Czas kopiowania danych Przestój czytelnika i zapisującego
100 GB lub mniej 32-rdzeniowy/ X-Large SQL Warehouse ~6 min lub mniej ~1–2 min lub mniej
1 TB (terabajt) 64-rdzeniowy / 2X-Large magazyn SQL ~30 min ~1–2 min
10 terabajtów (TB) 256-rdzeniowy magazyn SQL klasy 4X-Large ~1,5 godz. ~1–5 min

Szacunki zakładają, że szybkość przepływności wynosi 0,5–2 GB/rdzeń procesora CPU/minutę.

Note

Przestój może się różnić w zależności od czynników, takich jak rozmiar pliku, liczba plików i liczba zatwierdzeń.

Znane ograniczenia

  • Klienci przesyłania strumieniowego: Po konwersji należy ponownie uruchomić wszystkie zadania przesyłania strumieniowego.

  • Ograniczenia historii tabel po wycofaniu: Tabela historii zatwierdzeń wykonanych po konwersji, ale przed wycofaniem jest dostępna do przeglądania według wersji, ale nie według znacznika czasu.

  • Ograniczenia Delta Sharing: Polecenie SET MANAGED nie jest w pełni zgodne z Delta Sharing. Udostępnianie funkcji Open Delta działa zgodnie z oczekiwaniami, ale udostępnianie usługi Databricks do usługi Databricks nie powoduje automatycznej aktualizacji lokalizacji zarządzanej tabeli adresata. Odbiorca nadal odczytuje dane ze starej lokalizacji aż do ponownego udostępnienia tabeli. Aby ponownie udostępnić tabelę:

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

  • Wiele regionów chmurowych: Jeśli domyślna zarządzana lokalizacja Unity Catalog Metastore, katalogu lub schematu znajduje się w innym regionie chmurowym niż lokalizacja przechowywania tabeli zewnętrznej, mogą zostać naliczone dodatkowe koszty transferu danych między regionami. Dostawca usług w chmurze nakłada te opłaty poza kontrolą usługi Databricks.

    Aby sprawdzić lokalizacje schematu, katalogu i magazynu metadanych:

    DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;

DESC CATALOG EXTENDED <catalog_name>;

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