Brug Iceberg-tabeller med OneLake

I OneLake kan du problemfrit arbejde med tabeller i både Delta Lake og Apache Iceberg formater.

Denne fleksibilitet aktiveres via virtualisering af metadata, en funktion, der gør det muligt at fortolke Iceberg-tabeller som Delta Lake-tabeller og omvendt. Du kan skrive Iceberg-tabeller direkte eller oprette genveje til dem, hvilket gør disse tabeller tilgængelige på tværs af forskellige Fabric-arbejdsbelastninger. På samme måde kan Fabric-tabeller, der er skrevet i Delta Lake-formatet, læses ved hjælp af Iceberg-læserne.

Når du skriver eller opretter en genvej til en Iceberg-tabelmappe, genererer OneLake automatisk virtuelle Delta Lake-metadata (Delta log) for tabellen, så den kan bruges sammen med Fabric-arbejdsbelastninger. Omvendt indeholder Delta Lake-tabeller nu virtuelle Iceberg-metadata, der muliggør kompatibilitet med Iceberg-læsere.

Denne artikel indeholder en vejledning til brug af Iceberg-tabeller med Snowflake, men denne funktion er beregnet til at fungere sammen med alle Iceberg-tabeller med Parquet-formaterede datafiler på lageret.

Virtualiser Delta Lake-tabeller som Iceberg

Følg disse trin for at konfigurere automatisk konvertering og virtualisering af tabeller fra Delta Lake-format til Iceberg-format.

1. Sørg for, at din Delta Lake-tabel, eller en genvej til den, findes i sektionen Tables for dit dataelement. Dataelementet kan være et lakehouse eller et andet Fabric-dataelement.

   Tips

   Hvis dit lakehouse er skemaaktiveret, placeres din tabelmappe direkte i et skema, dbof.eks. . Hvis lakehouse ikke er skemaaktiveret, vil din tabelmappe være direkte i Tables mappen.

2. Bekræft, at tabellen Delta Lake er konverteret til det virtuelle Iceberg-format. Det kan du gøre ved at undersøge mappen bag tabellen.

   Hvis du vil have vist mappen, hvis tabellen er i et lakehouse, kan du højreklikke på tabellen i brugergrænsefladen Fabric og vælge Vis filer.

   Hvis tabellen er i en anden dataelementtype, f.eks. et lager, en database eller en spejlet database, skal du bruge en klient som Azure Storage Explorer eller OneLake File Explorer i stedet for Fabric-brugergrænsefladen til at få vist filerne bag tabellen.

3. Du bør kunne se en mappe med navnet metadata i tabelmappen, og den skal indeholde flere filer, herunder konverteringslogfilen. Åbn konverteringslogfilen for at få vist flere oplysninger om Delta Lake til Iceberg-konverteringen, herunder tidsstemplet for den seneste konvertering og eventuelle fejloplysninger.

4. Hvis konverteringslogfilen viser, at tabellen blev konverteret korrekt, skal du læse tabellen Iceberg ved hjælp af din tjeneste, app eller det valgte bibliotek.

   Afhængigt af hvilken Iceberg-læser du bruger, skal du kende enten stien til tabelmappen eller til den nyeste .metadata.json fil, der vises i mappen metadata .

   Du kan se HTTP-stien til den nyeste metadatafil i tabellen ved at åbne visningen Egenskaber for filen *.metadata.json med det højeste versionsnummer. Notér denne sti.

   Stien til din dataobjekts Tables mappe kan se sådan ud:

   https://onelake.dfs.fabric.microsoft.com/83896315-c5ba-4777-8d1c-e4ab3a7016bc/a95f62fa-2826-49f8-b561-a163ba537828/Tables/
   

   Inden for den mappe kan den relative sti til den seneste metadatafil se ud som dbo/MyTable/metadata/321.metadata.json.

   Hvis du vil læse dit virtuelle Iceberg-bord ved hjælp af Snowflake, skal du følge trinnene i denne vejledning.

Opret en tabelgenvej til en Iceberg-tabel

Hvis du allerede har en Iceberg-tabel på en lagerplacering, der understøttes af OneLake-genveje, skal du følge disse trin for at oprette en genvej og få din Iceberg-tabel vist med Delta Lake-formatet.

1. Find dit isbjergbord. Find ud af, hvor din Iceberg-tabel er gemt, hvilket kan være i Azure Data Lake Storage, OneLake, Amazon S3, Google Cloud Storage eller en S3-kompatibel lagertjeneste.

   Bemærk

   Hvis du bruger Snowflake og ikke er sikker på, hvor din Iceberg-tabel er gemt, kan du køre følgende sætning for at se placeringen af din Iceberg-tabel.

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

   Kørsel af denne sætning returnerer en sti til metadatafilen for Tabellen Iceberg. Denne sti fortæller dig, hvilken lagerkonto der indeholder tabellen Iceberg. Her er f.eks. de relevante oplysninger for at finde stien til en Iceberg-tabel, der er gemt i Azure Data Lake Storage:

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

   Din Iceberg-tabelmappe skal indeholde en metadata mappe, som indeholder mindst én fil, der ender i .metadata.json.

2. Opret en ny tabelgenvej i området Tabeller i et lakehouse i dit Fabric-lakehouse.

   Tips

   Hvis du kan se skemaer som f.eks. dbo under mappen Tabeller i dit lakehouse, er lakehouse'et skemaaktiveret. I dette tilfælde skal du højreklikke på skemaet og oprette en tabelgenvej under skemaet.

   

3. Vælg mappen Iceberg-tabel for genvejens destinationssti. Tabellen Iceberg indeholder mapperne metadata og data .

4. Når genvejen er oprettet, bør du automatisk se denne tabel afspejlet som en Delta Lake-tabel i dit lakehouse, så du kan bruge den i hele Fabric.

   

   Hvis din nye genvej til tabellen Iceberg ikke vises som en brugbar tabel, skal du se afsnittet Fejlfinding .

Fejlfinding

Følgende tip kan hjælpe med at sikre, at dine Iceberg-tabeller er kompatible med denne funktion:

Kontrollér mappestrukturen i din Iceberg-tabel

Åbn din Iceberg-mappe i dit foretrukne lageroversigtsværktøj, og kontrollér mappelisten for din Iceberg-mappe på den oprindelige placering. Du bør kunne se en mappestruktur som følgende eksempel.

../
|-- MyIcebergTable123/
    |-- data/
        |-- A5WYPKGO_2o_APgwTeNOAxg_0_1_002.parquet
        |-- 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

Hvis du ikke kan se metadatamappen, eller hvis du ikke kan se filer med de udvidelser, der vises i dette eksempel, har du muligvis ikke en korrekt oprettet Iceberg-tabel.

Kontrollér konverteringsloggen

Når en Iceberg-tabel virtualiseres som en Delta Lake-tabel, kan du finde en mappe med navnet _delta_log/ i genvejsmappen. Denne mappe indeholder Delta Lake-formatets metadata (Delta-logfilen) efter vellykket konvertering.

Denne mappe indeholder latest_conversion_log.txt også filen, som indeholder oplysninger om den senest forsøgte konvertering.

Hvis du vil se indholdet af denne fil, når du har oprettet genvejen, skal du åbne menuen for genvejen til tabellen Iceberg under Området Tabeller i lakehouse og vælge Vis filer.

Du bør se en struktur som følgende eksempel:

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.

Åbn konverteringslogfilen for at se den seneste konverteringstid eller oplysninger om fejl. Hvis du ikke kan se en konverteringslogfil, blev konverteringen ikke forsøgt.

Forstå konverteringsloggen og fejlkategorierne

Filen latest_conversion_log.txt registrerer det seneste konverteringsforsøg. Når du virtualiserer en Iceberg-tabel som Delta Lake, finder du denne fil i tabellens _delta_log/ mappe. Når du virtualiserer en Delta Lake-tabel som Iceberg, ligger den i tabellens metadata/ mappe. Filen er ren tekst. Når en konvertering fejler, indeholder en struktureret blok, latest_conversion_log.txt der ligner følgende:

Status:             Failed
Timestamp (UTC):    2025-07-29T19:04:11Z
Latest Metadata:    00000000000000000012.metadata.json
Invocation Id:      6f1c...e2
Root Activity Id:   9a3d...b7
Error Code:         <code>
Error Category:     USER | SYSTEM
Error Details:      <message>

Brug Fejlkategorien til at beslutte, hvad du skal gøre næste gang:

• USER Det betyder, at kildetabellen indeholder noget, denne funktion ikke kan konvertere. Fejldetaljer beskriver, hvad der skal rettes. Juster kildetabellen (se Begrænsninger og overvejelser), og indfør derefter en ændring i kildetabellen. Konverteringsforsøg genoptræder automatisk efter næste commit.

• SYSTEM betyder, at der opstod en intern eller midlertidig fejl, og der ikke er noget at rette i kildetabellen. For at udløse endnu et konverteringsforsøg, committer du en ændring i kildetabellen. Hvis fejlene fortsætter, kontakt support og giv hele latest_conversion_log.txt filen.

Hvis konverteringen ikke blev forsøgt

Hvis du ikke kan se en konverteringslogfil, blev konverteringen ikke forsøgt. Her er to almindelige årsager til, at konvertering ikke forsøges:

• Genvejen blev ikke oprettet på det rigtige sted.

  Hvis en genvej til en Iceberg-tabel skal konverteres til Delta Lake-formatet, skal genvejen placeres direkte under mappen Tabeller i et lakehouse, der ikke er skemaaktiveret. Du bør ikke placere genvejen i sektionen Filer eller under en anden mappe, hvis tabellen skal virtualiseres automatisk som en Delta Lake-tabel.

  

• Genvejens destinationssti er ikke stien til mappen Iceberg.

  Når du opretter genvejen, må den mappesti, du vælger på destinationslagerplaceringen, kun være mappen med tabellen Iceberg. Denne mappe indeholder mapperne metadata og data .

  

Fejlmeddelelsen "Fabric capacity region kan ikke valideres" i Snowflake

Hvis du bruger Snowflake til at skrive en ny Iceberg-tabel til OneLake, får du muligvis vist følgende fejlmeddelelse:

Stofkapacitetsområdet kan ikke valideres. Årsag: 'Ugyldigt adgangstoken. Dette kan skyldes godkendelse og scoping. Bekræft delegerede områder.'

Hvis du får vist denne fejl, skal du få din Fabric-lejeradministrator til at dobbelttjekke, at du har aktiveret begge de lejerindstillinger, der er nævnt i afsnittet Skriv en Iceberg-tabel til OneLake ved hjælp af Snowflake :

1. Åbn Indstillinger i øverste højre hjørne af brugergrænsefladen i Fabric, og vælg Administrationsportal.
2. Under Lejerindstillinger skal du i afsnittet Udviklerindstillinger aktivere indstillingen, der hedder Tjenesteprincipaler kan bruge Fabric API'er.
3. I det samme område skal du i afsnittet OneLake-indstillinger aktivere indstillingen med navnet Brugere kan få adgang til data, der er gemt i OneLake, med apps uden for Fabric.

Begrænsninger og overvejelser

Husk følgende begrænsninger, når du bruger denne funktion. Nogle begrænsninger gælder for begge konverteringsretninger. Andre er specifikke for at omdanne Delta Lake til Iceberg eller Iceberg til Delta Lake.

Hvordan konverteringsproblemer opstår

Når en kildefunktion ikke kan oversættes fuldt ud, sker der én af to ting. Begge udfald rapporteres i konverteringsloggen.

Generelle begrænsninger

• Understøttelse af Apache Iceberg-versionen

  Den understøttede Iceberg-version afhænger af konverteringsretningen:

  Ombygningsretning	Isbjergsversionens adfærd
  Delta Lake til isbjerg	Producerer Iceberg V2 metadata.
  Isbjerg til Delta Lake	Understøtter Iceberg V2 kildetabeller. Iceberg V3-kildetabeller understøttes delvist; se Iceberg V3-funktioner.

• Kun Parquet-datafiler

  Denne funktion understøtter kun Parquet som det underliggende datafilformat til metadataoversættelse i begge konverteringsretninger.

• Seneste metadata-version konverteret

  Funktionen for tabelformatvirtualisering konverterer i øjeblikket den nyeste version af tabelmetadata til det oprindelige tabelformat. Hvis flere versioner skrives til det oprindelige tabelformat, vil kun den nyeste tabelmetadata-version blive konverteret til det virtuelle tabelformat.

• Maksimalt antal inputtransaktioner

  Kildetabeller skal have færre end 5.000 transaktioner eller commits for at tabelformatkonverteringen kan finde sted. Sørg for at komprimere dine transaktionslogfiler eller manifest for at reducere antallet af transaktioner eller commits.

• Konverteringsforsinkelse og opdateringsfrekvens

  Generering af metadata i tabelformat kan tage mellem 5 sekunder og 2 minutter. Sørg for, at de opdateringer, du laver i din kildetabel, sker mindre hyppigt end én gang hvert andet minut. Ellers kan du se en inkonsistent visning af outputtabelformatet.

• Skemaudvikling

  I begge konverteringsretninger understøttes udvidelsestypeændringer (for eksempel int til )long En indsnævring eller på anden måde inkompatibel typeændring får konverteringen til at fejle.

Delta Lake til isbjerg

Disse begrænsninger gælder, når du virtualiserer en Delta Lake-tabel som Iceberg.

Følgende overvejelser gælder, især for Delta Lake-tabeller, der ikke er skrevet med en IcebergCompat writer-funktion:

• Nested array og map kolonner kræver stabile felt-ID'er på deres element, nøgle og værdi. Uden dem fjernes kolonnen med den indlejrede samling fra isbjergets output (noteret i konverteringsloggen). IcebergCompat tildeler disse ID'er.

• Tidsstempler skal gemmes som INT64 mikrosekunder. En tabel, hvis tidsstempler fysisk gemmes som INT96 (legacy), konverteres, men dens tidsstempelkolonner kan ikke læses af Iceberg-motorer. IcebergCompat håndhæver INT64-tidsstempler.

• Kolonneomdøbninger — Bevares, når Delta Lake-tabellen bruger kolonnemapping (id eller name mode), hvilket IcebergCompat kræver. Med kolonnekortlægningstilstand nonevises et omdøbning som at fjerne og tilføje en kolonne.

• Kolonnetyper — Kun isbjergkompatible typer konverteres; andre kolonner fjernes (noteret i konverteringsloggen). For eksempel void har ingen isbjergækvivalent. IcebergCompat begrænser skemaet til et konvertibelt typesæt.

• Partitionering — Identitets- og tidsmæssige (år, måned, dag, time) partitioner konverteres. Delta Lake har en enkelt tabel-bred opdeling.

Isbjerg til Delta Lake

Disse begrænsninger gælder, når du virtualiserer en isbjergtavle som Delta Lake.

• Omdøbninger af kolonner understøttes ikke. Du kan ikke omdøbe en kolonne i kildetabellen til Iceberg. Genskab i stedet tabellen med de nye kolonnenavne. Når du genskaber tabellen, skal du fjerne eventuelle resterende metadatafiler, som beskrevet i Iceberg-tabelmapperne, kun indeholde ét sæt metadatafiler .

• Partitionstransformationer — Kun identitets- og tidsmæssige (år, måned, dag, time) transformationer understøttes. , bucket[N]truncate[W], og void transformationerne ignoreres: tabellen konverterer stadig, men uden denne opdeling. Den underliggende kolonne bevares som en regulær, ikke-partition kolonne.

• Partitionsudvikling — Hvis kildetabellens live datafiler spænder over mere end én partitionsspecifikation, eller hvis en tidligere konverteret tabels partitionskolonner ændres, afvises konverteringen. Delta Lake har en enkelt tabel-bred partitionering, og konvertering af blandede filer ville fejlagtigt give null-partitionsværdier for de ældre filer. Behold en enkelt partitionsspecifikation.

• Rader-niveau sletninger — Iceberg V2-positioner sletter og V3-deletionsvektorer konverteres til Delta Lake-deletionsvektorer. Sletninger af lighed får konvertering til at fejle.

• Ikke-understøttede typer — Typer uden Delta Lake-ækvivalent (for eksempel time, og Iceberg V3 udvidede typer) droppes; uuid mappes til binær. Se Iceberg V3-funktioner.

• Problem med typebredde

  Hvis du bruger Snowflake til at skrive din Iceberg-tabel, og tabellen indeholder kolonnetyper INT64, double, eller Decimal med præcision >= 10, kan den resulterende virtuelle Delta Lake-tabel muligvis ikke forbruges af alle Fabric-motorer. Du kan se fejl som:

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

  Vi arbejder på at løse problemet.

  Workaround: Hvis du bruger Lakehouse-tabelens preview-UI og ser dette problem, kan du løse fejlen ved at skifte til SQL analytics endpoint-visningen (øverst til højre, vælg Lakehouse view, skift til SQL analytics endpoint) og forhåndsvise tabellen derfra. Hvis du derefter skifter tilbage til Visningen Lakehouse, vises eksempelvisningen af tabellen korrekt.

  Hvis du kører en Spark-notesbog eller et spark-job og støder på dette problem, kan du løse denne fejl ved at angive spark.sql.parquet.enableVectorizedReader Spark-konfigurationen til false. Her er et eksempel på kommandoen PySpark, der skal køres i en Spark-notesbog:

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

• Metadatalageret for iceberg-tabellen er ikke bærbart

  Metadatafilerne i en Iceberg-tabel refererer til hinanden ved hjælp af absolutte stireferencer. Hvis du kopierer eller flytter en Iceberg-tabels mappeindhold til en anden placering uden at omskrive Iceberg-metadatafilerne, bliver tabellen ulæselig for Iceberg-læsere, herunder denne OneLake-funktion.

  Løsning:

  Hvis du har brug for at flytte din Iceberg-tabel til et andet sted for at bruge denne funktion, skal du bruge det værktøj, der oprindeligt skrev tabellen Iceberg, til at skrive en ny Iceberg-tabel på den ønskede placering.

• Iceberg-tabelmapper må kun indeholde ét sæt metadatafiler

  Hvis du slipper og genskaber en Iceberg-tabel i Snowflake, ryddes metadatafilerne ikke op. Denne funktionsmåde er designet til at understøtte funktionen UNDROP i Snowflake. Men da genvejen peger direkte på en mappe, og mappen nu indeholder flere sæt metadatafiler, kan vi ikke konvertere tabellen, før du fjerner den gamle tabels metadatafiler.

  Konverteringen mislykkes, hvis der findes mere end ét sæt metadatafiler i iceberg-tabellens metadatamappe.

  Løsning:

  Sådan sikrer du, at den konverterede tabel afspejler den korrekte version af tabellen:

  • Sørg for, at du ikke gemmer mere end én Iceberg-tabel i den samme mappe.
  • Ryd op i indholdet af en Iceberg-tabelmappe, når du har droppet den, før du opretter tabellen igen.

• Metadataændringer afspejles ikke med det samme

  Hvis du foretager metadataændringer i din Iceberg-tabel, såsom at tilføje en kolonne, slette en kolonne, omdøbe en kolonne eller ændre en kolonnetype, kan tabellen muligvis ikke blive konverteret igen, før der foretages en dataændring, som for eksempel ved at tilføje en række data.

  Vi arbejder på en rettelse, der henter den korrekte seneste metadatafil, der indeholder den seneste ændring af metadata.

  Løsning:

  Når skemaændringen er foretaget i din Iceberg-tabel, skal du tilføje en række med data eller foretage andre ændringer af dataene. Efter denne ændring bør du kunne opdatere og se den nyeste visning af tabellen i Fabric.

Iceberg V3-funktioner

Denne funktion producerer og læser Iceberg V2-metadata; den skriver ikke Iceberg V3-metadata. Når kilden er en Iceberg V3-tabel, oversættes dens egenskaber som beskrevet i følgende tabel. Udeladte kolonner og andre oversættelsesnoter registreres i konverteringsloggen.

Understøttede datatyper

Den følgende tabel viser, hvordan kolonnedatatyper kortlægges mellem formater. Medmindre andet er angivet, konverteres en type i begge retninger.

For Iceberg-tabeller skrevet af Snowflake kan brede long, double, eller decimal kolonner også påvirkes af typebreddeproblemet, som beskrevet i afsnittet Iceberg to Delta Lake .

Understøttede partitionstransformationer

Skema- og partitionsudvikling

Rader-niveau sletninger

Når du virtualiserer en isbjergstabel som Delta Lake:

Når du virtualiserer et Delta Lake-bord som isbjerg:

Tilgængelighed og platformbegrænsninger

• Begrænsning af områdetilgængelighed

  Funktionen er endnu ikke tilgængelig i følgende områder:

  • Det centrale Qatar
  • Det vestlige Norge

  Løsning:

  Arbejdsområder, der er knyttet til Fabric-kapaciteter i andre områder, kan bruge denne funktion. Se den fulde liste over regioner, hvor Fabric er tilgængeligt.

• Private links understøttes ikke

  Denne funktion understøttes i øjeblikket ikke for lejere eller arbejdsområder, der har private links aktiveret.

  Vi arbejder på en forbedring for at fjerne denne begrænsning.

• OneLake-genveje skal være af samme område

  Vi har en midlertidig begrænsning på brugen af denne funktion med genveje, der peger på OneLake-placeringer: Genvejens målplacering skal være i det samme område som selve genvejen.

  Vi arbejder på en forbedring for at fjerne dette krav.

  Løsning:

  Hvis du har en OneLake-genvej til et Iceberg-bord i et andet lakehouse, skal du sørge for, at det andet lakehouse er knyttet til en kapacitet i samme område.

Relateret indhold

• Brug Snowflake til at skrive eller læse Iceberg-tabeller i OneLake.
• Få mere at vide om OneLake-genveje.