Formato universal (UniForm) para la compatibilidad de Iceberg con las tablas Delta

  • Artículo

El formato universal Delta (UniForm) permite leer tablas Delta con clientes lectores Iceberg. Esta característica requiere Databricks Runtime 14.3 LTS o superior.

Importante

Para obtener documentación sobre la característica heredada de tabla IcebergCompatV1 de UniForm, vea UniForm IcebergCompatV1 heredado.

UniForm aprovecha el hecho de que Delta Lake e Iceberg consisten en archivos de datos Parquet y una capa de metadatos. UniForm genera automáticamente los metadatos Iceberg de forma asíncrona, sin reescribir los datos, para que los clientes Iceberg puedan leer las tablas Delta como si fueran tablas Iceberg. Una sola copia de los archivos de datos sirve ambos formatos.

Puede configurar una conexión externa para que Unity Catalog actúe como un catálogo de Iceberg. Vea Lectura mediante el punto de conexión del catálogo Iceberg de Unity Catalog.

UniForm usa zstd en lugar de snappy como el códec de compresión para los archivos de datos parquet subyacentes.

Nota:

La generación de metadatos de UniForm se ejecuta de forma asincrónica en el proceso usado para escribir datos en tablas Delta, lo que podría aumentar el uso de recursos del controlador.

Requisitos

Para habilitar UniForm, debe cumplir los siguientes requisitos:

Nota:

No se pueden habilitar vectores de eliminación en una tabla con UniForm habilitado. Al habilitar UniForm en una tabla existente con vectores de eliminación habilitados, UniForm deshabilita y purga vectores de eliminación y vuelve a escribir los archivos de datos según sea necesario.

Habilitación de Delta UniForm

Importante

Al habilitar Delta UniForm, se establece la característica IcebergCompatV2 de tabla Delta, una característica de protocolo de escritura. Solo los clientes que admiten esta característica de tabla pueden escribir en tablas habilitadas para UniForm. Debe usar Databricks Runtime 14.3 LTS o superior para escribir en tablas delta con esta característica habilitada.

Puede desactivar UniForm estableciendo la delta.universalFormat.enabledFormats propiedad table. No se puede desactivar la asignación de columnas después de habilitarla y no se pueden deshacer las actualizaciones a las versiones del protocolo lector y escritor de Delta Lake.

Debe establecer las propiedades siguientes de la tabla para que habilite la compatibilidad de UniForm con Iceberg:

'delta.enableIcebergCompatV2' = 'true'
'delta.universalFormat.enabledFormats' = 'iceberg'

También debe habilitar la asignación de columnas para usar UniForm. Esto se habilita automáticamente si habilita UniForm durante la creación de la tabla, como en el ejemplo siguiente:

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

Puede habilitar UniForm en una tabla existente mediante la sintaxis siguiente:

REORG TABLE table_name APPLY (UPGRADE UNIFORM(ICEBERG_COMPAT_VERSION=2));

Nota:

Esta sintaxis también funciona para actualizar desde la Versión preliminar pública de UniForm, que ha usado la característica IcebergCompatV1 de la tabla.

Esta sintaxis deshabilita y purga automáticamente los vectores de eliminación de la tabla. Los archivos existentes se vuelven a escribir según sea necesario para que sean compatibles con Iceberg.

La primera vez que se habilita UniForm, comienza la generación de metadatos asincrónica. Esta tarea debe completarse antes de que los clientes externos puedan consultar la tabla mediante Iceberg. Vea Comprobación del estado de generación de metadatos de Iceberg.

Nota:

Si tiene previsto usar BigQuery como cliente de lector de Iceberg, debe establecerspark.databricks.delta.write.dataFilesToSubdir a true en Azure Databricks para adaptarse a un requisito de BigQuery para el diseño de datos.

Consulte Limitaciones.

¿Cuándo genera UniForm metadatos de Iceberg?

Azure Databricks desencadena de forma asincrónica la generación de metadatos después de que una transacción de escritura de Delta Lake se complete con el mismo proceso que completó la transacción Delta. También puede desencadenar manualmente la generación de metadatos de Iceberg. Vea Desencadenar manualmente la conversión de metadatos de Iceberg.

Para evitar las latencias de escritura asociadas a la generación de metadatos de Iceberg, las tablas Delta con confirmaciones frecuentes podrían agrupar varias confirmaciones delta en una sola confirmación de Iceberg.

Delta Lake garantiza que solo haya un proceso de generación de metadatos de Iceberg en curso en cualquier momento. Confirma que desencadenaría un segundo proceso simultáneo de generación de metadatos se confirmará correctamente en Delta, pero no desencadenarán la generación asincrónica de metadatos de Iceberg. Esto evita la latencia en cascada para la generación de metadatos para cargas de trabajo con confirmaciones frecuentes (segundos a minutos entre confirmaciones).

Vea Las versiones de la tabla Delta y Iceberg.

Vea Comprobación del estado de generación de metadatos de Iceberg.

UniForm agrega los siguientes campos a los metadatos de las tablas Unity Catalog y Iceberg para realizar un seguimiento del estado de generación de metadatos:

Campo de metadatos Descripción
converted_delta_version La versión más reciente de la tabla Delta para la que se generaron correctamente los metadatos Iceberg.
converted_delta_timestamp Marca de tiempo de la confirmación Delta más reciente para la que se generaron correctamente los metadatos Iceberg.

En Azure Databricks, puede revisar estos campos de metadatos mediante una de las siguientes opciones:

  • Revisión de la sección Delta Uniform Iceberg que devuelve DESCRIBE EXTENDED table_name.
  • Revisión de metadatos de tabla con Catalog Explorer.
  • Uso de la API REST para obtener una tabla.

Vea la documentación del cliente de lector Iceberg para obtener información sobre cómo revisar las propiedades de tabla fuera de Azure Databricks. En el caso de Apache Spark de OSS, puede ver estas propiedades con la sintaxis siguiente:

SHOW TBLPROPERTIES <table-name>;

Desencadenar manualmente la conversión de metadatos de Iceberg

Puede desencadenar manualmente la generación de metadatos Iceberg para la versión más reciente de la tabla Delta. Esta operación se ejecuta de forma sincrónica, lo que significa que cuando se completa, el contenido de la tabla disponible en Iceberg refleja la última versión de la tabla Delta disponible cuando se inició el proceso de conversión.

Esta operación no debe ser necesaria en condiciones normales, pero puede ayudar si encuentra lo siguiente:

  • Un clúster finaliza antes de que la generación automática de metadatos se realice correctamente.
  • Un error o error de trabajo interrumpe la generación de metadatos.
  • Un cliente que no admite la generación de metadatos UniForm Iceberg escribe en la tabla Delta.

Utilice la siguiente sintaxis para desencadenar manualmente la generación de metadatos de Iceberg:

MSCK REPAIR TABLE <table-name> SYNC METADATA

Consulte REPAIR TABLE.

Lectura mediante una ruta de acceso JSON de metadatos

Algunos clientes de Iceberg requieren que proporcione una ruta de acceso a los archivos de metadatos con versiones para registrar tablas externas de Iceberg. Cada vez que UniForm convierte una nueva versión de la tabla Delta en Iceberg, crea un nuevo archivo JSON de metadatos.

Los clientes que usan rutas de acceso JSON de metadatos para configurar Iceberg incluyen BigQuery. Consulte la documentación del cliente de lector de Iceberg para obtener más información sobre la configuración.

Delta Lake almacena los metadatos Iceberg en el directorio de tabla, con el siguiente patrón:

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

En Azure Databricks, puede revisar esta ubicación de metadatos mediante una de las siguientes opciones:

  • Revisión de la sección Delta Uniform Iceberg que devuelve DESCRIBE EXTENDED table_name.
  • Revisión de metadatos de tabla con Catalog Explorer.
  • Uso del siguiente comando con la API REST:
GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

La respuesta incluye la siguiente información:

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

Importante

Es posible que los clientes lectores de Iceberg basados en rutas de acceso requieran actualizar y actualizar manualmente las rutas JSON de metadatos para leer las versiones actuales de la tabla. Es posible que los usuarios encuentren errores al consultar las tablas de Iceberg con versiones obsoletas, ya que los archivos de datos Parquet se quitan de la tabla Delta con VACUUM.

Leer con el punto de conexión del catálogo Iceberg de Unity Catalog

Algunos clientes de Iceberg pueden conectarse a un catálogo REST de Iceberg. Unity Catalog proporciona una implementación de solo lectura de la API de catálogo REST de Iceberg para tablas Delta con UniForm habilitado mediante el punto de conexión /api/2.1/unity-catalog/iceberg. Vea la especificación de la API REST de Iceberg para obtener más detalles sobre el uso de esta API REST.

Los clientes conocidos por admitir la API del catálogo Iceberg incluyen Apache Spark, Flink y Trino. Debe configurar el acceso al almacenamiento de objetos en la nube subyacente que contiene la tabla Delta con UniForm habilitado. Consulte la documentación del cliente de lector de Iceberg para obtener más información sobre la configuración.

Debe generar y configurar un token de acceso personal de Azure Databricks para permitir que otros servicios se conecten a Unity Catalog. Vea Autenticación para la automatización de Azure Databricks: información general.

A continuación se muestra un ejemplo de la configuración para configurar OSS Apache Spark para que lea UniForm como 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

Sustituya la dirección URL completa del área de trabajo en la que generó el token de acceso personal para <api-root>.

Nota:

Al consultar tablas en Unity Catalog mediante este método, los identificadores de objeto usan el siguiente patrón:

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

Este patrón usa el mismo espacio de nombres de tres niveles presente en Unity Catalog, pero agrega un prefijo adicionalunity.

Versiones de tabla Delta y Iceberg

Delta Lake y Iceberg permiten consultas de viaje de tiempo mediante versiones de tabla o marcas de tiempo almacenadas en metadatos de tabla.

En general, las versiones de la tabla Iceberg y Delta no se alinean con la marca de tiempo de confirmación ni con el identificador de versión. Si desea comprobar a qué versión de una tabla Delta se corresponde una versión determinada de una tabla de Iceberg, puede utilizar las propiedades correspondientes de la tabla establecida en la tabla Iceberg. Vea Comprobación del estado de generación de metadatos de Iceberg.

Limitaciones

Existen las siguientes limitaciones:

  • UniForm no funciona en tablas con vectores de eliminación habilitados. Consulte ¿Qué son los vectores de eliminación?.
  • Las tablas delta con UniForm habilitado no admiten los tipos VOID.
  • Los clientes de Iceberg solo pueden leer de UniForm. No se admiten escrituras.
  • Es posible que los clientes lectores Iceberg tengan limitaciones individuales, independientemente de UniForm. Consulte la documentación del cliente elegido.
  • Los destinatarios de Delta Sharing solo pueden leer la tabla como Delta, incluso cuando UniForm está habilitado.

La modificación de la fuente de distribución de datos funciona para los clientes de Delta cuando UniForm está habilitado, pero no tiene soporte técnico en Iceberg.

Algunas características de tabla de Delta Lake que usa UniForm no son compatibles con algunos clientes de lector de Delta Sharing. Vea Uso seguro de recursos de uso compartido de datos e inteligencia artificial mediante Delta Sharing.