Zugreifen auf Azure Databricks-Tabellen von Apache Iceberg-Clients

Mit dem Apache Iceberg REST-Katalog können unterstützte Clients wie Apache Spark, Apache Flink und Trino in Unity Catalog registrierte Iceberg-Tabellen auf Azure Databricks lesen und schreiben.

Eine vollständige Liste der unterstützten Integrationen finden Sie unter Unity Catalog-Integrationen.

Hinweis

Unity-Katalog verfügt auch über einen schreibgeschützten Iceberg REST-Katalog-API-Endpunkt. Dies ist ein veralteter Endpunkt. Siehe Lesen von Databricks-Tabellen aus Apache Iceberg Clients (veraltet)

Verwenden des Unity Catalog Iceberg-Katalogendpunkts

Unity Catalog stellt eine Implementierung der Iceberg REST-Katalog-API-Spezifikation bereit.

Konfigurieren des Zugriffs mithilfe des Endpunkts /api/2.1/unity-catalog/iceberg-rest. Details zur Verwendung dieser REST-API finden Sie in der Iceberg REST API-Spezifikation.

Hinweis

Azure Databricks hat für einige Iceberg-Leserclients den Verkauf von Anmeldeinformationen eingeführt. Databricks empfiehlt, den Verkauf von Anmeldeinformationen zum Steuern des Zugriffs auf Cloudspeicherorte für unterstützte Systeme zu nutzen. Siehe Unity Katalog-Anmeldedatenbereitstellung für den Zugriff auf externe Systeme und Zugriff auf Iceberg-Tabellen mit externen Systemen.

Wenn das Bereitstellen von Anmeldeinformationen für Ihren Client nicht unterstützt wird, müssen Sie den Zugriff vom Client auf den Speicherort konfigurieren, der die Dateien und Metadaten für die Delta- oder Iceberg-Tabelle enthält. Weitere Informationen zur Konfiguration finden Sie in der Dokumentation ihres Iceberg-Clients.

Anforderungen

Azure Databricks unterstützt den Iceberg REST-Katalogzugriff auf Tabellen als Teil des Unity-Katalogs. Sie müssen den Unity-Katalog in Ihrem Arbeitsbereich aktiviert haben, um diese Endpunkte zu verwenden. Auf die folgenden Tabellentypen kann mithilfe des Iceberg REST-Katalogs zugegriffen werden:

Thema Lesen Sie Schreiben
Verwalteter Iceberg Ja Ja
Fremde Eisberge Ja Nein
Verwaltetes Delta (mit aktiviertem Iceberg-Lesemodus) Ja Nein
Externes Delta (mit aktivierten Iceberg-Lesevorgängen) Ja Nein

Fremde Eisbergtabellen werden nicht automatisch aktualisiert, wenn Sie die Iceberg REST-Katalog-API zum Lesen von Tabellen verwenden. Zum Aktualisieren müssen Sie REFRESH FOREIGN TABLE ausführen, um die neueste Momentaufnahme zu lesen. Der Verkauf von Anmeldeinformationen in ausländischen Iceberg-Tabellen wird nicht unterstützt.

Hinweis

Sie müssen Delta-Tabellen so konfigurieren, dass sie über die Iceberg REST-Katalog-API zugänglich sind. Siehe Delta Lake-Tabellen mit Iceberg-Clients mithilfe von UniForm lesen.

Sie müssen die folgenden Konfigurationsschritte ausführen, um den Zugriff auf Lese- oder Schreibzugriff auf Azure Databricks-Tabellen von Iceberg-Clients mithilfe des Iceberg-REST-Katalogs zu konfigurieren:

Hinweis

Die Iceberg-Spezifikation lässt keine doppelten Datendateien innerhalb einer einzigen Tabellenspiegelung zu. Um dies zu verhindern, blockiert Unity Catalog, wenn dies erkannt wird, externe Engines daran, doppelte Datendateien in die Tabelle zu schreiben.

Hinweis

Informationen zum Lesen von Tabellen mit Zeilenfiltern oder Spaltenmasken , die von einem externen Iceberg-Client angefügt sind, finden Sie unter cross-engine attribute-based access controls (ABAC) für erforderliche Clientversionen und -konfigurationen.

Verwenden von Iceberg-Tabellen mit Apache Spark

Die folgenden Beispiele zeigen, wie Sie Apache Spark für den Zugriff auf Azure Databricks Tabellen über die Iceberg REST-Katalog-API konfigurieren. Azure Databricks unterstützt die OAuth- und PAT-Authentifizierung (Personal Access Token).

Um auf Tabellen in mehreren Katalogen zuzugreifen, müssen Sie jeden Katalog separat konfigurieren.

Hinweis

Sie müssen die Iceberg Spark Runtime JAR und das cloudspezifische Bundle JAR in Ihre Spark-Pakete einschließen. Die JAR-Laufzeitversion muss ihren Spark- und Scala-Versionen entsprechen. Beispiel: für Spark 3.5 mit Scala 2.12:

  • org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>

Außerdem das cloudspezifische Bundle:

  • 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. Diese JARs sind beim Zugriff auf Iceberg-Tabellen aus Azure Databricks Clustern nicht erforderlich.

OAuth-Authentifizierung

CLI

pyspark \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version> \
  --conf "spark.sql.catalog.<spark-catalog-name>=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.<spark-catalog-name>.type=rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.rest.auth.type=oauth2" \
  --conf "spark.sql.catalog.<spark-catalog-name>.uri=https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri=https://<workspace-url>/oidc/v1/token" \
  --conf "spark.sql.catalog.<spark-catalog-name>.credential=<oauth_client_id>:<oauth_client_secret>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.warehouse=<uc-catalog-name>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.scope=all-apis"

Python

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>") \
    .config("spark.sql.catalog.<spark-catalog-name>", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.<spark-catalog-name>.type", "rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.rest.auth.type", "oauth2") \
    .config("spark.sql.catalog.<spark-catalog-name>.uri", "https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri", "https://<workspace-url>/oidc/v1/token") \
    .config("spark.sql.catalog.<spark-catalog-name>.credential", "<oauth_client_id>:<oauth_client_secret>") \
    .config("spark.sql.catalog.<spark-catalog-name>.warehouse", "<uc-catalog-name>") \
    .config("spark.sql.catalog.<spark-catalog-name>.scope", "all-apis") \
    .getOrCreate()

Ersetzen Sie die folgenden Variablen:

  • <spark-catalog-name>: Der Name, den Sie dem Katalog in Ihrer Spark-Sitzung zuweisen möchten.
  • <uc-catalog-name>: Der Name des Katalogs im Unity-Katalog, der Ihre Tabellen enthält.
  • <oauth_client_id>: OAuth-Client-ID für den authentifizierenden Prinzipal.
  • <oauth_client_secret>: Geheimer OAuth-Clientschlüssel für den authentifizierenden Prinzipal.
  • <iceberg-version>: Die zu verwendende Iceberg-Version, z. B. 1.9.2.

PAT-Authentifizierung

CLI

pyspark \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version> \
  --conf "spark.sql.catalog.<spark-catalog-name>=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.<spark-catalog-name>.type=rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.uri=https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.token=<token>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.warehouse=<uc-catalog-name>"

Python

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>") \
    .config("spark.sql.catalog.<spark-catalog-name>", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.<spark-catalog-name>.type", "rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.uri", "https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.token", "<token>") \
    .config("spark.sql.catalog.<spark-catalog-name>.warehouse", "<uc-catalog-name>") \
    .getOrCreate()

Ersetzen Sie die folgenden Variablen:

  • <spark-catalog-name>: Der Name, den Sie dem Katalog in Ihrer Spark-Sitzung zuweisen möchten.
  • <uc-catalog-name>: Der Name des Katalogs im Unity-Katalog, der Ihre Tabellen enthält.
  • <token>: Ein persönliches Zugriffstoken (PAT) für die authentifizierende Entität. Siehe Authentifizieren mit persönlichen Zugriffstokens von Azure Databricks (Legacy).
  • <iceberg-version>: Die zu verwendende Iceberg-Version, z. B. 1.9.2.

Zugreifen auf Azure Databricks-Tabellen mit Snowflake

Snowflake bietet zwei Optionen für den Zugriff auf Tabellen über den Iceberg REST-Katalog: mithilfe der katalogverknüpften Datenbanken von Snowflake oder mithilfe externer Tabellen.

Konfigurieren Sie für beide Optionen zunächst eine Snowflake-Katalogintegration. Azure Databricks unterstützt die folgenden Authentifizierungsmethoden für Snowflake-Katalogintegrationen:

  • Bearertoken: Verwendet ein Azure Databricks Personal Access Token (PAT) oder OAuth-Token. Wird in allen Clouds unterstützt.
  • Entra-Dienstprinzipal OAuth (nur Azure): Verwendet einen Microsoft Entra ID-Dienstprinzipal, um sich direkt beim Entra-Tokenendpunkt zu authentifizieren.

Weitere Informationen zu den Snowflake-Authentifizierungsoptionen für REST-Katalogintegrationen finden Sie in der Snowflake-Dokumentation.

Snowflake mit Bearer-Token-Authentifizierung

Im folgenden Beispiel wird eine Snowflake-Katalogintegration mithilfe eines Bearertokens konfiguriert. Sie können ein persönliches Azure Databricks-Zugriffstoken (PERSONAL Access Token, PAT) oder ein OAuth-Token verwenden, das aus einem Azure Databricks-Dienstprinzipal generiert wird. Ausführliche Informationen zum Generieren von OAuth-Token finden Sie unter Autorisieren des Dienstprinzipalzugriffs auf Azure Databricks mit OAuth.

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest',
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

Ersetzen Sie die folgenden Variablen:

  • <catalog-integration-name>: Der Name, den Sie dem Katalog zuweisen möchten, der bei Snowflake registriert ist.
  • <uc-schema-name>: Der Name des Schemas im Unity-Katalog, auf das Sie zugreifen müssen.
  • <uc-catalog-name>: Der Name des Katalogs im Unity-Katalog, auf den Sie zugreifen müssen.
  • <workspace-url>: Die Azure Databricks-Arbeitsbereichs-URL. Zum Beispiel: https://cust-success.cloud.databricks.com oder https://adb-1234567890123456.12.azuredatabricks.net.
  • <token>: Ein persönliches Zugriffstoken (PAT) für den Benutzer, der die Integration konfiguriert.

Snowflake mit Entra-Dienstprinzipal OAuth

In Azure können Snowflake-Katalogintegrationen, die einen Entra-gesicherten Dienstprinzipal verwenden, den Azure Databricks OIDC-Tokenendpunkt (<workspace-url>/oidc/v1/token) nicht verwenden. Stattdessen müssen Sie sich direkt beim Microsoft Entra-Tokenendpunkt authentifizieren. Dies unterscheidet sich von dem OAuth-Ansatz, der für andere Iceberg-Clients (z. B. Apache Spark) in Azure verwendet wird.

Hinweis

Die Dokumentation von Snowflake kann darauf hinweisen, dass entra-ID nicht unterstützt wird. Die folgende Konfiguration verwendet Entra OAuth für den Azure Databricks-Ressourcenbereich und ist der unterstützte Pfad zum Lesen des Unity-Katalogs aus Snowflake in Azure.

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

Führen Sie die folgende SQL-Datei in Snowflake aus:

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = 'https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://login.microsoftonline.com/<azure-tenant-id>/oauth2/v2.0/token'
    OAUTH_CLIENT_ID = '<entra-client-id>'
    OAUTH_CLIENT_SECRET = '<entra-client-secret>'
    OAUTH_ALLOWED_SCOPES = ('2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default')
  )
  ENABLED = TRUE
  REFRESH_INTERVAL_SECONDS = 600;

Ersetzen Sie die folgenden Variablen:

  • <catalog-integration-name>: Der Name, den Sie dem Katalog zuweisen möchten, der bei Snowflake registriert ist.
  • <uc-schema-name>: Der Name des Schemas im Unity-Katalog, auf das Sie zugreifen müssen.
  • <uc-catalog-name>: Der Name des Katalogs im Unity-Katalog, auf den Sie zugreifen müssen.
  • <workspace-url>: Die Azure Databricks-Arbeitsbereichs-URL. Beispiel: adb-1234567890123456.12.azuredatabricks.net.
  • <azure-tenant-id>: Ihre Microsoft Entra-Mandanten-ID.
  • <entra-client-id>Die Client-ID oder Anwendungs-ID des Dienstprinzipals.
  • <entra-client-secret>: Ein Client-Geheimnis für den Entra-Service Principal.

Von Bedeutung

Der Bereich 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default ist die Azure Databricks-Anwendungs-ID, die in Entra registriert ist. Dies unterscheidet sich von dem all-apis Bereich, der beim Azure Databricks OIDC-Endpunkt verwendet wird. Die Verwendung des falschen Bereichs ist eine häufige Ursache für Authentifizierungsfehler beim Konfigurieren dieser Integration.

Nachdem Sie die Katalogintegration erstellt haben, folgen Sie der Snowflake-Dokumentation , um eine katalogverknüpfte Datenbank zu erstellen, um auf Ihre Tabellen zuzugreifen.

Weitere Informationen zum Erstellen und Verwalten von Entra-Dienstprinzipale für Azure Databricks finden Sie unter Authenticate with Microsoft Entra service principals.

Hinweis

Snowflake unterstützt keine Entra-Authentifizierung für Katalogintegrationen, die private Netzwerke (Azure Private Link) verwenden, um eine Verbindung mit Azure Databricks herzustellen. Die Verbindung mit dem Azure Databricks Iceberg REST-Katalogendpunkt muss beim Authentifizieren mit einem Entra-Dienstprinzipal öffentliche Netzwerke verwenden.

Katalogverknüpfte Datenbanken

Die katalogverknüpften Datenbanken von Snowflake werden automatisch mit Dem Unity-Katalog synchronisiert, um Schemas und Iceberg-Tabellen zu erkennen. Dies beseitigt die Notwendigkeit einer manuellen Metadatenaktualisierung.

Nachdem Sie eine Snowflake-Katalogintegration konfiguriert haben, lesen Sie die Snowflake-Dokumentation , um eine katalogverknüpfte Datenbank zu erstellen, um auf Ihre Tabellen zuzugreifen.

Von Bedeutung

Der Versuch, von Snowflake in schreibgeschützte Azure Databricks-Tabellen zu schreiben, kann zu Fehlern führen. Weitere Informationen zu unterstützten Vorgängen können Sie in der Snowflake-Dokumentation nachlesen.

Externe Tabellen

Alternativ können Sie nach dem Erstellen einer Snowflake-Katalogintegration externe Tabellen erstellen. Bei diesem Ansatz müssen Metadaten manuell aktualisiert werden, um Aktualisierungen anzuzeigen.

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = '<catalog-integration-name>'
  CATALOG_TABLE_NAME = '<uc-table-name>';

Verwenden von Azure Databricks-Tabellen mit PyIceberg

Um PyIceberg für den Zugriff auf Azure Databricks-Tabellen zu verwenden, müssen Sie PyIceberg mit den erforderlichen Abhängigkeiten installieren. PyIceberg erfordert pyarrow für Tabellenvorgänge wie das Lesen von Daten und das Überprüfen von Tabellenmetadaten. Installieren Sie PyIceberg mit dem Extra pyarrow:

pip install "pyiceberg[pyarrow]"

Hinweis

Wenn Sie die Installation nicht durchführen pyarrow, schlagen Vorgänge wie das Beschreiben oder Lesen von Tabellen fehl. Die vollständige Liste der optionalen Abhängigkeiten finden Sie in der PyIceberg-Dokumentation.

Nachfolgend sehen Sie ein Beispiel für die Konfigurationseinstellungen, mit denen PyIceberg auf Azure Databricks-Tabellen zugreifen kann, indem Sie eine Verbindung mit dem Iceberg REST-Katalog im Unity-Katalog herstellen:

catalog:
  unity_catalog:
    uri: https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest
    warehouse: <uc-catalog-name>
    token: <token>

Ersetzen Sie die folgenden Variablen:

  • <uc-catalog-name>: Der Name des Katalogs im Unity-Katalog, auf den Sie zugreifen müssen.
  • <token>: Ein persönliches Zugriffstoken (PAT) für den Benutzer, der die Integration konfiguriert.

Weitere Informationen finden Sie in der Dokumentation zur Konfiguration des PYIceberg REST-Katalogs.

Beispiel für REST-API-Curl

Im folgenden curl Beispiel wird eine Tabelle mit der REST-API geladen:

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

Die Antwort sieht wie folgt aus:

{
  "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 expires-at-ms Feld zeigt an, wann die Anmeldeinformationen ablaufen. Die Standardablaufzeit beträgt eine Stunde. Um die Leistung zu verbessern, sollte der Client die Anmeldeinformationen zwischenspeichern, bis sie ablaufen, bevor neue angefordert werden.

  • Last updated on