Freigeben über

UniForm IcebergCompatV1 (Legacy)

  • Artikel

Wichtig

Diese Dokumentation wurde eingestellt und wird unter Umständen nicht aktualisiert. Die in diesem Inhalt erwähnten Produkte, Dienste oder Technologien werden nicht mehr unterstützt. Weitere Informationen finden Sie unter Verwenden von UniForm zum Lesen von Delta-Tabellen mit Iceberg-Clients.

Wichtig

Dieses Feature befindet sich in Databricks Runtime 13.2 und höheren Versionen in Public Preview.

Das universelle Delta-Format (UniForm) ermöglicht das Lesen von Delta-Tabellen mit Iceberg-Reader-Clients.

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.

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 13.2 oder höher verwenden.

Aktivieren von Delta UniForm

Wichtig

Durch Aktivieren von Delta UniForm wird das Delta-Tabellenfeature IcebergCompatV1, 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 13.2 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.

Die folgende Tabelleneigenschaft aktiviert die UniForm-Unterstützung für Iceberg. iceberg ist der einzig gültige Wert.

'delta.universalFormat.enabledFormats' = 'iceberg'

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

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

Wenn Sie eine neue Tabelle mit einer CTAS-Anweisung erstellen, müssen Sie die Spaltenzuordnung manuell angeben wie im folgenden Beispiel gezeigt:

CREATE TABLE T
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.universalFormat.enabledFormats' = 'iceberg')
AS
  SELECT * FROM source_table;

Wenn Sie eine vorhandene Tabelle ändern, müssen Sie wie im folgenden Beispiel alle diese Eigenschaften angeben:

ALTER TABLE T SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV1' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

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 mithilfe des Katalog-Explorers überprüfen. Diese Felder und Werte werden auch zurückgegeben, wenn Sie die REST-API zum Abrufen einer Tabelle verwenden.

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

Sie können den Pfad dieser Datei mithilfe des Katalog-Explorers ermitteln. In Tabellen mit aktiviertem UniForm sind die Details für die Delta-Tabelle in einem Feld für den Speicherort der Iceberg-Metadaten enthalten.

Sie können auch die REST-API verwenden, um alle Details für eine Tabelle einschließlich des Speicherorts der Metadaten abzurufen. Verwenden Sie den folgenden Befehl:

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. Siehe Authentifizierung des Zugriffs auf Azure Databricks-Ressourcen.

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 aktiviertem UniForm unterstützen die Typen LIST, MAPund VOID nicht.
  • 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.
  • Iceberg Reader-Clients, Version 1.2.0 und niedriger, unterstützen den von Apache Spark geschriebenen Zeitstempeltyp INT96 nicht. Verwenden Sie den folgenden Code in Notebooks, die in UniForm-Tabellen schreiben, um diese Einschränkung zu umgehen: spark.conf.set(“spark.sql.parquet.outputTimestampType”, “TIMESTAMP_MICROS”)
  • Die Public Preview-Version des Unity Catalog Iceberg-Endpunkts ist nicht für umfangreiche Produktionsworkloads vorgesehen. Es kann zu Ratenbegrenzungen kommen, wenn Sie einen Schwellenwert von 5 Abfragen pro Sekunde überschreiten.

Die folgenden Delta Lake-Features funktionieren für Delta-Clients, wenn UniForm aktiviert ist, sie aber in Iceberg nicht unterstützt werden:

  • Ändern des Datenfeeds
  • Delta Sharing