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

Статья
06/12/2024

Внимание

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

Внимание

Эта функция доступна в общедоступной предварительной версии в Databricks Runtime 13.2 и выше.

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

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

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

Примечание.

Создание метаданных UniForm выполняется асинхронно на вычислительных ресурсах, используемых для записи данных в разностные таблицы, что может увеличить использование ресурсов драйвера.

Требования

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

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

Включение Delta UniForm

Внимание

Включение Delta UniForm задает функцию IcebergCompatV1таблицы Delta , функцию протокола записи. Только клиенты, поддерживающие эту функцию таблицы, могут записывать в таблицы с поддержкой UniForm. Для записи в таблицы Delta с включенным компонентом необходимо использовать Databricks Runtime 13.2 или более поздней версии.

Вы можете отключить UniForm, отменив настройку delta.universalFormat.enabledFormats свойства таблицы. Невозможно отключить сопоставление столбцов после его включения, а обновления до версии протокола чтения Delta Lake и записи не могут быть отменены.

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

'delta.universalFormat.enabledFormats' = 'iceberg'

Кроме того, необходимо включить сопоставление столбцов и IcebergCompatV1 использовать 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.

Примечание.

Если вы планируете использовать BigQuery в качестве клиента читателя Iceberg, необходимо установить spark.databricks.delta.write.dataFilesToSubdir значение true в Azure Databricks для размещения требования BigQuery для макета данных.

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

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

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

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

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

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

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

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

Поле метаданных	Description
`converted_delta_version`	Последняя версия таблицы Delta, для которой метаданные Iceberg были успешно созданы.
`converted_delta_timestamp`	Метка времени последней фиксации Delta, для которой метаданные Айсберга были успешно созданы.

В 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

См. раздел "ИСПРАВЛЕНИЕ ТАБЛИЦЫ".

Чтение с помощью пути 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"
    }
}

Внимание

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

Чтение конечной точки каталога Айсберга каталога Unity

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

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

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

Ниже приведен пример параметров настройки OSS Apache Spark для чтения Юниформы в качестве Айсберга:

"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 с помощью этого метода идентификаторы объектов используют следующий шаблон:

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

Этот шаблон использует те же три уровня имен, которые присутствуют в каталоге Unity, но добавляет дополнительный префикс unity.

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

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

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

Ограничения

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

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

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

Изменение веб-канала данных
Разностный общий доступ

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

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

Требования

Включение Delta UniForm

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

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

Ручное активация преобразования метаданных Iceberg

Чтение с помощью пути JSON метаданных

Чтение конечной точки каталога Айсберга каталога Unity

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

Ограничения

Обратная связь

Дополнительные ресурсы