Поделиться через

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

  • Статья

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

Внимание

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

Схема, демонстрирующая виртуализацию метаданных Delta Lake.

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

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

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

  1. Найдите таблицу Айсберга. Найдите место хранения таблицы 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.

  2. В azure Fabric lakehouse создайте новый ярлык в области таблиц в нестандартном озерном доме с поддержкой схемы.

    Примечание.

    Если вы видите схемы, такие как dbo в папке "Таблицы" вашего lakehouse, то lakehouse включена схема и еще не совместима с этой функцией.

    Снимок экрана: пункт меню создания ярлыка в разделе

  3. Для целевого пути ярлыка выберите папку таблицы Iceberg. Папка таблицы Iceberg содержит metadata папки и data папки.

  4. После создания ярлыка вы автоматически увидите эту таблицу, отображаемую как таблицу Delta Lake в озерном доме, готовую к использованию на протяжении всей структуры.

    Снимок экрана: успешное создание ярлыка таблицы Iceberg.

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

Написание таблицы Айсберга в OneLake с помощью Snowflake

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

  1. Убедитесь, что емкость Fabric находится в том же расположении Azure, что и экземпляр Snowflake.

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

    Снимок экрана: область емкости Fabric.

    В левом нижнем углу интерфейса учетной записи Snowflake в интерфейсе учетной записи Azure проверьте регион Azure учетной записи Snowflake.

    Снимок экрана: регион учетной записи Snowflake.

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

  2. Откройте меню для области "Файлы" в озерном доме, выберите "Свойства" и скопируйте URL-адрес (путь HTTPS) этой папки.

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

  3. Определите идентификатор клиента Fabric. Выберите профиль пользователя в правом верхнем углу пользовательского интерфейса Fabric и наведите указатель мыши на пузырь сведений рядом с именем клиента. Скопируйте идентификатор клиента.

    Снимок экрана: идентификатор клиента.

  4. В Snowflake настройте EXTERNAL VOLUME путь к папке "Файлы" в lakehouse. Дополнительные сведения о настройке внешних томов Snowflake см. здесь.

    Примечание.

    Snowflake требует, чтобы схема URL-адресов была azure://, поэтому обязательно измените ее https:// 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>'
    )
);

    В этом примере все таблицы, созданные с помощью этого внешнего тома, хранятся в lakehouse Fabric в папке Files/icebergtables .

  5. Теперь, когда создается внешний том, выполните следующую команду, чтобы получить URL-адрес согласия и имя приложения, которое Snowflake использует для записи в OneLake. Это приложение используется любым другим внешним томом в учетной записи Snowflake.

    DESC EXTERNAL VOLUME onelake_exvol;

    Выходные данные этой команды возвращают и AZURE_MULTI_TENANT_APP_NAME свойстваAZURE_CONSENT_URL. Запишите оба значения. Имя мультитенантного приложения Azure выглядит следующим <name>_<number>образом, но необходимо только записать <name> часть.

  6. Откройте URL-адрес согласия на предыдущем шаге на новой вкладке браузера. Если вы хотите продолжить, согласиться с необходимыми разрешениями приложения, если появится запрос.

  7. Вернитесь в Fabric, откройте рабочую область и выберите " Управление доступом", а затем добавьте людей или группы. Предоставьте приложению, используемому внешним томом Snowflake, разрешения, необходимые для записи данных в lakehouses в рабочей области. Рекомендуется предоставить роль участника .

  8. Вернувшись в Snowflake, используйте новый внешний том для создания таблицы Айсберга.

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

    С помощью этой инструкции создается новая папка таблицы Iceberg с именем Inventory в пути к папке, определенному во внешнем томе.

  9. Добавьте некоторые данные в таблицу Айсберга.

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

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

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

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

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

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

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

Если папка метаданных не отображается или вы не видите файлы с расширениями, показанными в этом примере, возможно, у вас нет правильно созданной таблицы 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 папки.

    Снимок экрана: содержимое пути к целевому объекту ярлыка во время создания ярлыка.

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

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

  • 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

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

    Если вы используете 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 в хранилище должна находиться в каталоге глубже, чем уровень контейнера или контейнера. Таблицы Айсберга, хранящиеся непосредственно в корневом каталоге контейнера или контейнера, не могут быть виртуализированы в формате Delta Lake.

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

    Решение:

    Убедитесь, что все таблицы Iceberg хранятся в каталоге глубже, чем корневой каталог контейнера или контейнера.

  • Папки таблицы Iceberg должны содержать только один набор файлов метаданных

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

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

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

    Решение:

    Чтобы убедиться, что преобразованная таблица отражает правильную версию таблицы:

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

  • Изменения метаданных не сразу отражаются

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

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

    Решение:

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

  • Рабочие области с поддержкой схемы еще не поддерживаются

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

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

    Решение:

    Используйте нефункциональный lakehouse с этой функцией. Этот параметр можно настроить во время создания Lakehouse.

  • Ограничение доступности региона

    Эта функция пока недоступна в следующих регионах:

    • Центральный Катар
    • Западная Норвегия

    Решение:

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

  • Закрытые ссылки не поддерживаются

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

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

  • Ограничение размера таблицы

    У нас есть временное ограничение на размер таблицы Айсберга, поддерживаемой этой функцией. Максимальное поддерживаемого количества файлов данных Parquet составляет около 5 000 файлов данных или примерно 1 млрд строк, в зависимости от того, какое ограничение встречается в первую очередь.

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

  • Сочетания клавиш OneLake должны быть одинаковыми регионами

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

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

    Решение:

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

Связанный контент