Konvertieren einer externen Tabelle in eine verwaltete Unity-Katalogtabelle

Diese Seite beschreibt die Verwendung des ALTER TABLE ... SET MANAGED Befehls zum Konvertieren einer externen Tabelle in eine verwaltete Unity-Katalog-Tabelle in Azure Databricks.

Übersicht SET MANAGED

Verwenden Sie das SET MANAGED Feature, um eine externe Tabelle in eine verwaltete Unity-Tabelle in Azure Databricks zu konvertieren. SET MANAGED bietet die folgenden Vorteile:

• Minimierung der Ausfallzeit für Leser und Schreiber.
• Gleichzeitige Schreibvorgänge während der Konvertierung behandeln.
• Tabellenverlauf beibehalten.
• Beibehalten der gleichen Tabellenkonfigurationen, einschließlich desselben Namens, der Einstellungen, Berechtigungen und Ansichten.
• Möglichkeit, eine konvertierte verwaltete Tabelle auf eine externe Tabelle zurückzusetzen.

Prerequisites

Um das Tabellenkonvertierungsfeature zu verwenden, müssen Sie die folgenden Voraussetzungen erfüllen:

• Alle Leser und Autoren für die externen Tabellen müssen namenbasierten Zugriff verwenden. Beispiel:

  SELECT * FROM catalog_name.schema_name.table_name;
  

  Der pfadbasierte Zugriff wird nicht unterstützt und schlägt möglicherweise fehl, nachdem die Tabelle konvertiert wurde.

• Sie müssen Databricks Runtime 17.0 oder höher oder serverlose Berechnung verwenden, verwenden oder verwendenSET MANAGED.UNSET MANAGED

• Um Unity Catalog-Tabellen mit bereits aktivierten Iceberg-Lesevorgängen (UniForm) zu konvertieren, müssen Sie Databricks Runtime 17.2 oder höher oder serverlose Compute verwenden, um TRUNCATE UNIFORM HISTORY zu nutzen.

• Azure Databricks-Leser und -Autoren müssen Databricks Runtime 15.4 LTS oder höher verwenden. Wenn Ihre Leser oder Autoren 14.3 LTS oder niedriger verwenden, lesen Sie die Alternative Option für Leser und Autoren der Databricks Runtime 14.3 LTS oder niedriger.

• Der SET MANAGED-Befehl schlägt mit einem DELTA_TRUNCATED_TRANSACTION_LOG-Fehler fehl, wenn Ihre Tabelle minReaderVersion=2, minWriterVersion=7 und tableFeatures={..., columnMapping} enthält. Sie können überprüfen, ob ihre Tabelle diese Eigenschaften verwendet DESCRIBE DETAIL.

• Externe (nicht-Databricks)-Clients müssen Lesevorgänge in den verwalteten Tabellen des Unity-Katalogs unterstützen. Siehe Lesen von Tabellen mit Delta-Clients.

  • Verwenden Sie das Access Insights-Dashboard , um festzustellen, ob Leser und Autoren, die auf Ihre Tabellen zugreifen, Databricks Runtime oder externe Nicht-Databricks sind.

Important

Um Konflikte zu vermeiden, brechen Sie alle vorhandenen OPTIMIZE Befehlsaufträge (flüssiger Clustering, Komprimierung, ZORDERKomprimierung) ab, und planen Sie keine Aufträge, während Sie Ihre externen Tabellen in verwaltete Tabellen konvertieren.

Konvertieren von einer externen in verwaltete Tabelle

Important

Der SET MANAGED Befehl ist in Databricks Runtime 17.0 oder höher und serverlosem Compute verfügbar.

Der TRUNCATE UNIFORM HISTORY Befehl ist in Databricks Runtime 17.2 oder höher und serverlosem Compute verfügbar.

Führen Sie einen der folgenden Befehle aus, um Die externe Tabelle ihres Unity-Katalogs in eine verwaltete Unity-Katalog-Tabelle zu konvertieren.

• Für externe Tabellen im Unity-Katalog ohne aktivierte Apache Iceberg-Reads (UniForm):

  ALTER TABLE catalog.schema.my_external_table SET MANAGED;
  

  Nach der Konvertierung können Sie Iceberg-Lesevorgänge in Ihrer verwalteten Tabelle ohne Kompatibilitätsprobleme aktivieren.

• Für externe Tabellen im Unity-Katalog mit Iceberg-Lesezugriffen (UniForm) wurde bereits Folgendes aktiviert:

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

  Fügen Sie in diesem Fall TRUNCATE UNIFORM HISTORY ein, um die optimale Tabellenleistung und -kompatibilität zu gewährleisten. TRUNCATE UNIFORM HISTORY schneidet nur die Geschichte von UniForm Iceberg ab und entfernt keine Delta-Geschichte. Dieser Befehl führt nach der Verkürzung zu einer kurzen Lese- und Schreibausfallzeit für Iceberg.

Wenn der Befehl beim Kopieren von Daten unterbrochen wird, können Sie ihn neu starten und von dort aus fortfahren, wo Sie aufgehört haben.

Warning

Databricks empfiehlt, mehrere SET MANAGED Befehle nicht gleichzeitig in derselben Tabelle auszuführen, da dies zu einem inkonsistenten Tabellenzustand führen kann.

Nach der Tabellenkonvertierung müssen Sie:

• Starten Sie alle Streamingaufträge (Lesen oder Schreiben) mithilfe der externen Tabelle neu.
• Stellen Sie sicher, dass Ihre Leser und Autoren mit der verwalteten Tabelle arbeiten.

Die Predictive Optimization wird automatisch aktiviert, außer wenn Sie sie manuell deaktiviert haben. Überprüfen Sie, ob die Predictive Optimization aktiviert ist.

Mit aktivierter prädiktiven Optimierung löscht Azure Databricks die Daten nach 14 Tagen automatisch an Ihrem externen Speicherort im Unity-Katalog. Wenn die Predictive Optimization deaktiviert ist, können Sie die neu konvertierte verwaltete Tabelle nach Ablauf von 14 Tagen mit VACUUM ausführen (dies erfordert Databricks Runtime 17.0 oder höher oder serverlose Compute).

VACUUM my_converted_table

Note

In einigen Fällen werden die Daten am externen Speicherort Ihres Unity-Katalogs möglicherweise nicht nach 14 Tagen gelöscht, auch wenn die Vorhersageoptimierung aktiviert ist. Wenn Ihre verwaltete Tabelle im Unity-Katalog z. B. nicht häufig verwendet wird oder sehr klein ist, tritt möglicherweise kein automatischer Löschvorgang auf. In diesen Fällen müssen Sie nach 14 Tagen VACUUM manuell auf der neu konvertierten verwalteten Tabelle ausführen (erfordert Databricks Runtime 17.0 oder höher oder serverlose Compute), um die alten Daten zu entfernen.

Azure Databricks löscht nur die Daten am externen Speicherort. Das Delta-Transaktionsprotokoll und der Verweis auf die Tabelle im Unity-Katalog werden beibehalten.

Konvertierung überprüfen

Sie können bestätigen, dass Ihre externe Tabelle in eine verwaltete Tabelle konvertiert wurde:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Überprüfen Sie die Ausgabe dieses Befehls, um zu bestätigen, dass die Tabelle konvertiert wurde. Die Tabelle Type sollte angezeigt werden als MANAGED.

Wenn Sie die Tabelleninformationen im Katalog-Explorer anzeigen, aktualisieren Sie die Seite. Auf der Registerkarte "Details " sollte unter " Über diese Tabelle" der Tabellentyp als MANAGEDangezeigt werden.

Alternative Option für Leser und Autoren auf Databricks Runtime 14.3 LTS oder darunter

Databricks empfiehlt, alle Leser und Autoren auf Databricks Runtime 15.4 LTS oder höher zu aktualisieren, um den SET MANAGED Befehl zu nutzen, einschließlich der Möglichkeit, den Tabellenverlauf beizubehalten.

Sie können den SET MANAGED Befehl weiterhin verwenden, wenn Sie Leser oder Autoren mit Databricks Runtime 14.3 oder darunter haben. Nach der Konvertierung in eine verwaltete Tabelle können Sie jedoch nicht mehr auf frühere Commits anhand von Zeitstempeln zugreifen. Sie können dies nur nach Version tun. Wenn Sie ein Rollback auf eine externe Tabelle innerhalb des 14-Tage-Zeitraums durchführen, wird die Zeitreise zu historischen Commits, die vor der Konvertierung vorgenommen wurden, erneut aktiviert.

In allen Fällen (unabhängig von der DBR-Version) funktioniert ein Rollback auf UC extern nach Zeitstempel nicht für Commits, die an der konvertierten verwalteten UC-Tabelle während des Zeitraums vorgenommen wurden, in dem Sie die Konvertierung abgeschlossen hatten und bevor Sie versucht haben, ein Rollback auszuführen.

Das Schreiben in eine Tabelle nach der Konvertierung mit Databricks Runtime 15.4 LTS oder niedriger erfordert das Ablegen des inCommitTimestamp Features:

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Problembehandlung bei Konvertierungsfehlern

In diesem Abschnitt werden häufige Probleme beim Konvertieren externer Tabellen in verwaltete Tabellen im Unity-Katalog beschrieben und wie sie behoben werden.

DBR-Versionskonsistenz

Vermeiden Sie das Ausführen oder Wiederholen der Konvertierung derselben Tabelle mit unterschiedlichen Databricks-Runtime-Versionen. Metadaten können in allen Versionen unterschiedlich serialisiert werden, was zu einem VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED Fehler führt. Wenn die Konvertierung fehlschlägt, versuchen Sie immer, dieselbe Databricks-Runtime-Version zu verwenden.

Cluster-Abschaltung während der Konvertierung

Wenn Ihr Cluster während der Konvertierung heruntergefahren wird, kann der Befehl möglicherweise fehlschlagen mit DELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERROR. Wiederholen Sie den Befehl, um die Konvertierung fortzusetzen.

Beschädigte externe Tabelle

Wenn die externe Tabelle bereits beschädigt ist (z. B. ungültiger Tabellenzustand), schlägt die Konvertierung möglicherweise mit Fehlern wie DELTA_TRUNCATED_TRANSACTION_LOG, DELTA_TXN_LOG_FAILED_INTEGRITY oder DELTA_STATE_RECOVER_ERRORS fehl. Stellen Sie vor dem Versuch der Konvertierung sicher, dass Sie grundlegende Vorgänge für die externe Tabelle ausführen können, wie z. B. DESCRIBE DETAIL.

Zurückkehren zu einer externen Tabelle

Important

Der UNSET MANAGED Befehl ist in Databricks Runtime 17.0 oder höher und serverlosem Compute verfügbar.

Nachdem Sie eine externe Tabelle in eine verwaltete Tabelle konvertiert haben, können Sie innerhalb von 14 Tagen einen Rollback ausführen.

Wenn Sie ein Rollback ausführen, sind Commits, die am externen Speicherort zwischen der Konvertierung und dem Rollback vorgenommen wurden, nach Version, aber nicht nach Zeitstempel, zeitlich rückverfolgbar. Sieben Tage nach dem Rollback werden Daten am verwalteten Speicherort gelöscht.

Führen Sie zum Zurücksetzen auf eine externe Tabelle den folgenden Befehl aus:

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED

Wenn der Rollbackbefehl unterbrochen wird, können Sie ihn erneut ausführen, ähnlich wie beim verwalteten SET-Befehl.

Rollback überprüfen

Sie können bestätigen, dass Ihre Konvertierung zurückgesetzt wurde:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Überprüfen Sie die Ausgabe dieses Befehls, um zu bestätigen, dass die Tabelle rückgängig gemacht wurde. Die Tabelle Type sollte angezeigt werden als EXTERNAL.

Wenn Sie die Tabelleninformationen im Katalog-Explorer anzeigen, aktualisieren Sie die Seite. Auf der Registerkarte "Details " sollte unter " Über diese Tabelle" der Tabellentyp als EXTERNALangezeigt werden.

Sie müssen ihre Streamingaufträge auch neu starten, nachdem Sie ein Rollback auf eine externe Tabelle durchgeführt haben, ähnlich der Konvertierung.

Ausfallzeiten und Datenkopiezeiten

Ausfallzeiten können auftreten, wenn Leser oder Autoren während der Konvertierung auf die Tabelle zugreifen. Im Vergleich zum Befehl "DEEP CLONE" minimiert oder beseitigt der SET MANAGED Befehl Jedoch Ausfallzeiten für Leser und Autoren. Leser auf Databricks Runtime 16.1 oder höher erleben keine Ausfallzeiten. Leser und Autoren sind während des ersten Schritts nicht betroffen, wenn die Tabellendaten und das Delta-Protokoll kopiert werden.

Während des zweiten Schritts werden Schreibvorgänge am externen Speicherort des Unity-Katalogs blockiert, und die während der ersten Datenkopie getätigten Commits an diesem Speicherort werden verschoben. Dieser zweite Datenkopienschritt führt zu Ausfallzeiten für Autoren und Leser in Databricks Runtime 15.4 LTS oder darunter.

Danach werden Leser und Autoren an den verwalteten Speicherort des Unity-Katalogs verschoben, und der neue Speicherort der verwalteten Tabelle wird im Unity-Katalog registriert. Nutzer mit Databricks Runtime 16.1 oder höher werden einen Zustand erleben, der einem Nichtvorhandensein von Ausfallzeiten gleichkommt.

Geschätzte Ausfallzeiten sind:

Tabellengröße	Empfohlene Clustergröße	Zeit für datenkopie	Ausfallzeiten von Lese- und Schreibgeräten
100 GB oder weniger	32-Core / DBSQL small	~6min oder weniger	~1-2min oder weniger
1 TB	64-Core / DBSQL Medium	~30 Min.	~1-2min
10 TB	256-core / DBSQL x-large	~1,5 Stunden	~1-5min

Die Schätzungen gehen von einer Durchsatzrate von 0,5-2 GB/CPU-Kern/Minute aus.

Note

Ausfallzeiten können variieren. Die Leistung der Konvertierung hängt von Faktoren wie Der Dateigröße, der Anzahl der Dateien und der Anzahl der Commits ab.

Bekannte Einschränkungen

Beim Umwandeln von externen in verwaltete Tabellen gibt es folgende Einschränkungen:

• Streamingclients: Sie müssen alle Streamingaufträge nach der Konvertierung neu starten.

• Tabellenverlaufseinschränkungen nach dem Rollback: Für Leser/Schreiber in Databricks Runtime 15.4 LTS oder höher ist der Tabellenverlauf für Commits, die nach der Konvertierung, aber vor dem Rollback erfolgt sind, nach Version, aber nicht nach dem Zeitstempel abrufbar.

• Einschränkungen für die Delta-Freigabe: Der SET MANAGED Befehl ist nicht vollständig kompatibel mit der Delta-Freigabe. Während die offene Delta-Freigabe wie vorgesehen funktioniert, aktualisiert die Databricks-to-Databricks-Freigabe nicht automatisch den verwalteten Speicherort der Empfängertabelle. Der Empfänger liest weiterhin vom alten Standort aus, bis die Tabelle erneut freigegeben wird. Um die Tabelle erneut zu teilen:

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

• Mehrere Cloudregionen: Wenn sich der standardmäßig verwaltete Speicherort Ihres Unity-Katalogmetastores, -Katalogs oder -Schemas in einer anderen Cloudregion befindet als der Speicherort der externen Tabelle, die konvertiert wird, können Sie zusätzliche regionsübergreifende Datenübertragungskosten verursachen. Der Cloudanbieter erzwingt diese Gebühren außerhalb der Databricks-Kontrolle.

  Um die Speicherorte Ihres Schemas, Katalogs und Metastores zu überprüfen, können Sie die folgenden Befehle verwenden:

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