Устаревшая версия UniForm IcebergCompatV1

Универсальный формат Delta (UniForm) позволяет читать таблицы Delta с помощью клиентов чтения Iceberg.

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

Вы можете настроить внешнее подключение, чтобы каталог Unity действовал в качестве каталога Iceberg. См. статью Read using the Unity Catalog Iceberg catalog endpoint.

Требования

Чтобы включить UniForm, необходимо выполнить следующие требования:

• Таблица Delta должна быть зарегистрирована в каталоге Unity. Поддерживаются как управляемые, так и внешние таблицы.
• Таблица должна иметь включенное сопоставление столбцов. См. как переименовывать и удалять столбцы с использованием сопоставления столбцов в Delta Lake.
• Таблица Delta должна иметь minReaderVersion>= 2 и minWriterVersion>= 7. См. сведения о совместимости функций Delta Lake и протоколах.
• Записи в таблицу должны использовать Databricks Runtime 13.2 или более поздней версии.

Включение Delta UniForm

Следующее свойство таблицы включает поддержку UniForm для Iceberg. iceberg является единственным допустимым значением.

'delta.universalFormat.enabledFormats' = 'iceberg'

Кроме того, необходимо включить сопоставление столбцов и использовать UniForm. Они задаются автоматически, если включить UniForm во время создания таблицы, как показано в следующем примере:

CREATE TABLE T(c1 INT) TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'iceberg');

При создании таблицы с оператором CTAS необходимо вручную указать сопоставление столбцов, как показано в следующем примере:

CREATE TABLE T
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.universalFormat.enabledFormats' = 'iceberg')
AS
  SELECT * FROM source_table;

При изменении существующей таблицы необходимо указать все эти свойства, как показано в следующем примере:

ALTER TABLE T SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV1' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

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

См. Ограничения.

Когда UniForm создает метаданные Айсберга?

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

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

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

См. версии таблиц Delta и Iceberg.

Проверка состояния создания метаданных Iceberg

UniForm добавляет следующие поля в каталог Unity и метаданные таблицы Iceberg для отслеживания состояния создания метаданных:

В Azure Databricks можно просмотреть эти поля метаданных с помощью обозревателя каталогов. Эти поля и значения также возвращаются при использовании REST API для получения таблицы.

Сведения о проверке свойств таблицы за пределами Azure Databricks см. в документации по клиенту читателя Iceberg. Для OSS Apache Spark эти свойства можно просмотреть с помощью следующего синтаксиса:

SHOW TBLPROPERTIES <table-name>;

Вручную активировать преобразование метаданных Iceberg

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

Эта операция не должна быть необходимой в обычных условиях, но может помочь в следующих случаях:

• Кластер завершается до успешного создания автоматических метаданных.
• Ошибка или сбой задания прерывает создание метаданных.
• Клиент, не поддерживающий генерацию метаданных UniForm Iceberg, записывает в таблицу Delta.

Используйте следующий синтаксис, чтобы вручную активировать создание метаданных Iceberg:

MSCK REPAIR TABLE <table-name> SYNC METADATA

См. REPAIR TABLE.

Чтение с использованием пути JSON метаданных

Для некоторых клиентов Iceberg требуется указать путь к файлам версионных метаданных для регистрации внешних таблиц Iceberg. Каждый раз, когда UniForm преобразует новую версию таблицы Delta в Iceberg, он создает новый JSON-файл метаданных.

Клиенты, использующие пути JSON метаданных для настройки Айсберга, включают BigQuery. Дополнительные сведения о конфигурации см. в документации для клиента средства чтения Iceberg.

Delta Lake хранит метаданные Iceberg в каталоге таблиц, используя следующий шаблон:

<table-path>/metadata/<version-number>-<uuid>.metadata.json

Путь к этому файлу можно найти с помощью обозревателя каталогов. Для таблиц с поддержкой UniForm сведения о таблице Delta содержат поле для расположения метаданных Iceberg.

Можно также использовать REST API для получения всех сведений о таблице, включая расположение метаданных. Используйте следующую команду:

GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

Ответ содержит следующие данные:

{
    ...
          "delta_uniform_iceberg": {
              "metadata_location":  "<cloud-storage-uri>/metadata/v<version-number>-<uuid>.metadata.json"
    }
}

чтение с помощью конечной точки каталога Iceberg в системе Unity Catalog

Некоторые клиенты Iceberg могут подключаться к каталогу REST Iceberg. Каталог Unity предоставляет только для чтения реализацию REST API каталога Iceberg для таблиц Delta с включенной функцией UniForm, используя конечную точку /api/2.1/unity-catalog/iceberg. См. спецификацию Iceberg REST API для получения подробной информации об использовании данного REST API.

Клиенты, известные для поддержки API каталога Iceberg, включают Apache Spark, Flink и Trino. Необходимо настроить доступ к базовому облачному хранилищу объектов, содержащего таблицу Delta с включенной функцией UniForm. Дополнительные сведения о конфигурации см. в документации для клиента средства чтения Iceberg.

Необходимо создать и настроить личный маркер доступа Azure Databricks, чтобы разрешить другим службам подключаться к каталогу Unity. См. Разрешение доступа к ресурсам Azure Databricks.

Ниже приведен пример параметров настройки OSS Apache Spark для конфигурирования UniForm в формате Iceberg:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
"spark.sql.catalog.unity"="org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.unity.catalog-impl": "org.apache.iceberg.rest.RESTCatalog",
"spark.sql.catalog.unity.uri": "<api-root>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.unity.token":"<your_personal_access_token>",
"spark.sql.catalog.unity.io-impl": "org.apache.iceberg.aws.s3.S3FileIO

Замените полный URL-адрес рабочей области, в которой вы создали личный токен доступа, на <api-root>.

unity.<catalog-name>.<schema-name>.<table-name>

версии таблиц Delta и Iceberg

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

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

Ограничения

Существуют следующие ограничения:

• UniForm не работает в таблицах с включенными векторами удаления. См. раздел " Что такое векторы удаления?".
• Таблицы Delta с поддержкой UniForm не поддерживают LIST, MAP и VOID типы.
• Клиенты Айсберг могут читать только из UniForm. Запись данных не поддерживается.
• Пользователи приложения Айсберг могут иметь специфические ограничения, независимо от UniForm. Посмотрите документацию для выбранного вами клиента.
• Клиенты читателя Iceberg версии 1.2.0 и ниже не поддерживают INT96 тип метки времени, написанный Apache Spark. Используйте следующий код в записных книжках, которые записывают в таблицы UniForm, чтобы избежать этого ограничения: spark.conf.set(“spark.sql.parquet.outputTimestampType”, “TIMESTAMP_MICROS”)
• Публичная предварительная версия конечной точки Unity Catalog Iceberg не предназначена для крупномасштабных производственных нагрузок. При превышении порогового значения 5 запросов в секунду может возникнуть ограничение скорости.

Следующие функции Delta Lake работают для клиентов Delta при включении UniForm, но не поддерживаются в Айсберге:

• Лента данных об изменениях
• Delta Sharing (Дельта шаринг)