Použití tabulek Iceberg s OneLake

V Microsoft OneLake můžete vytvářet zástupce tabulek Apache Iceberg, které umožňují jejich použití napříč širokou škálou úloh Fabric. Tato funkce je možná prostřednictvím funkce označované jako virtualizace metadat, která umožňuje interpretovat tabulky Iceberg jako tabulky Delta Lake z pohledu zástupce. Když vytvoříte zástupce složky tabulky Iceberg, OneLake automaticky vygeneruje odpovídající metadata Delta Lake (protokol Delta) pro tuto tabulku, aby metadata Delta Lake byla přístupná prostřednictvím zástupce.

Důležité

Tato funkce je ve verzi Preview.

I když tento článek obsahuje pokyny pro psaní tabulek Iceberg z Snowflake do OneLake, tato funkce je určená pro práci se všemi tabulkami Iceberg s datovými soubory Parquet.

Vytvoření zástupce tabulky v tabulce Iceberg

Pokud už máte tabulku Iceberg v umístění úložiště podporovaném zkratkami OneLake, vytvořte zástupce podle těchto kroků a vytvořte tabulku Iceberg s formátem Delta Lake.

1. Vyhledejte tabulku Icebergu. Najděte, kde je uložená tabulka Iceberg, která může být ve službě Azure Data Lake Storage, OneLake, Amazon S3, Google Cloud Storage nebo službě úložiště kompatibilní s S3.

   Poznámka:

   Pokud používáte Snowflake a nevíte, kde je tabulka Iceberg uložená, můžete spustit následující příkaz, abyste viděli umístění úložiště tabulky Iceberg.

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

   Spuštění tohoto příkazu vrátí cestu k souboru metadat pro tabulku Iceberg. Tato cesta vám řekne, který účet úložiště obsahuje tabulku Iceberg. Tady jsou například relevantní informace pro vyhledání cesty k tabulce Iceberg uložené ve službě 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"}

   Složka tabulky Iceberg musí obsahovat metadata složku, která obsahuje alespoň jeden soubor končící .metadata.json.

2. V objektu Fabric Lakehouse vytvořte novou zástupce v oblasti Tabulky bez schématu u jezera s povoleným schématem.

   Poznámka:

   Pokud se zobrazí schémata, například dbo ve složce Tabulky vašeho jezerahouse, je jezero povoleno schématem a ještě není kompatibilní s touto funkcí.

   

3. Pro cílovou cestu zástupce vyberte složku tabulky Iceberg. Složka tabulky Iceberg obsahuje metadata složky a data složky.

4. Po vytvoření zástupce by se tato tabulka měla automaticky zobrazit jako tabulka Delta Lake ve vašem jezeře, která je připravená k použití v rámci prostředků infrastruktury.

   

   Pokud se nová zkratka tabulky Iceberg nezobrazí jako použitelná tabulka, projděte si část Řešení potíží .

Napsání tabulky Iceberg na OneLake pomocí Snowflake

Pokud používáte Snowflake v Azure, můžete do OneLake psát tabulky Iceberg pomocí následujícího postupu:

1. Ujistěte se, že vaše kapacita Fabric je ve stejném umístění Azure jako vaše instance Snowflake.

   Určete umístění kapacity Prostředků infrastruktury přidružené k vašemu fabric lakehouse. Otevřete nastavení pracovního prostoru Fabric, který obsahuje váš lakehouse.

   

   V levém dolním rohu rozhraní účtu Snowflake v Azure zkontrolujte oblast Azure účtu Snowflake.

   

   Pokud se tyto oblasti liší, musíte použít jinou kapacitu prostředků infrastruktury ve stejné oblasti jako váš účet Snowflake.

2. Otevřete nabídku pro oblast Soubory v jezeře, vyberte Vlastnosti a zkopírujte adresu URL (cestu HTTPS) této složky.

   

3. Identifikujte ID tenanta Fabric. Vyberte profil uživatele v pravém horním rohu uživatelského rozhraní Fabric a najeďte myší na informační bublinu vedle názvu tenanta. Zkopírujte ID tenanta.

   

4. Ve Snowflake nastavte EXTERNAL VOLUME cestu ke složce Soubory v jezeře. Další informace o nastavení externích svazků Snowflake najdete tady.

   Poznámka:

   Snowflake vyžaduje schéma url , azure://takže nezapomeňte změnit https:// na azure://.

   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>'
       )
   );
   

   V této ukázce jsou všechny tabulky vytvořené pomocí tohoto externího Files/icebergtables svazku uloženy ve složce Fabric Lakehouse.

5. Po vytvoření externího svazku spusťte následující příkaz, který načte adresu URL souhlasu a název aplikace, kterou Snowflake používá k zápisu do OneLake. Tuto aplikaci používá jakýkoli jiný externí svazek ve vašem účtu Snowflake.

   DESC EXTERNAL VOLUME onelake_exvol;
   

   Výstup tohoto příkazu vrátí AZURE_CONSENT_URL vlastnosti a AZURE_MULTI_TENANT_APP_NAME vlastnosti. Poznamenejte si obě hodnoty. Název víceklientských aplikací Azure vypadá takto <name>_<number>, ale stačí zachytit <name> jenom část.

6. Otevřete adresu URL souhlasu z předchozího kroku na nové kartě prohlížeče. Pokud chcete pokračovat, v případě výzvy udělte souhlas s požadovanými oprávněními aplikace.

7. Zpátky v Prostředcích infrastruktury otevřete pracovní prostor a vyberte Spravovat přístup a pak přidejte lidi nebo skupiny. Udělte aplikaci, kterou používá externí svazek Snowflake, oprávnění potřebná k zápisu dat do lakehouses ve vašem pracovním prostoru. Doporučujeme udělit roli Přispěvatel .

8. Zpátky ve Snowflake použijte nový externí svazek k vytvoření tabulky Iceberg.

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

   Pomocí tohoto příkazu se vytvoří nová složka tabulky Iceberg s názvem Inventory v cestě ke složce definované na externím svazku.

9. Přidejte některá data do tabulky Iceberg.

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

10. Nakonec v oblasti Tabulky stejného jezera můžete vytvořit zástupce OneLake tabulky Iceberg. Prostřednictvím této zkratky se tabulka Iceberg zobrazí jako tabulka Delta Lake pro spotřebu napříč úlohami Fabric.

Řešení problému

Následující tipy vám můžou pomoct zajistit kompatibilitu tabulek Iceberg s touto funkcí:

Kontrola struktury složek tabulky Iceberg

Otevřete složku Iceberg v preferovaném nástroji Průzkumníka úložiště a zkontrolujte výpis adresáře vaší složky Iceberg v původním umístění. Měla by se zobrazit struktura složek jako v následujícím příkladu.

../
|-- 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

Pokud složku metadat nevidíte nebo nevidíte soubory s příponami zobrazenými v tomto příkladu, možná nemáte správně vygenerovanou tabulku Iceberg.

Kontrola protokolu převodu

Pokud je tabulka Iceberg virtualizovaná jako tabulka Delta Lake, složka s názvem _delta_log/ se nachází uvnitř složky zástupce. Tato složka obsahuje metadata formátu Delta Lake (protokol Delta) po úspěšném převodu.

Tato složka obsahuje latest_conversion_log.txt také soubor, který obsahuje podrobnosti o úspěchu nebo selhání posledního pokusu o převod.

Pokud chcete zobrazit obsah tohoto souboru po vytvoření zástupce, otevřete nabídku zástupce tabulky Iceberg v oblasti Tabulky u jezera a vyberte Zobrazit soubory.

Měla by se zobrazit struktura podobná následujícímu příkladu:

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.

Otevřete soubor protokolu převodu, abyste viděli nejnovější čas převodu nebo podrobnosti o selhání. Pokud nevidíte soubor protokolu převodu, převod se nepokoušal.

Pokud se převod nepokoušal

Pokud nevidíte soubor protokolu převodu, převod se nepokusil. Tady jsou dva běžné důvody, proč se převod nepokoušal:

• Zástupce se nevytvořil na správném místě.

  Aby se zástupce tabulky Iceberg převedl do formátu Delta Lake, musí být zástupce umístěn přímo do složky Tabulky nepovoleného jezera. Pokud chcete, aby se tabulka automaticky virtualizovala jako tabulka Delta Lake, neměli byste zástupce umístit do oddílu Soubory ani do jiné složky.

  

• Cílová cesta zástupce není cesta ke složce Iceberg.

  Při vytváření zástupce musí být cesta ke složce, kterou vyberete v cílovém umístění úložiště, pouze složka tabulky Iceberg. Tato složka obsahuje složky metadata a data složky.

  

Omezení a důležité informace

Při použití této funkce mějte na paměti následující dočasná omezení:

• Podporované datové typy

  Následující datové typy sloupců Iceberg se mapují na odpovídající typy Delta Lake pomocí této funkce.

  Typ sloupce Iceberg	Typ sloupce Delta Lake	Komentáře
  int	integer
  long	long	Viz Problém s šířkou typu.
  float	float
  double	double	Viz Problém s šířkou typu.
  decimal(P, S)	decimal(P, S)	Viz Problém s šířkou typu.
  boolean	boolean
  date	date
  timestamp	timestamp_ntz	timestamp Datový typ Iceberg neobsahuje informace o časovém pásmu. Typ timestamp_ntz Delta Lake není plně podporovaný napříč úlohami Fabric. Doporučujeme používat časová razítka se zahrnutými časovými pásmy.
  timestamptz	timestamp	Pokud chcete tento typ použít ve Snowflake, zadejte timestamp_ltz jako typ sloupce při vytváření tabulky Iceberg. Další informace o datových typech Iceberg podporovaných ve Snowflake najdete tady.
  string	string
  binary	binary

• Problém s šířkou typu

  Pokud použijete Snowflake k napsání tabulky Iceberg a tabulka obsahuje typy INT64sloupců , doublenebo Decimal s přesností >= 10, výsledná virtuální tabulka Delta Lake nemusí být využita všemi moduly Fabric. Může se zobrazit například následující chyba:

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

  Pracujeme na opravě tohoto problému.

  Alternativní řešení: Pokud používáte uživatelské rozhraní tabulky Lakehouse ve verzi Preview a vidíte tento problém, můžete tuto chybu vyřešit přepnutím do zobrazení koncového bodu SQL (v pravém horním rohu, výběrem zobrazení Lakehouse, přepnutím na koncový bod SQL) a zobrazením náhledu tabulky odtud. Pokud pak přepnete zpět do zobrazení Lakehouse, měl by se náhled tabulky zobrazit správně.

  Pokud používáte poznámkový blok Sparku nebo úlohu a narazíte na tento problém, můžete tuto chybu vyřešit nastavením konfigurace Sparku spark.sql.parquet.enableVectorizedReader na false. Tady je příklad příkazu PySpark ke spuštění v poznámkovém bloku Spark:

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

• Úložiště metadat tabulek Iceberg není přenosné

  Soubory metadat tabulky Iceberg se vzájemně odkazují pomocí absolutních odkazů na cestu. Pokud zkopírujete nebo přesunete obsah složky tabulky Iceberg do jiného umístění, aniž byste museli přepisovat soubory metadat Icebergu, stane se tabulka nečitelnými čtenáři Icebergu, včetně této funkce OneLake.

  Alternativní řešení:

  Pokud potřebujete tabulku Iceberg přesunout do jiného umístění, abyste tuto funkci mohli použít, použijte nástroj, který původně napsal tabulku Iceberg, a napište novou tabulku Iceberg v požadovaném umístění.

• Ledové tabulky musí být hlubší než kořenová úroveň.

  Složka tabulky Iceberg v úložišti musí být umístěna v adresáři hlouběji než kontejner nebo úroveň kontejneru. Tabulky Iceberg uložené přímo v kořenovém adresáři kontejneru nebo kontejneru nemusí být virtualizované ve formátu Delta Lake.

  Na vylepšení tohoto požadavku pracujeme.

  Alternativní řešení:

  Zajistěte, aby všechny tabulky Icebergu byly uloženy v adresáři hlouběji než kořenový adresář kontejneru nebo kontejneru.

• Složky tabulek Iceberg musí obsahovat pouze jednu sadu souborů metadat.

  Pokud v Snowflake přehodíte a znovu vytvoříte tabulku Iceberg, soubory metadat se nevyčistí. Toto chování je podporováno UNDROP funkcí ve Snowflake. Vzhledem k tomu, že zástupce odkazuje přímo na složku a tato složka teď obsahuje více sad souborů metadat, nemůžeme tabulku převést, dokud neodeberete soubory metadat staré tabulky.

  V současné době se v tomto scénáři pokusíte o převod, což může vést k tomu, že se v virtualizované tabulce Delta Lake zobrazí starý obsah tabulky a informace o schématu.

  Pracujeme na opravě, ve které se převod nezdaří, pokud se ve složce metadat tabulky Iceberg nachází více než jedna sada souborů metadat.

  Alternativní řešení:

  Aby převedená tabulka odrážela správnou verzi tabulky:

  • Ujistěte se, že do stejné složky neuložíte více než jednu tabulku Iceberg.
  • Před opětovným vytvořením tabulky vyčistíte veškerý obsah složky tabulky Iceberg.

• Změny metadat se okamžitě neprojeví

  Pokud provedete změny metadat v tabulce Iceberg, například přidání sloupce, odstranění sloupce, přejmenování sloupce nebo změna typu sloupce, nemusí se tabulka znovu převést, dokud nedojde ke změně dat, například přidání řádku dat.

  Pracujeme na opravě, která přebírá správný nejnovější soubor metadat, který obsahuje nejnovější změnu metadat.

  Alternativní řešení:

  Po provedení změny schématu v tabulce Iceberg přidejte řádek dat nebo proveďte jakoukoli jinou změnu dat. Po této změně byste měli být schopni aktualizovat a zobrazit nejnovější zobrazení tabulky v prostředcích infrastruktury.

• Pracovní prostory s podporou schématu se zatím nepodporují.

  Pokud vytvoříte zástupce Icebergu v jezeře s podporou schématu, převod se pro tuto zkratku neprojeví.

  Pracujeme na vylepšení, abychom toto omezení odebrali.

  Alternativní řešení:

  S touto funkcí použijte bez schématu lakehouse. Toto nastavení můžete nakonfigurovat během vytváření jezera.

• Omezení dostupnosti oblastí

  Tato funkce ještě není dostupná v následujících oblastech:

  • Střední Katar
  • Norsko – západ

  Alternativní řešení:

  Tuto funkci můžou používat pracovní prostory připojené ke kapacitám Fabric v jiných oblastech. Podívejte se na úplný seznam oblastí, ve kterých je Microsoft Fabric dostupný.

• Privátní propojení nejsou podporována.

  Tato funkce se v současné době nepodporuje u tenantů ani pracovních prostorů s povolenými privátními propojeními.

  Pracujeme na vylepšení, abychom toto omezení odebrali.

• Omezení velikosti tabulky

  Tato funkce podporuje dočasné omezení velikosti tabulky Iceberg. Maximální podporovaný počet datových souborů Parquet je asi 5 000 datových souborů, nebo přibližně 1 miliardu řádků, podle toho, který limit je zjištěn jako první.

  Pracujeme na vylepšení, abychom toto omezení odebrali.

• Klávesové zkratky OneLake musí být ve stejné oblasti.

  Máme dočasné omezení použití této funkce se zástupci, které odkazují na umístění OneLake: cílové umístění zástupce musí být ve stejné oblasti jako samotná klávesová zkratka.

  Na vylepšení tohoto požadavku pracujeme.

  Alternativní řešení:

  Pokud máte zástupce OneLake tabulky Iceberg v jiném jezeře, ujistěte se, že je druhé jezero přidružené ke kapacitě ve stejné oblasti.

Související obsah

• Přečtěte si další informace o zabezpečení Fabric a OneLake.
• Přečtěte si další informace o zkratkách OneLake.