Использование таблиц Айсберга с OneLake

2025-07-01

В Microsoft OneLake вы можете легко работать с таблицами в форматах Delta Lake и Apache Iceberg.

Эта гибкость включена через виртуализацию метаданных, функцию, которая позволяет таблицам Iceberg интерпретироваться как таблицы Delta Lake и наоборот. Вы можете напрямую писать таблицы Айсберга или создавать сочетания клавиш, делая эти таблицы доступными для различных рабочих нагрузок Fabric. Аналогичным образом таблицы Fabric, написанные в формате Delta Lake, можно читать с помощью средств чтения Iceberg.

При создании ярлыка к папке таблицы Iceberg, OneLake автоматически генерирует виртуальные метаданные Delta Lake (журнал Delta) для таблицы, что позволяет использовать её с рабочими нагрузками Fabric. И наоборот, таблицы Delta Lake теперь включают виртуальные метаданные Iceberg, что позволяет обеспечить совместимость с средствами чтения Iceberg.

Внимание

Эта функция доступна в предварительной версии.

Схема, на которой показана виртуализация таблиц от Iceberg до Delta Lake.

Хотя эта статья содержит рекомендации по использованию таблиц Iceberg с Snowflake, эта функция предназначена для работы с любыми таблицами Айсберга с файлами данных в формате Parquet в хранилище.

Виртуализация таблиц Delta Lake в виде Айсберга

Чтобы настроить автоматическое преобразование и виртуализацию таблиц из формата Delta Lake в Айсберг, выполните следующие действия.

Включите автоматическую виртуализацию таблиц Delta Lake в формат Айсберга, включив делегированный параметр OneLake с именем Enable Delta Lake для виртуализации таблицы Apache Iceberg в параметрах рабочей области.

Примечание.

Этот параметр управляет функцией, которая в настоящее время находится в предварительной версии. Этот параметр будет удален в будущем обновлении, когда функция включена для всех пользователей и больше не находится в предварительной версии.
Убедитесь, что таблица Delta Lake или ярлык к ней находится в Tables разделе элемента данных. Элемент данных может быть лейкхаусом или другим элементом данных Fabric.

Подсказка

Если ваш lakehouse имеет схему, то каталог таблиц будет располагаться непосредственно в этой схеме, например dbo. Если lakehouse не включена в схему, каталог таблицы будет находиться непосредственно в каталоге Tables .
Убедитесь, что таблица Delta Lake успешно преобразована в виртуальный формат Айсберга. Это можно сделать, проверив каталог за таблицей.

Чтобы просмотреть каталог, если таблица находится в лейкхаусе, щелкните правой кнопкой мыши таблицу в пользовательском интерфейсе Fabric и выберите "Просмотреть файлы".

Если ваша таблица находится в другом типе данных, например, в хранилище, базе данных или зеркальной базе данных, вам нужно будет воспользоваться клиентом, например, Azure Storage Explorer или OneLake File Explorer, вместо пользовательского интерфейса Fabric, чтобы просмотреть файлы, связанные с таблицей.
В папке таблицы должен отображаться каталог metadata , который должен содержать несколько файлов, включая файл журнала преобразования. Откройте файл журнала преобразования, чтобы просмотреть дополнительные сведения о преобразовании Delta Lake в Iceberg, включая метку времени последнего преобразования и все сведения об ошибке.
Если файл журнала преобразования показывает, что таблица была успешно преобразована, прочитайте таблицу Iceberg с помощью службы, приложения или библиотеки.

В зависимости от используемого средства чтения Iceberg необходимо знать путь к каталогу таблицы или к последнему .metadata.json файлу, показанном в каталоге metadata .

Вы можете просмотреть HTTP-путь к последнему файлу метаданных таблицы, открыв представление "Свойства " для *.metadata.json файла с наибольшим номером версии. Запишите этот путь.

Путь к папке элемента Tables данных может выглядеть следующим образом:
```
https://onelake.dfs.fabric.microsoft.com/83896315-c5ba-4777-8d1c-e4ab3a7016bc/a95f62fa-2826-49f8-b561-a163ba537828/Tables/
```
В этой папке относительный путь к последнему файлу метаданных может выглядеть следующим dbo/MyTable/metadata/321.metadata.jsonобразом.

Чтобы прочитать виртуальную таблицу Айсберга с помощью Snowflake, выполните действия, описанные в этом руководстве.

Создание ярлыка таблицы для таблицы Iceberg

Если у вас уже есть таблица Iceberg в расположении хранения, поддерживаемом сочетаниями клавиш OneLake, выполните следующие действия, чтобы создать ярлык и открыть таблицу Iceberg с форматом Delta Lake.

Найдите таблицу Айсберга. Найдите место хранения таблицы Iceberg, которая может находиться в Azure Data Lake Storage, OneLake, Amazon S3, Google Cloud Storage или службе хранилища, совместимой с S3.

Примечание.

Если вы используете Snowflake и не уверены, где хранится таблица Айсберга, можно выполнить следующую инструкцию, чтобы просмотреть расположение хранения таблицы Iceberg.

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

Выполнение этой инструкции возвращает путь к файлу метаданных для таблицы Iceberg. Этот путь указывает, какая учетная запись хранения содержит таблицу Айсберга. Например, вот соответствующие сведения, чтобы найти путь к таблице Iceberg, хранящейся в 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"}

Папка таблицы Iceberg должна содержать metadata папку, которая сама содержит по крайней мере один файл, заканчивающийся .metadata.json.
В вашем Fabric lakehouse создайте новый ярлык таблицы в разделе таблиц lakehouse.

Подсказка

Если вы видите схемы, такие, как dbo в папке Таблицы вашего lakehouse, то lakehouse поддерживает схемы. В этом случае щелкните схему правой кнопкой мыши и создайте ярлык таблицы в схеме.
Для целевого пути ярлыка выберите папку таблицы Iceberg. Папка таблицы Iceberg содержит metadata папки и data папки.
После создания ярлыка вы автоматически увидите эту таблицу, отображаемую как таблицу Delta Lake в озерном доме, готовую к использованию на протяжении всей структуры.

Если новый ярлык таблицы Iceberg не отображается в качестве пригодной для использования таблицы, проверьте раздел "Устранение неполадок ".

Устранение неполадок

Следующие советы помогут убедиться, что таблицы Iceberg совместимы с этой функцией:

Проверьте структуру папок таблицы Iceberg

Откройте папку Iceberg в предпочтительном средстве обозревателя хранилища и проверьте список каталогов папки Iceberg в исходном расположении. Вы увидите структуру папок, как показано в следующем примере.

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

Если папка метаданных не отображается или вы не видите файлы с расширениями, показанными в этом примере, возможно, у вас нет правильно созданной таблицы Iceberg.

Проверка журнала преобразования

Если таблица Айсберга виртуализирована как таблица Delta Lake, в ярлыке можно найти папку с именем _delta_log/ . Эта папка содержит метаданные формата Delta Lake (журнал Delta) после успешного преобразования.

Эта папка также содержит latest_conversion_log.txt файл, содержащий последние сведения об успешном выполнении или сбое преобразования.

Чтобы просмотреть содержимое этого файла после создания ярлыка, откройте меню ярлыка таблицы Айсберга в области таблиц в области озера и выберите пункт "Просмотр файлов".

Снимок экрана: пункт меню

Вы увидите структуру, как показано в следующем примере:

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.

Откройте файл журнала преобразования, чтобы просмотреть последние сведения о времени преобразования или сбое. Если файл журнала преобразования не отображается, преобразование не было предприняно.

Если преобразование не было предприняно

Если файл журнала преобразования не отображается, преобразование не было выполнено. Ниже приведены две распространенные причины, по которым преобразование не выполняется:

Ярлык не был создан в нужном месте.

Чтобы ярлык в таблицу Айсберга был преобразован в формат Delta Lake, ярлык должен быть помещен непосредственно в папку "Таблицы" в нестандартном озерном доме с поддержкой схемы. Ярлык не следует помещать в раздел "Файлы" или в другую папку, если вы хотите, чтобы таблица была автоматически виртуализирована в виде таблицы Delta Lake.
Целевой путь ярлыка не является путь к папке Iceberg.

При создании ярлыка путь к папке, выбранной в целевом расположении хранилища, должен быть только папкой таблицы Iceberg. Эта папка содержитmetadata папки и data папки.

Сообщение об ошибке "Область пропускной способности Fabric невозможно подтвердить" в Snowflake

Если вы используете Snowflake для записи новой таблицы Iceberg в OneLake, может появиться следующее сообщение об ошибке:

Невозможно проверить область емкости Fabric. Причина: «Недопустимый токен доступа.» Это может быть связано с проверкой подлинности и ограничением области. Проверьте делегированные области.

Если вы видите эту ошибку, ваш администратор клиента Fabric должен внимательно проверить, что включены оба параметра клиента, упомянутые в секции «Запись таблицы Iceberg в OneLake с помощью Snowflake».

В правом верхнем углу пользовательского интерфейса Fabric откройте параметры и выберите портал администрирования.
В разделе Параметры клиента, в разделе Параметры разработчика, включите параметр, помеченный как Служебные субъекты могут использовать API Fabric.
В той же области, в разделе параметры OneLake, включите настройку, обозначенную как пользователи могут получить доступ к данным, хранящимся в OneLake через приложения, которые находятся вне системы Fabric.

Рекомендации и ограничения

Имейте в виду следующие временные ограничения при использовании этой функции:

Supported data types (Azure Search) (Поддерживаемые типы данных (служба "Поиск Azure")).

Следующие типы данных столбцов Iceberg сопоставляют с соответствующими типами Delta Lake с помощью этой функции.

Тип столбца Айсберга	Тип столбца Delta Lake	Комментарии
`int`	`integer`
`long`	`long`	См . проблему с шириной типа.
`float`	`float`
`double`	`double`	См . проблему с шириной типа.
`decimal(P, S)`	`decimal(P, S)`	См . проблему с шириной типа.
`boolean`	`boolean`
`date`	`date`
`timestamp`	`timestamp_ntz`	`timestamp` Тип данных Iceberg не содержит сведения о часовом поясе. Тип `timestamp_ntz` Delta Lake не полностью поддерживается в рабочих нагрузках Fabric. Рекомендуется использовать метки времени с включенными часовыми поясами.
`timestamptz`	`timestamp`	В Snowflake для использования этого типа укажите `timestamp_ltz` в качестве типа столбца во время создания таблицы Iceberg. Дополнительные сведения о типах данных Iceberg, поддерживаемых в Snowflake, см. здесь.
`string`	`string`
`binary`	`binary`
`time`	Не применимо	Не поддерживается

Проблема с шириной типа

Если вы используете Snowflake для записи таблицы Iceberg и таблицы содержит типы INT64столбцов, doubleили Decimal с точностью >= 10, результирующая виртуальная таблица Delta Lake может не использоваться всеми двигателями Fabric. Могут отображаться такие ошибки, как:
```
Parquet column cannot be converted in file ... Column: [ColumnA], Expected: decimal(18,4), Found: INT32.
```
Мы работаем над исправлением этой проблемы.

Решение . Если вы используете пользовательский интерфейс предварительной версии таблицы Lakehouse и видите эту проблему, эту ошибку можно устранить, переключившись в представление конечной точки SQL (в правом верхнем углу, выберите представление Lakehouse, перейдите в конечную точку SQL) и просмотрите таблицу. Если переключиться обратно в представление Lakehouse, предварительный просмотр таблицы должен отображаться правильно.

Если вы работаете с записной книжкой Spark или заданием и столкнулись с этой проблемой, эту ошибку можно устранить, установив spark.sql.parquet.enableVectorizedReader для конфигурации Spark значение false. Ниже приведен пример команды PySpark для запуска в записной книжке Spark:
```
spark.conf.set("spark.sql.parquet.enableVectorizedReader","false")
```
Хранилище метаданных таблицы Айсберга не переносимо

Файлы метаданных таблицы Айсберга ссылаются друг на друга, используя абсолютные ссылки на пути. Если вы копируете или перемещаете содержимое папки таблицы Айсберга в другое место без перезаписи файлов метаданных Iceberg, таблица становится нечитаемой для читателей Iceberg, включая эту функцию OneLake.

Решение:

Если вам нужно переместить таблицу Айсберга в другое место для использования этой функции, используйте инструмент, который первоначально написал таблицу Айсберга, чтобы написать новую таблицу Айсберга в нужном расположении.
Папки таблицы Iceberg должны содержать только один набор файлов метаданных

Если удалить и повторно создать таблицу Iceberg в Snowflake, файлы метаданных не очищаются. Это поведение предусмотрено в поддержку функции Snowflake. Тем не менее, так как ярлык указывает непосредственно на папку и в ней есть несколько наборов файлов метаданных, мы не можем преобразовать таблицу, пока не удалите файлы метаданных старой таблицы.

Преобразование завершится ошибкой, если в папке метаданных таблицы Iceberg найдено несколько наборов файлов метаданных.

Решение:

Чтобы убедиться, что преобразованная таблица отражает правильную версию таблицы:
- Убедитесь, что вы не храните более одной таблицы Iceberg в одной папке.
- Очистите любое содержимое папки таблицы Iceberg после удаления, прежде чем воссоздать таблицу.
Изменения метаданных не сразу отражаются

Если вы вносите изменения метаданных в таблицу Iceberg, например добавление столбца, удаление столбца, переименование столбца или изменение типа столбца, таблица может не быть восстановлена до тех пор, пока не будет выполнено изменение данных, например добавление строки данных.

Мы работаем над исправлением, которое выбирает правильный последний файл метаданных, включающий последнее изменение метаданных.

Решение:

После изменения схемы в таблицу Iceberg добавьте строку данных или внесите другие изменения в данные. После этого изменения вы сможете обновить и просмотреть последнее представление таблицы в Fabric.
Ограничение доступности региона

Эта функция пока недоступна в следующих регионах:
- Центральный Катар
- Западная Норвегия
Решение:

Рабочие области, подключенные к емкостям Fabric в других регионах, могут использовать эту функцию. Полный список регионов, где доступна Microsoft Fabric.
Закрытые ссылки не поддерживаются

Эта функция в настоящее время не поддерживается для клиентов или рабочих областей с включенными закрытыми ссылками.

Мы работаем над улучшением, чтобы удалить это ограничение.
Сочетания клавиш OneLake должны быть одинаковыми регионами

У нас есть временное ограничение на использование этой функции с ярлыками, указывающими на расположения OneLake: целевое расположение ярлыка должно находиться в том же регионе, что и сам ярлык.

Мы работаем над улучшением, чтобы удалить это требование.

Решение:

Если у вас есть ярлык OneLake к столу Айсберга в другом озерном доме, убедитесь, что другой lakehouse связан с емкостью в том же регионе.
Некоторые типы преобразования секций Iceberg не поддерживаются

В настоящее время типы bucket[N]truncate[W] и void не поддерживаются.

Если преобразованная таблица Айсберга содержит эти типы преобразования секций, виртуализация в формат Delta Lake не будет выполнена.

Мы работаем над улучшением, чтобы удалить это ограничение.

Используйте Snowflake для записи или чтения таблиц Айсберга в OneLake.
Дополнительные сведения о безопасности Fabric и OneLake.
Дополнительные сведения о сочетаниях клавиш OneLake.