Compartir vía

Uso de UniForm para leer tablas delta con clientes de Iceberg

  • Artículo

El formato universal de Delta Lake (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.

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 Iceberg usa Zstandard 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.

¿Cómo funciona UniForm?

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. Una sola copia de los archivos de datos proporciona varios formatos.

Requisitos

Para habilitar UniForm Iceberg, se deben cumplir los siguientes requisitos:

Nota:

No se pueden habilitar vectores de eliminación en una tabla con UniForm Iceberg habilitado.

Use REORG para deshabilitar y purgar vectores de eliminación al habilitar UniForm Iceberg en una tabla existente con vectores de eliminación habilitados. Consulte Habilitación o actualización mediante REORG.

Habilitación de UniForm Iceberg

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. Las actualizaciones a las versiones del protocolo de lectura y escritura de Delta Lake no se pueden deshacer.

Debe establecer las siguientes propiedades de tabla para habilitar UniForm Iceberg:

'delta.enableIcebergCompatV2' = 'true'
'delta.universalFormat.enabledFormats' = '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.

Para obtener una lista de limitaciones, consulte Limitaciones.

Habilitación durante la creación de tablas

La asignación de columnas debe estar habilitada para usar UniForm Iceberg. Esto sucede automáticamente si habilita UniForm Iceberg 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');

Habilitación modificando una tabla existente

En Databricks Runtime 15.4 LTS y versiones posteriores, puede habilitar o actualizar UniForm Iceberg en una tabla existente mediante la siguiente sintaxis:

ALTER TABLE table_name SET TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

Habilitación o actualización mediante REORG

Puede usar REORG para habilitar UniForm Iceberg y reescribir archivos de datos subyacentes, como en el siguiente ejemplo:

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

Use REORG si se cumple alguna de las siguientes condiciones:

  • La tabla tiene habilitados vectores de eliminación.
  • Anteriormente habilitó la versión IcebergCompatV1 de UniForm Iceberg.
  • Debe leer de los motores de Iceberg que no admiten archivos Parquet de estilo Hive, como Athena o Redshift.

¿Cuándo genera UniForm metadatos de Iceberg?

Azure Databricks desencadena la generación de metadatos de forma asincrónica después de que se complete una transacción de escritura de Delta Lake. Este proceso de generación de metadatos usa el mismo proceso que completó la transacción de Delta.

Nota:

También puede desencadenar manualmente la generación de metadatos de Iceberg. Vea Desencadenar manualmente la conversión de metadatos de Iceberg.

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

Delta Lake garantiza que solo haya un proceso de generación de metadatos en curso en cualquier momento en un recurso de proceso determinado. Confirma que desencadenaría un segundo proceso de generación de metadatos simultáneos para confirmarse correctamente en Delta, pero no desencadenaría la generación asincrónica de metadatos de Cosmos. 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.

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 Delta no se alinean con las versiones de Incremental mediante la marca de tiempo de confirmación o el identificador de versión. Para 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. Vea Comprobación del estado de generación de metadatos de 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. Consulte la documentación del cliente de lector de Iceberg para obtener más información sobre la configuración.

Autenticación y autorización

Existen dos requisitos para acceder a los datos registrados en el catálogo de Unity mediante el punto de conexión api/2.1/unity-catalog/iceberg de servicios externos:

Ejemplo de configuración de Apache Spark

A continuación se muestra un ejemplo de la configuración usado 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.type": "rest",
"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.warehouse": "<uc_catalog_name>"

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

Al consultar tablas en Unity Catalog mediante configuraciones de Spark, tenga en cuenta lo siguiente:

  • Los identificadores de objeto usan el patrón unity.<schema-name>.<table-name>.

    Este patrón usa el mismo espacio de nombres de tres niveles que se usa en Unity Catalog, pero con el nombre del catálogo reemplazado por unity.

  • Solo necesita "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" si ejecuta procedimientos almacenados específicos de Iceberg.

  • Si usa un proveedor de nube para el almacenamiento, debe agregar agrupados de Iceberg específicos para la nube como paquetes de Spark:

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    Para obtener más información, consulte la documentación sobre la integración de AWS Iceberg para Spark.

Ejemplo de curl de API de REST

También puede usar una llamada a la API de REST como la de este ejemplo de curl para cargar una tabla:

curl -X GET -H "Authentication: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

A continuación, debe recibir una respuesta como esta:

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

Nota:

El campo expires-at-ms de la respuesta indica la hora de expiración de las credenciales y tiene una hora de expiración predeterminada de una hora. Para mejorar el rendimiento, haga que el cliente almacene en caché las credenciales hasta la fecha de expiración antes de solicitar una nueva.

Limitaciones

Existen las siguientes limitaciones para todas las tablas de UniForm:

  • 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.
  • Algunas características de tabla de Delta Lake que usa UniForm Iceberg no son compatibles con algunos clientes de lector de Delta Sharing. Consulte ¿Qué es Delta Sharing?

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.