Freigeben über

Verwenden von Iceberg-Tabellen mit OneLake

  • Artikel

In Microsoft OneLake können Sie Verknüpfungen zu Ihren Apache Iceberg-Tabellen erstellen, damit diese für die verschiedensten Fabric-Workloads verwendet werden können. Diese Funktionalität wird durch ein Feature namens Metadatenvirtualisierungermöglicht. Hiermit können Iceberg-Tabellen aus der Perspektive der Verknüpfung als Delta Lake-Tabellen interpretiert werden. Wenn Sie eine Verknüpfung zu einem Iceberg-Tabellenordner erstellen, generiert OneLake automatisch die entsprechenden Delta Lake-Metadaten (das Delta-Protokoll) für diese Tabelle, wodurch die Delta Lake-Metadaten über die Verknüpfung zugänglich sind.

Wichtig

Dieses Feature befindet sich in der Vorschauphase.

Diagramm zur Veranschaulichung der Delta Lake-Metadatenvirtualisierung

Dieser Artikel enthält Anleitungen zum Schreiben von Iceberg-Tabellen von Snowflake nach OneLake. Dieses Feature ist jedoch so konzipiert, dass es mit allen Iceberg-Tabellen funktioniert, die Parquet-Datendateien enthalten.

Erstellen einer Tabellenverknüpfung zu einer Iceberg-Tabelle

Wenn Sie bereits über eine Iceberg-Tabelle an einem Speicherort verfügen, der von OneLake-Verknüpfungen unterstützt wird, führen Sie die folgenden Schritte aus, um eine Verknüpfung zu erstellen und die Iceberg-Tabelle im Delta Lake-Format anzuzeigen.

  1. Suchen Sie die Iceberg-Tabelle. Suchen Sie den Speicherort der Iceberg-Tabelle. Das kann Azure Data Lake Storage, OneLake, Amazon S3, Google Cloud Storage oder ein S3-kompatibler Speicherdienst sein.

    Hinweis

    Wenn Sie Snowflake verwenden und nicht sicher sind, wo die Iceberg-Tabelle gespeichert ist, können Sie die folgende Anweisung ausführen, um den Speicherort der Iceberg-Tabelle anzuzeigen.

    SELECT SYSTEM$GET_ICEBERG_TABLE_INFORMATION('<table_name>');

    Wenn Sie diese Anweisung ausführen, wird ein Pfad zur Metadatendatei für die Iceberg-Tabelle zurückgegeben. Dieser Pfad gibt an, in welchem Speicherkonto die Iceberg-Tabelle enthalten ist. Nachfolgend sehen Sie ein Beispiel mit den relevanten Informationen, um den Pfad einer in Azure Data Lake Storage gespeicherten Iceberg-Tabelle zu finden:

    {"metadataLocation":"azure://<storage_account_path>/<path_within_storage>/<table_name>/metadata/00001-389700a2-977f-47a2-9f5f-7fd80a0d41b2.metadata.json","status":"success"}

    Der Iceberg-Tabellenordner muss einen Ordner metadata enthalten, der selbst mindestens eine Datei enthält, die auf .metadata.json endet.

  2. Erstellen Sie im Fabric-Lakehouse eine neue Verknüpfung im Bereich „Tabellen“ eines Lakehouse, das nicht für Schemas aktiviert ist.

    Hinweis

    Wenn im Ordner „Tabellen“ des Lakehouse Schemas wie dbo angezeigt werden, ist das Lakehouse für Schemas aktiviert und noch nicht mit diesem Feature kompatibel.

    Screenshot des Menüelements zum Erstellen von Verknüpfungen unter „Tabellen“

  3. Wählen Sie für den Zielpfad der Verknüpfung den Iceberg-Tabellenordner aus. Der Iceberg-Tabellenordner enthält die Ordner metadata und data.

  4. Sobald die Verknüpfung erstellt wurde, sollte diese Tabelle automatisch als Delta Lake-Tabelle im Lakehouse angezeigt werden und kann in Fabric verwendet werden.

    Screenshot der erfolgreichen Erstellung einer Verknüpfung zu einer Iceberg-Tabelle

    Wenn die neue Verknüpfung zur Iceberg-Tabelle nicht als verwendbare Tabelle angezeigt wird, überprüfen Sie den Abschnitt Problembehandlung.

Schreiben einer Iceberg-Tabelle in OneLake mithilfe von Snowflake

Wenn Sie Snowflake in Azure verwenden, können Sie Iceberg-Tabellen in OneLake schreiben, indem Sie die folgenden Schritte ausführen:

  1. Stellen Sie sicher, dass sich die Fabric-Kapazität am selben Azure-Speicherort wie die Snowflake-Instanz befindet.

    Ermitteln Sie den Standort der Fabric-Kapazität, die dem Fabric-Lakehouse zugeordnet ist. Öffnen Sie die Einstellungen des Fabric-Arbeitsbereichs, in dem das Lakehouse enthalten ist.

    Screenshot der Fabric-Kapazitätsregion

    Überprüfen Sie in der unteren linken Ecke der Schnittstelle für das Snowflake-Konto in Azure die Azure-Region des Snowflake-Kontos.

    Screenshot der Region des Snowflake-Kontos

    Wenn diese Regionen nicht identisch sind, müssen Sie eine andere Fabric-Kapazität verwenden, die sich in derselben Region wie das Snowflake-Konto befindet.

  2. Öffnen Sie das Menü für den Bereich „Dateien“ des Lakehouse, wählen Sie „Eigenschaften“ aus, und kopieren Sie die URL (den HTTPS-Pfad) dieses Ordners.

    Screenshot des Menüelements „Eigenschaften“

  3. Ermitteln Sie Ihre Fabric-Mandanten-ID. Wählen Sie Ihr Benutzerprofil in der oberen rechten Ecke der Fabric-Benutzeroberfläche aus, und zeigen Sie auf die Infoblase neben Ihrem Mandantennamen. Kopieren Sie die Tenant ID (Mandanten-ID).

    Screenshot der Mandanten-ID

  4. Richten Sie in Snowflake das EXTERNAL VOLUME mithilfe des Pfads zum Ordner „Dateien“ im Lakehouse ein. Hier finden Sie weitere Informationen zum Einrichten externer Snowflake-Volumes.

    Hinweis

    Das URL-Schema für Snowflake muss azure:// lauten. Achten Sie daher darauf, https:// in azure:// zu ändern.

    CREATE OR REPLACE EXTERNAL VOLUME onelake_exvol
STORAGE_LOCATIONS =
(
    (
        NAME = 'onelake_exvol'
        STORAGE_PROVIDER = 'AZURE'
        STORAGE_BASE_URL = 'azure://<path_to_Files>/icebergtables'
        AZURE_TENANT_ID = '<Tenant_ID>'
    )
);

    In diesem Beispiel werden alle Tabellen, die mit diesem externen Volume erstellt wurden, im Fabric-Lakehouse im Ordner Files/icebergtables gespeichert.

  5. Nachdem das externe Volume erstellt wurde, führen Sie den folgenden Befehl aus, um die Zustimmungs-URL und den Namen der Anwendung abzurufen, die Snowflake zum Schreiben in OneLake verwendet. Diese Anwendung wird allen anderen externen Volumes im Snowflake-Konto verwendet.

    DESC EXTERNAL VOLUME onelake_exvol;

    Die Ausgabe dieses Befehls gibt die Eigenschaften AZURE_CONSENT_URL und AZURE_MULTI_TENANT_APP_NAME zurück. Notieren Sie sich beide Werte. Der Name der mehrinstanzenfähigen Azure-App sieht wie folgt aus: <name>_<number>. Sie müssen jedoch nur den <name>-Teil notieren.

  6. Öffnen Sie die Zustimmungs-URL aus dem vorherigen Schritt in einer neuen Browserregisterkarte. Wenn Sie fortfahren möchten, stimmen Sie den erforderlichen Anwendungsberechtigungen zu, wenn Sie dazu aufgefordert werden.

  7. Kehren Sie zu Fabric zurück, öffnen Sie den Arbeitsbereich, und wählen Sie Zugriff verwalten und dann Fügen Sie Personen oder Gruppen hinzu aus. Erteilen Sie der Anwendung, die vom externen Snowflake-Volume verwendet wird, die Berechtigungen, die zum Schreiben von Daten in Lakehouses in Ihrem Arbeitsbereich erforderlich sind. Es wird empfohlen, die Rolle Mitwirkender zu gewähren.

  8. Kehren Sie zu Snowflake zurück, und verwenden Sie das neue externe Volume, um eine Iceberg-Tabelle zu erstellen.

    CREATE OR REPLACE ICEBERG TABLE MYDATABASE.PUBLIC.Inventory (
    InventoryId int,
    ItemName STRING
)
EXTERNAL_VOLUME = 'onelake_exvol'
CATALOG = 'SNOWFLAKE'
BASE_LOCATION = 'Inventory/';

    Mit dieser Anweisung wird ein neuer Iceberg-Tabellenordner namens „Bestand“ innerhalb des Ordnerpfads erstellt, der im externen Volume definiert ist.

  9. Fügen Sie einige Daten zur Iceberg-Tabelle hinzu.

    INSERT INTO MYDATABASE.PUBLIC.Inventory
VALUES
(123456,'Amatriciana');

  10. Schließlich können Sie im Bereich „Tabellen“ desselben Lakehouse eine OneLake-Verknüpfung zur Iceberg-Tabelle erstellen. Über diese Verknüpfung wird die Iceberg-Tabelle als Delta Lake-Tabelle angezeigt, die in Fabric-Workloads verwendet werden kann.

Problembehandlung

Anhand der folgenden Tipps können Sie sicherstellen, dass die Iceberg-Tabellen mit diesem Feature kompatibel sind:

Überprüfen der Ordnerstruktur der Iceberg-Tabelle

Öffnen Sie den Iceberg-Ordner in Ihrem bevorzugten Speicher-Explorertool, und überprüfen Sie die Verzeichnisauflistung des Iceberg-Ordners am ursprünglichen Speicherort. Sie sollten eine Ordnerstruktur wie im folgenden Beispiel sehen:

../
|-- MyIcebergTable123/
    |-- data/
        |-- snow_A5WYPKGO_2o_APgwTeNOAxg_0_1_002.parquet
        |-- snow_A5WYPKGO_2o_AAIBON_h9Rc_0_1_003.parquet
    |-- metadata/
        |-- 00000-1bdf7d4c-dc90-488e-9dd9-2e44de30a465.metadata.json
        |-- 00001-08bf3227-b5d2-40e2-a8c7-2934ea97e6da.metadata.json
        |-- 00002-0f6303de-382e-4ebc-b9ed-6195bd0fb0e7.metadata.json
        |-- 1730313479898000000-Kws8nlgCX2QxoDHYHm4uMQ.avro
        |-- 1730313479898000000-OdsKRrRogW_PVK9njHIqAA.avro
        |-- snap-1730313479898000000-9029d7a2-b3cc-46af-96c1-ac92356e93e9.avro
        |-- snap-1730313479898000000-913546ba-bb04-4c8e-81be-342b0cbc5b50.avro

Wenn der Metadatenordner oder die Dateien mit den in diesem Beispiel gezeigten Erweiterungen nicht angezeigt werden, verfügen Sie möglicherweise nicht über eine ordnungsgemäß generierte Iceberg-Tabelle.

Überprüfen des Konvertierungsprotokolls

Wenn eine Iceberg-Tabelle als Delta Lake-Tabelle virtualisiert wird, wird im Verknüpfungsordner der Ordner _delta_log/ angezeigt. Dieser Ordner enthält nach erfolgreicher Konvertierung die Metadaten des Delta Lake-Formats (das Delta-Protokoll).

Dieser Ordner enthält auch die Datei latest_conversion_log.txt, die Informationen darüber enthält, ob die letzte Konvertierung erfolgreich war oder fehlgeschlagen ist.

Wenn Sie den Inhalt dieser Datei nach dem Erstellen der Verknüpfung anzeigen möchten, öffnen Sie im Bereich „Tabellen“ des Lakehouse das Menü für die Verknüpfung der Iceberg-Tabelle, und wählen Sie Dateien anzeigen aus.

Screenshot des Menüelements „Dateien anzeigen“

Sie sollten eine Struktur wie im folgenden Beispiel sehen:

Tables/
|-- MyIcebergTable123/
    |-- data/
        |-- <data files>
    |-- metadata/
        |-- <metadata files>
    |-- _delta_log/   <-- Virtual folder. This folder doesn't exist in the original location.
        |-- 00000000000000000000.json
        |-- latest_conversion_log.txt   <-- Conversion log with latest success/failure details.

Öffnen Sie die Protokolldatei für die Konvertierung, um Details zur letzten Konvertierungszeit oder zu Fehlern anzuzeigen. Wenn keine Protokolldatei für die Konvertierung angezeigt wird, wurde kein Konvertierungsversuch unternommen.

Wenn kein Konvertierungsversuch unternommen wurde

Wenn keine Protokolldatei für die Konvertierung angezeigt wird, wurde kein Konvertierungsversuch unternommen. Nachfolgend sind zwei häufige Gründe aufgeführt, warum kein Konvertierungsversuch unternommen wird:

  • Die Verknüpfung wurde nicht an der richtigen Stelle erstellt.

    Damit eine Verknüpfung zu einer Iceberg-Tabelle in das Delta Lake-Format konvertiert werden kann, muss die Verknüpfung direkt unter dem Ordner „Tabellen“ eines Lakehouse platziert werden, das nicht für Schemas aktiviert ist. Sie dürfen die Verknüpfung nicht im Bereich „Dateien“ oder unter einem anderen Ordner platzieren, wenn die Tabelle automatisch als Delta Lake-Tabelle virtualisiert werden soll.

    Screenshot der richtigen Platzierung einer Verknüpfung im Ordner „Tabellen“

  • Der Zielpfad der Verknüpfung ist nicht der Iceberg-Ordnerpfad.

    Wenn Sie die Verknüpfung erstellen, muss der Ordnerpfad, den Sie im Zielspeicherort auswählen, der Iceberg-Tabellenordner sein. Dieser Ordner enthält die Dateien metadata und data.

    Screenshot des Inhalts eines Verknüpfungszielpfads während der Erstellung der Verknüpfung

Einschränkungen und Aspekte

Beachten Sie die folgenden temporären Einschränkungen, wenn Sie dieses Feature verwenden:

  • Unterstützte Datentypen

    Die folgenden Typen für Iceberg-Spaltendaten werden mit diesem Feature den entsprechenden Delta Lake-Typen zugeordnet.

    Iceberg-Spaltentyp Delta Lake-Spaltentyp Kommentare
    int integer
    long long Siehe Problem mit Typbreite.
    float float
    double double Siehe Problem mit Typbreite.
    decimal(P, S) decimal(P, S) Siehe Problem mit Typbreite.
    boolean boolean
    date date
    timestamp timestamp_ntz Der Iceberg-Datentyp timestamp enthält keine Zeitzoneninformationen. Der Delta Lake-Typ timestamp_ntz wird in Fabric-Workloads nicht vollständig unterstützt. Wir empfehlen die Verwendung von Zeitstempeln, die Zeitzonen enthalten.
    timestamptz timestamp Um diesen Typ zu verwenden, geben Sie in Snowflake bei der Erstellung von Iceberg-Tabellen timestamp_ltz als Spaltentyp an. Hier finden Sie weitere Informationen zu den Iceberg-Datentypen, die in Snowflake unterstützt werden.
    string string
    binary binary

  • Problem mit Typbreite

    Wenn Sie Snowflake verwenden, um die Iceberg-Tabelle zu schreiben, und die Tabelle den Spaltentyp INT64, double oder Decimal mit Genauigkeit >= 10 enthält, kann die resultierende virtuelle Delta Lake-Tabelle möglicherweise nicht von allen Fabric-Engines verwendet werden. Ihnen wird möglicherweise der folgende Fehler angezeigt:

    Parquet column cannot be converted in file ... Column: [ColumnA], Expected: decimal(18,4), Found: INT32.

    Wir arbeiten an der Behebung dieses Problems.

    Problemumgehung: Wenn Sie die Benutzeroberfläche für die Lakehouse-Tabellenvorschau verwenden und dieses Problem sehen, können Sie den Fehler beheben, indem Sie zur Ansicht des SQL-Endpunkts wechseln (obere rechte Ecke, Lakehouse-Ansicht auswählen, zu SQL-Endpunkt wechseln) und von dort aus eine Vorschau der Tabelle anzeigen. Wenn Sie dann wieder zur Lakehouse-Ansicht wechseln, sollte die Tabellenvorschau ordnungsgemäß angezeigt werden.

    Wenn Sie ein Spark-Notebook oder einen Spark-Auftrag ausführen und dieses Problem auftritt, können Sie den Fehler beheben, indem Sie die Spark-Konfiguration spark.sql.parquet.enableVectorizedReader auf falsefestlegen. Hier ist ein Beispiel für einen PySpark-Befehl, der in einem Spark-Notebook ausgeführt werden kann:

    spark.conf.set("spark.sql.parquet.enableVectorizedReader","false")

  • Metadatenspeicher der Iceberg-Tabelle ist nicht portierbar

    Die Metadatendateien einer Iceberg-Tabelle verweisen unter Verwendung absoluter Pfadverweise aufeinander. Wenn Sie den Ordnerinhalt einer Iceberg-Tabelle an einen anderen Speicherort kopieren oder verschieben, ohne die Iceberg-Metadatendateien neu zu schreiben, wird die Tabelle für Iceberg-Reader unlesbar, einschließlich dieses OneLake-Features.

    Problemumgehung:

    Wenn Sie die Iceberg-Tabelle an einen anderen Ort verschieben müssen, um dieses Feature zu verwenden, verwenden Sie das Tool, mit dem die Iceberg-Tabelle ursprünglich geschrieben wurde, um eine neue Iceberg-Tabelle am gewünschten Ort zu schreiben.

  • Iceberg-Tabellen müssen tiefer als die Stammebene sein

    Der Iceberg-Tabellenordner im Speicher muss sich in einem Verzeichnis befinden, das tiefer als Bucket- oder Containerebene ist. Iceberg-Tabellen, die direkt im Stammordner eines Buckets oder Containers gespeichert sind, werden im Delta Lake-Format möglicherweise nicht virtualisiert.

    Wir arbeiten an einer Verbesserung, um diese Anforderung zu entfernen.

    Problemumgehung:

    Stellen Sie sicher, dass alle Iceberg-Tabellen in einem Verzeichnis gespeichert werden, das tiefer als der Stammordner eines Buckets oder Containers ist.

  • Iceberg-Tabellenordner dürfen nur eine Gruppe von Metadatendateien enthalten

    Wenn Sie eine Iceberg-Tabelle in Snowflake ablegen und neu erstellen, werden die Metadatendateien nicht bereinigt. Dieses Verhalten unterstützt das UNDROP-Feature in Snowflake. Da die Verknüpfung jedoch direkt auf einen Ordner verweist und dieser Ordner jetzt mehrere Metadatendateien enthält, kann die Tabelle erst konvertiert werden, wenn Sie die Metadatendateien der alten Tabelle entfernen.

    Derzeit wird in diesem Szenario ein Konvertierungsversuch unternommen. Das kann dazu führen, dass alte Tabelleninhalte und Schemainformationen in der virtualisierten Delta Lake-Tabelle angezeigt werden.

    Wir arbeiten daran, das Problem zu beheben, damit die Konvertierung fehlschlägt, wenn im Metadatenordner der Iceberg-Tabelle mehrere Metadatendateien gefunden werden.

    Problemumgehung:

    So stellen Sie sicher, dass die konvertierte Tabelle die richtige Version der Tabelle widerspiegelt:

    • Stellen Sie sicher, dass Sie nicht mehr als eine Iceberg-Tabelle im selben Ordner speichern.
    • Bereinigen Sie nach dem Ablegen der Tabelle alle Inhalte eines Iceberg-Tabellenordners, bevor Sie die Tabelle neu erstellen.

  • Metadatenänderungen werden nicht sofort widergespiegelt

    Wenn Sie Metadatenänderungen an der Iceberg-Tabelle vornehmen, z. B. eine Spalte hinzufügen, eine Spalte löschen, eine Spalte umbenennen oder einen Spaltentyp ändern, wird die Tabelle möglicherweise erst dann erneut konvertiert, wenn eine Datenänderung vorgenommen wird, z. B. das Hinzufügen einer Datenzeile.

    Wir arbeiten daran, das Problem zu beheben, damit die richtige Metadatendatei ausgewählt wird, die die neueste Metadatenänderung enthält.

    Problemumgehung:

    Nachdem Sie die Schemaänderung an der Iceberg-Tabelle vorgenommen haben, fügen Sie eine Datenzeile hinzu, oder nehmen Sie eine andere Änderung an den Daten vor. Nach dieser Änderung sollte in Fabric die neueste Ansicht der Tabelle angezeigt werden.

  • Für Schemas aktivierte Arbeitsbereiche werden noch nicht unterstützt

    Wenn Sie eine Iceberg-Verknüpfung in einem Lakehouse erstellen, das für Schemas aktiviert ist, wird für diese Verknüpfung keine Konvertierung durchgeführt.

    Wir arbeiten an einer Verbesserung, um diese Einschränkung zu entfernen.

    Problemumgehung:

    Verwenden Sie mit diesem Feature ein Lakehouse, das nicht für Schemas aktiviert ist. Sie können diese Einstellung während der Lakehouse-Erstellung konfigurieren.

  • Einschränkungen der Regionsverfügbarkeit

    Dieses Feature ist in den folgenden Regionen noch nicht verfügbar:

    • Katar, Mitte
    • Norwegen, Westen

    Problemumgehung:

    Arbeitsbereiche, die mit Fabric-Kapazitäten in anderen Regionen verbunden sind, können dieses Feature verwenden. Hier finden Sie die vollständige Liste der Regionen, in denen Microsoft Fabric verfügbar ist.

  • Private Links werden nicht unterstützt

    Dieses Feature wird derzeit für Mandanten oder Arbeitsbereiche mit aktivierten privaten Links nicht unterstützt.

    Wir arbeiten an einer Verbesserung, um diese Einschränkung zu entfernen.

  • Einschränkung der Tabellengröße

    Die von diesem Feature unterstützte Größe der Iceberg-Tabelle ist vorübergehend eingeschränkt. Es werden maximal 5.000 Parquet-Datendateien oder etwa 1 Milliarde Zeilen unterstützt, je nachdem, welcher Grenzwert zuerst erreicht wird.

    Wir arbeiten an einer Verbesserung, um diese Einschränkung zu entfernen.

  • OneLake-Verknüpfungen müssen sich in derselben Region befinden

    Es gibt eine temporäre Einschränkung für die Verwendung dieses Features mit Verknüpfungen, die auf OneLake-Speicherorte verweisen: Der Zielspeicherort der Verknüpfung muss sich in derselben Region wie die Verknüpfung selbst befinden.

    Wir arbeiten an einer Verbesserung, um diese Anforderung zu entfernen.

    Problemumgehung:

    Wenn Sie eine OneLake-Verknüpfung zu einer Iceberg-Tabelle in einem anderen Lakehouse haben, stellen Sie sicher, dass das andere Lakehouse mit einer Kapazität in derselben Region verbunden ist.

Zugehöriger Inhalt