Freigeben über

Verwenden von UniForm zum Lesen von Delta-Tabellen mit Iceberg-Clients

  • Artikel

Das universelle Delta Lake-Format (UniForm) ermöglicht das Lesen von Delta-Tabellen mit Iceberg-Readerclients. 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).

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 Iceberg verwendet als Komprimierungscodec für zugrunde liegende Parquet-Datendateien Zstandard anstelle von Snappy.

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.

Wie funktioniert UniForm?

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. Eine einzelne Kopie der Datendateien kann für mehrere Formate verwendet werden.

Anforderungen

Um UniForm Iceberg zu aktivieren, müssen die folgenden Anforderungen erfüllt sein:

  • 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 Iceberg aktiviert ist.

Verwenden Sie REORG, um Löschvektoren zu deaktivieren und zu löschen, wenn Sie UniForm Iceberg für eine vorhandene Tabelle mit aktiven Löschvektoren aktivieren. Weitere Informationen finden Sie unter Aktivieren oder Upgraden mithilfe von REORG.

Aktivieren von UniForm Iceberg

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. Upgrades auf Delta Lake-Reader- und Writer-Protokollversionen können nicht rückgängig gemacht werden.

Sie müssen die folgenden Tabelleneigenschaften festlegen, um UniForm Iceberg zu aktivieren:

'delta.enableIcebergCompatV2' = '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.

Eine Liste der Einschränkungen finden Sie unter Einschränkungen.

Aktivieren während der Tabellenerstellung

Spaltenzuordnung muss für die Verwendung von UniForm Iceberg aktiviert sein. Diese ist automatisch aktiviert, wenn Sie UniForm während der Tabellenerstellung aktivieren, wie im folgenden Beispiel gezeigt wird:

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

Aktivieren durch Ändern einer vorhandenen Tabelle

In Databricks Runtime 15.4 LTS und höher können Sie UniForm Iceberg mithilfe der folgenden Syntax in einer vorhandenen Tabelle aktivieren oder upgraden:

ALTER TABLE table_name SET TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

Aktivieren oder Upgraden mithilfe von REORG

Sie können REORG verwenden, um UniForm Iceberg zu aktivieren und zugrunde liegende Datendateien wie im folgenden Beispiel neu zu schreiben:

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

Verwenden Sie REORG, wenn eine der folgenden Bedingungen zutrifft:

  • In Ihrer Tabelle sind Löschvektoren aktiviert.
  • Sie haben zuvor die IcebergCompatV1-Version von UniForm Iceberg aktiviert.
  • Sie müssen aus Iceberg-Engines lesen, die keine Parquet-Dateien im Hive-Stil wie Athena oder Redshift unterstützen.

Wann generiert UniForm Iceberg-Metadaten?

Azure Databricks löst die Metadatengenerierung asynchron aus, nachdem eine Delta Lake-Schreibtransaktion abgeschlossen wurde. Dieser Metadatengenerierungsprozess verwendet dieselbe Computeressource, mit der die Delta-Transaktion abgeschlossen wurde.

Hinweis

Sie können die Generierung von Iceberg-Metadaten auch manuell auslösen. Weitere Informationen finden Sie unter Manuelles Auslösen der Iceberg-Metadatenkonvertierung.

Um Schreiblatenzen bei der Metadatengenerierung zu vermeiden, können Delta-Tabellen mit häufigen Commits mehrere Delta-Commits in einen an Iceberg-Metadaten bündeln.

Delta Lake stellt sicher, dass in einer Computeressource immer nur ein Metadatengenerierungsprozess gleichzeitig ausgeführt wird. Commits, die einen zweiten gleichzeitigen Metadatengenerierungsprozess 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.

Delta- und Iceberg-Tabellenversionen

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

Im Allgemeinen stimmen Delta-Tabellenversionen weder bei den Commit-Zeitstempeln noch den Versions-IDs mit Iceberg-Versionen überein. Wenn Sie überprüfen möchten, welche Version einer Delta-Tabelle einer bestimmten Version einer Iceberg-Tabelle entspricht, können Sie die entsprechenden Tabelleneigenschaften verwenden. Weitere Informationen finden Sie unter Überprüfen des Status der Generierung von Iceberg-Metadaten.

Ü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

Manche Iceberg-Clients erfodern, dass 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. Konfigurationsdetails finden Sie in der Dokumentation des Iceberg-Reader-Clients.

Authentifizierung und Autorisierung

Es gibt zwei Anforderungen für den Zugriff auf Daten, die im Unity Catalog mithilfe des api/2.1/unity-catalog/iceberg-Endpunkts von externen Diensten registriert sind:

Beispiel für eine Apache Spark-Konfiguration

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.type": "rest",
"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.warehouse": "<uc_catalog_name>"

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

Beachten Sie beim Abfragen von Tabellen im Unity-Katalog mithilfe von Spark-Konfigurationen Folgendes:

  • Objekt-IDs verwenden das Muster unity.<schema-name>.<table-name>.

    Dieses Muster verwendet den gleichen dreistufigen Namespace, der im Unity-Katalog verwendet wird, aber mit dem Katalognamen ersetzt durch unity.

  • Sie brauchen "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" nur, wenn Sie Iceberg-spezifische gespeicherte Prozeduren ausführen.

  • Wenn Sie einen Cloudanbieter für den Speicher verwenden, müssen Sie die cloudspezifischen Iceberg-Bundle-JARS als Spark-Pakete hinzufügen:

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    Ausführliche Informationen finden Sie in der Dokumentation zur Iceberg AWS-Integration für Spark.

Beispiel für eine REST-API

Sie können auch einen REST-API-Aufruf wie den in diesem Curll-Beispiel verwenden, um eine Tabelle zu laden:

curl -X GET -H "Authentication: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

Sie erhalten eine Antwort wie diese:

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

Hinweis

Das Feld expires-at-ms in der Antwort gibt die Ablaufzeit der Anmeldeinformationen an und hat eine Standardablaufzeit von einer Stunde. Um eine bessere Leistung zu erzielen, müssen Sie die Anmeldeinformationen bis zur Ablaufzeit zwischenspeichern, bevor Sie eine neue anfordern.

Begrenzungen

Für alle UniForm-Tabellen 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.
  • Einige von UniForm Iceberg verwendete Delta Lake-Tabellenfeatures werden von einigen Delta Sharing-Readerclients nicht unterstützt. Weitere Informationen finden Sie unter Was ist Delta Sharing?.

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