Verwenden von UniForm zum Lesen von Deltatabellen mit Iceberg-Clients

Das universelle Delta-Format (UniForm) ermöglicht das Lesen von Delta-Tabellen mit Iceberg-Reader-Clients. Für dieses Feature wird Databricks Runtime 14.3 LTS oder höher benötigt.

Wichtig

Eine Dokumentation für die Legacytabellenfunktion IcebergCompatV1 von UniForm finden Sie unter UniForm IcebergCompatV1 (Legacy).

UniForm nutzt die Tatsache, dass sowohl Delta Lake als auch Iceberg aus Parquet-Datendateien und einer Metadatenebene bestehen. UniForm generiert automatisch asynchron Iceberg-Metadaten, ohne Daten neu zu schreiben, sodass Iceberg-Clients Delta-Tabellen lesen können, als wären sie Iceberg-Tabellen. Eine einzelne Kopie der Datendateien dient beiden Formaten.

Sie können eine externe Verbindung so konfigurieren, dass Unity Catalog als Iceberg-Katalog fungiert. Weitere Informationen finden Sie unter Lesen mithilfe des Unity Catalog Iceberg-Katalogendpunkts.

UniForm verwendet zstd anstelle von Snappy als Komprimierungscodec für zugrunde liegende Parkettdatendateien.

Hinweis

Die Generierung von UniForm-Metadaten wird asynchron auf dem Compute ausgeführt, der zum Schreiben von Daten in Delta-Tabellen verwendet wird, was die Ressourcenauslastung des Treibers erhöhen kann.

Anforderungen

Um UniForm aktivieren zu können, müssen Sie die folgenden Anforderungen erfüllen:

• Die Delta-Tabelle muss bei Unity Catalog registriert werden. Sowohl verwaltete als auch externe Tabellen werden unterstützt.
• Für die Tabelle muss die Spaltenzuordnung aktiviert sein. Weitere Informationen finden Sie unter Rename and drop columns with Delta Lake column mapping (Umbenennen und Löschen von Spalten mit Delta Lake-Spaltenzuordnung).
• Die Delta-Tabelle muss eine minReaderVersion>= 2 und eine minWriterVersion>= 7 aufweisen. Weitere Informationen finden Sie unter Wie verwaltet Azure Databricks die Kompatibilität von Delta Lake-Features?.
• Schreibvorgänge in die Tabelle müssen Databricks Runtime 14.3 LTS oder höher verwenden.

Hinweis

Sie können Löschvektoren für eine Tabelle nicht aktivieren, wenn UniForm aktiviert ist. Wenn Sie UniForm für eine vorhandene Tabelle mit aktivierten Löschvektoren aktivieren, deaktiviert und löscht UniForm Löschvektoren und schreibt Datendateien nach Bedarf neu.

Aktivieren von Delta UniForm

Wichtig

Durch Aktivieren von Delta UniForm wird das Delta-Tabellenfeature IcebergCompatV2, ein Feature zum Schreiben von Protokollen, festgelegt. Nur Clients, die dieses Tabellenfeature unterstützen, können in Tabellen mit aktiviertem UniForm schreiben. Sie müssen Databricks Runtime 14.3 LTS oder höher verwenden, um mit dem aktivierten Feature in Delta-Tabellen zu schreiben.

Sie können UniForm deaktivieren, indem Sie die Tabelleneigenschaft delta.universalFormat.enabledFormats löschen. Sie können die Spaltenzuordnung nicht deaktivieren, nachdem sie aktiviert wurde, und Upgrades von Delta Lake Reader- und Writer-Protokollversionen können nicht rückgängig gemacht werden.

Sie müssen die folgenden Tabelleneigenschaften festlegen, um die UniForm-Unterstützung für Iceberg zu aktivieren:

'delta.enableIcebergCompatV2' = 'true'
'delta.universalFormat.enabledFormats' = 'iceberg'

Außerdem müssen Sie die Spaltenzuordnung aktivieren, um UniForm nutzen zu können. Diese ist automatisch aktiviert, wenn Sie UniForm während der Tabellenerstellung aktivieren, wie das folgende Beispiel zeigt:

CREATE TABLE T(c1 INT) TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

Sie können UniForm mithilfe der folgenden Syntax ermöglichen, in eine vorhandene Tabelle zu schreiben:

REORG TABLE table_name APPLY (UPGRADE UNIFORM(ICEBERG_COMPAT_VERSION=2));

Hinweis

Diese Syntax funktioniert auch zum Upgraden der Public Preview-Version von UniForm, die die Tabellenfunktion IcebergCompatV1 verwendet hat.

Diese Syntax deaktiviert und löscht Löschvektoren automatisch aus der Tabelle. Vorhandene Dateien werden nach Bedarf umgeschrieben, um sie mit Iceberg kompatibel zu machen.

Wenn Sie UniForm zum ersten Mal aktivieren, beginnt die asynchrone Generierung von Metadaten. Diese Aufgabe muss abgeschlossen werden, bevor externe Clients die Tabelle mithilfe von Iceberg abfragen können. Weitere Informationen finden Sie unter Überprüfen des Status der Generierung von Iceberg-Metadaten.

Hinweis

Wenn Sie BigQuery als Iceberg-Reader-Client verwenden möchten, müssen Sie in Azure Databricks spark.databricks.delta.write.dataFilesToSubdir auf festlegentrue, um eine BigQuery-Anforderung für das Datenlayout zu ermöglichen.

Informationen finden Sie unter Einschränkungen.

Wann generiert UniForm Iceberg-Metadaten?

Azure Databricks löst die Generierung von Iceberg-Metadaten asynchron aus, nachdem eine Delta Lake-Schreibtransaktion mit demselben Computeausführung abgeschlossen wurde, die die Delta-Transaktion abgeschlossen hat. Sie können die Generierung von Iceberg-Metadaten auch manuell auslösen. Weitere Informationen finden Sie unter Manuelles Auslösen der Iceberg-Metadatenkonvertierung.

Um Wartezeiten beim Schreiben im Zusammenhang mit der Iceberg-Metadatengenerierung zu vermeiden, können Delta-Tabellen mit häufigen Commits mehrere Delta-Commits in einem Iceberg-Commit bündeln.

Delta Lake stellt sicher, dass immer nur ein Prozess zur Generierung von Iceberg-Metadaten ausgeführt wird. Commits, die einen zweiten gleichzeitigen Prozess zur Generierung von Iceberg-Metadaten auslösen würden, werden zwar erfolgreich an Delta committet, lösen jedoch keine asynchrone Generierung von Iceberg-Metadaten aus. Dies verhindert kaskadierende Wartezeiten bei der Generierung von Metadaten für Workloads mit häufigen Commits (Sekunden bis Minuten zwischen Commits).

Weitere Informationen finden Sie unter Delta- und Iceberg-Tabellenversionen.

Überprüfen des Status der Generierung von Iceberg-Metadaten

UniForm fügt Unity Catalog- und Iceberg-Tabellenmetadaten die folgenden Felder hinzu, um den Status der Generierung von Metadaten nachzuverfolgen:

Metadatenfeld	Beschreibung
converted_delta_version	Die neueste Version der Delta-Tabelle, für die erfolgreich Iceberg-Metadaten generiert wurden.
converted_delta_timestamp	Der Zeitstempel des neuesten Delta-Commits, für den erfolgreich Iceberg-Metadaten generiert wurden.

In Azure Databricks können Sie diese Metadatenfelder wie folgt überprüfen:

• Überprüfen des Abschnitts Delta Uniform Iceberg, der von DESCRIBE EXTENDED table_name zurückgegeben wird
• Überprüfen von Tabellenmetadaten mit dem Katalog-Explorer
• Verwenden der REST-API zum Abrufen einer Tabelle

Informationen zum Überprüfen von Tabelleneigenschaften außerhalb von Azure Databricks finden Sie in der Dokumentation Ihres Iceberg-Reader-Clients. Für OSS Apache Spark können Sie diese Eigenschaften mithilfe der folgenden Syntax anzeigen:

SHOW TBLPROPERTIES <table-name>;

Manuelles Auslösen der Iceberg-Metadatenkonvertierung

Sie können die Generierung von Iceberg-Metadaten für die neueste Version der Delta-Tabelle manuell auslösen. Dieser Vorgang wird synchron ausgeführt. Das bedeutet, dass die in Iceberg verfügbaren Tabelleninhalte nach Abschluss die neueste Version der Delta-Tabelle widerspiegeln, die beim Starten des Konvertierungsprozesses verfügbar ist.

Dieser Vorgang sollte unter normalen Bedingungen nicht erforderlich sein, kann jedoch hilfreich sein, wenn folgende Probleme auftreten:

• Ein Cluster wird beendet, bevor die Metadaten erfolgreich automatisch generiert wurden.
• Ein Fehler oder Auftragsfehler unterbricht die Generierung der Metadaten.
• Ein Client, der die Generierung von UniForm-Iceberg-Metadaten nicht unterstützt, schreibt in die Delta-Tabelle.

Verwenden Sie die folgende Syntax, um die Generierung von Iceberg-Metadaten manuell auszulösen:

MSCK REPAIR TABLE <table-name> SYNC METADATA

Informationen finden Sie unter REPAIR TABLE.

Lesen mithilfe eines Metadaten-JSON-Pfads

Bei manchen Iceberg-Clients müssen Sie einen Pfad zu versionierten Metadatendateien angeben, um externe Iceberg-Tabellen zu registrieren. Jedes Mal, wenn UniForm eine neue Version der Delta-Tabelle in Iceberg konvertiert, wird dabei auch eine neue JSON-Metadatendatei erstellt.

Clients, die Metadaten-JSON-Pfade zum Konfigurieren von Iceberg verwenden, umfassen BigQuery. Konfigurationsdetails finden Sie in der Dokumentation des Iceberg-Reader-Clients.

Delta Lake speichert Iceberg-Metadaten im Tabellenverzeichnis nach folgendem Muster:

<table-path>/metadata/<version-number>-<uuid>.metadata.json

In Azure Databricks können Sie diesen Metadatenspeicherort wie folgt überprüfen:

• Überprüfen des Abschnitts Delta Uniform Iceberg, der von DESCRIBE EXTENDED table_name zurückgegeben wird
• Überprüfen von Tabellenmetadaten mit dem Katalog-Explorer
• Verwenden des folgenden Befehls mit der REST-API:

GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

Die Antwort enthält folgende Informationen:

{
    ...
          "delta_uniform_iceberg": {
              "metadata_location":  "<cloud-storage-uri>/metadata/v<version-number>-<uuid>.metadata.json"
    }
}

Wichtig

Pfadbasierte Iceberg-Reader-Clients erfordern möglicherweise das manuelle Updaten und Aktualisieren von Metadaten-JSON-Pfaden, um aktuelle Tabellenversionen zu lesen. Benutzer können beim Abfragen von Iceberg-Tabellen mit veralteten Versionen auf Fehler stoßen, da Parquet-Datendateien mithilfe von VACUUM aus der Delta-Tabelle entfernt werden.

Lesen mithilfe des Unity Catalog Iceberg-Katalogendpunkts

Einige Iceberg-Clients können eine Verbindung mit einem Iceberg-REST-Katalog herstellen. Unity Catalog bietet mithilfe des Endpunkts /api/2.1/unity-catalog/iceberg eine schreibgeschützte Implementierung der Iceberg-REST-Katalog-API für Delta-Tabellen mit aktiviertem UniForm an. Weitere Informationen zur Verwendung dieser REST-API finden Sie in der Iceberg-REST-API-Spezifikation.

Clients, die bekanntermaßen die Iceberg-Katalog-API unterstützen, sind Apache Spark, Flink und Trino. Sie müssen den Zugriff auf den zugrunde liegenden Cloudobjektspeicher konfigurieren, der die Delta-Tabelle mit aktiviertem UniForm enthält. Konfigurationsdetails finden Sie in der Dokumentation des Iceberg-Reader-Clients.

Sie müssen ein persönliches Azure Databricks-Zugriffstoken generieren und konfigurieren, damit andere Dienste eine Verbindung mit Unity Catalog herstellen können. Weitere Informationen finden Sie unter Authentifizierung für die Azure Databricks-Automatisierung – Übersicht.

Im Folgenden finden Sie ein Beispiel für die Einstellungen zum Konfigurieren von OSS Apache Spark zum Lesen des UniForm- als Iceberg-Format:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
"spark.sql.catalog.unity"="org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.unity.catalog-impl": "org.apache.iceberg.rest.RESTCatalog",
"spark.sql.catalog.unity.uri": "<api-root>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.unity.token":"<your_personal_access_token>",
"spark.sql.catalog.unity.io-impl": "org.apache.iceberg.aws.s3.S3FileIO

Ersetzen Sie die vollständige URL des Arbeitsbereichs, in dem Sie das persönliche Zugriffstoken für <api-root> generiert haben.

Hinweis

Beim Abfragen von Tabellen in Unity Catalog mit dieser Methode verwenden Objektbezeichner das folgende Muster:

unity.<catalog-name>.<schema-name>.<table-name>

Dieses Muster verwendet dieselben Namespaces mit drei Ebenen, die in Unity Catalog vorhanden sind, fügt jedoch zusätzlich das Präfix unity hinzu.

Delta- und Iceberg-Tabellenversionen

Sowohl Delta Lake als auch Iceberg ermöglichen Zeitreisenabfragen mithilfe von Tabellenversionen oder Zeitstempeln, die in Tabellenmetadaten gespeichert sind.

Im Allgemeinen werden Iceberg- und Delta-Tabellenversionen weder durch den Commit-Zeitstempel noch durch die Versions-ID ausgerichtet. Wenn Sie überprüfen möchten, welcher Version einer Delta-Tabelle eine bestimmte Version einer Iceberg-Tabelle entspricht, können Sie die entsprechenden Tabelleneigenschaften verwenden, die für die Iceberg-Tabelle festgelegt sind. Weitere Informationen finden Sie unter Überprüfen des Status der Generierung von Iceberg-Metadaten.

Begrenzungen

Es gelten die folgenden Einschränkungen:

• UniForm funktioniert nicht für Tabellen, bei denen Löschvektoren aktiviert sind. Weitere Informationen finden Sie unter Was sind Löschvektoren?.
• Delta-Tabellen mit UniForm-Aktivierung unterstützen keine VOID-Typen.
• Iceberg-Clients können nur aus UniForm lesen. Schreibvorgänge werden nicht unterstützt.
• Für Iceberg-Reader-Clients können unabhängig von UniForm individuelle Einschränkungen gelten. Weitere Informationen finden Sie in der Dokumentation des von Ihnen gewählten Clients.
• Die Empfänger der Delta-Freigabe können die Tabelle nur als Delta lesen, auch wenn UniForm aktiviert ist.

Der Datenfeed kann für Delta-Clients geändert werden, wenn UniForm aktiviert ist, aber in Iceberg nicht unterstützt wird:

Einige von UniForm verwendete Delta Lake-Tabellenfunktionen werden von einigen Delta Sharing-Reader-Clients nicht unterstützt. Weitere Informationen unter Sicheres Freigeben von Daten und KI-Ressourcen mithilfe von Delta Sharing.