Uso de tablas de Iceberg con OneLake

2025-07-02

En Microsoft OneLake, puede trabajar sin problemas con tablas en los formatos Delta Lake y Apache Iceberg.

Esta flexibilidad se habilita a través de la virtualización de metadatos, una característica que permite interpretar las tablas de Iceberg como tablas de Delta Lake y viceversa. Puede escribir directamente tablas de Iceberg o crear accesos directos a ellas, lo que hace que estas tablas sean accesibles en varias cargas de trabajo de Fabric. Del mismo modo, las tablas Fabric escritas en el formato Delta Lake se pueden leer utilizando los lectores Iceberg.

Al escribir o crear un acceso directo a una carpeta de tablas de Iceberg, OneLake genera automáticamente un log de Delta virtual (metadatos de Delta Lake) para la tabla, lo que permite su uso con cargas de trabajo de Fabric. Por el contrario, las tablas de Delta Lake ahora incluyen metadatos virtuales de Iceberg, lo que permite la compatibilidad con lectores de Iceberg.

Importante

Esta característica se encuentra en versión preliminar.

Diagrama en el que se muestra la virtualización de tablas de Iceberg a Delta Lake.

Aunque en este artículo se incluyen instrucciones para el uso de tablas con Snowflake, esta característica está pensada para trabajar con cualquier tabla de Iceberg con archivos de datos en formato Parquet almacenados.

Virtualizar tablas de Delta Lake como Iceberg

Para configurar la conversión automática de tablas del formato Delta Lake al formato Iceberg, siga estos pasos.

Habilite la virtualización automática de tablas de Delta Lake al formato Iceberg al activar la configuración delegada de OneLake denominada Habilitar la virtualización de formato de tabla de Delta Lake a Apache Iceberg en las configuraciones de su entorno de trabajo.

Nota:

Esta configuración controla una característica que se encuentra actualmente en versión preliminar. Esta configuración se quitará en una actualización futura cuando la característica esté habilitada para todos los usuarios y ya no esté en versión preliminar.
Asegúrese de que la tabla de Delta Lake o un acceso directo a ella se encuentra en la Tables sección del elemento de datos. El elemento de datos puede ser una lakehouse u otro elemento de datos de Fabric.

Sugerencia

Si lakehouse está habilitado para el esquema, el directorio de la tabla se ubicará directamente dentro de un esquema como dbo. Si su lakehouse no tiene habilitado el esquema, entonces su directorio de la tabla estará directamente dentro del directorio Tables.
Confirme que la tabla de Delta Lake se ha convertido correctamente al formato virtual Iceberg. Para ello, examine el directorio detrás de la tabla.

Para ver el directorio si la tabla está en una instancia de LakeHouse, puede hacer clic con el botón derecho en la tabla en la interfaz de usuario de Fabric y seleccionar Ver archivos.

Si la tabla está en otro tipo de elemento de datos, como un almacenamiento, una base de datos o una base de datos reflejada, deberá usar un cliente como el Explorador de archivos de Azure Storage o el Explorador de archivos OneLake, en lugar de la interfaz de usuario de Fabric, para ver los archivos detrás de la tabla.
Debería ver un directorio denominado metadata dentro de la carpeta table y debe contener varios archivos, incluido el archivo de registro de conversión. Abra el archivo de registro de conversión para ver más información sobre la conversión de Delta Lake a Iceberg, incluida la marca de tiempo de la conversión más reciente y cualquier detalle de errores.
Si el archivo de registro de conversión muestra que la tabla se ha convertido correctamente, lea la tabla Iceberg mediante su servicio, aplicación o biblioteca que prefiera.

En función de lo que use el lector de Iceberg, deberá conocer la ruta de acceso al directorio de la tabla o al archivo más reciente .metadata.json que se muestra en metadata directorio.

Para ver la ruta de acceso HTTP al archivo de metadatos más reciente de la tabla, abra la vista Propiedades del *.metadata.json archivo con el número de versión más alto. Tome nota de esta ruta de acceso.

La ruta de acceso a la carpeta del Tables elemento de datos puede tener este aspecto:
```
https://onelake.dfs.fabric.microsoft.com/83896315-c5ba-4777-8d1c-e4ab3a7016bc/a95f62fa-2826-49f8-b561-a163ba537828/Tables/
```
Dentro de esa carpeta, la ruta de acceso relativa al archivo de metadatos más reciente puede parecerse a dbo/MyTable/metadata/321.metadata.json.

Para leer la tabla virtual de Iceberg mediante Snowflake, siga los pasos descritos en esta guía.

Crear un acceso directo de tabla a una tabla de Iceberg

En el caso de que ya disponga de una tabla de Iceberg en una ubicación de almacenamiento compatible con los accesos directos de OneLake, siga estos pasos para crear un acceso directo y hacer que la tabla de Iceberg aparezca con el formato de Delta Lake.

Búsqueda de la tabla de Iceberg. Busque dónde se almacena la tabla de Iceberg, que podría estar en Azure Data Lake Storage, OneLake, Amazon S3, Google Cloud Storage o en un servicio de almacenamiento compatible con S3.

Nota:

En el caso de que use Snowflake y no esté seguro de dónde se almacena la tabla de Iceberg, ejecute la siguiente instrucción para ver la ubicación de almacenamiento de la misma.

SELECT SYSTEM$GET_ICEBERG_TABLE_INFORMATION('<table_name>');

Al ejecutar esta instrucción, se devuelve una ruta de acceso al archivo de metadatos de la tabla de Iceberg. Esta ruta de acceso indica qué cuenta de almacenamiento contiene la tabla de Iceberg. Por ejemplo, esta es la información pertinente para encontrar la ruta de acceso de una tabla de Iceberg almacenada en 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"}

La carpeta de la tabla de Iceberg debe contener una carpeta metadata, que contiene al menos un archivo que termina en .metadata.json.
En Fabric Lakehouse, cree un nuevo acceso directo a tabla en el área de Tablas de un lakehouse.

Sugerencia

Si ves esquemas como dbo en la carpeta de tablas de tu lakehouse, entonces el lakehouse está habilitado para esquemas. En este caso, haga clic con el botón derecho en el esquema y cree un acceso directo a la tabla dentro del esquema.
Para la ruta de acceso de destino del acceso directo, seleccione la carpeta de la tabla de Iceberg. La carpeta de la tabla de Iceberg contiene las carpetas metadata y data.
Al crear el acceso directo, se debería ver automáticamente esta tabla reflejada como tabla de Delta Lake en el almacén de lago, lista para su uso en Fabric.

En caso de que el nuevo acceso directo a la tabla de Iceberg no aparezca como una tabla utilizable, compruebe la sección Solución de problemas.

Solución de problemas

Las siguientes recomendaciones pueden ayudarle a asegurarse de que las tablas de Iceberg sean compatibles con esta característica:

Compruebe la estructura de carpetas de la tabla de Iceberg

Abra la carpeta de Iceberg en la herramienta de explorador de almacenamiento que prefiera y compruebe la lista de directorios de la carpeta de Iceberg en su ubicación original. Debería ver una estructura de carpetas como la del ejemplo siguiente.

../
|-- MyIcebergTable123/
    |-- data/
        |-- A5WYPKGO_2o_APgwTeNOAxg_0_1_002.parquet
        |-- 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

En caso de no ver la carpeta de metadatos o archivos con las extensiones que se muestran en este ejemplo, es posible que no tenga una tabla de Iceberg generada correctamente.

Comprobación del registro de conversión

Cuando una tabla de Iceberg se virtualiza como tabla de Delta Lake, se puede encontrar una carpeta denominada _delta_log/ dentro de la carpeta de acceso directo. Esta carpeta contendrá los metadatos del formato de Delta Lake (el registro Delta) después de una conversión correcta.

Esta carpeta también incluye el archivo latest_conversion_log.txt, que contiene los detalles de éxito o error de la conversión más reciente.

Para ver el contenido de este archivo después de la creación del acceso directo, abra el menú para el acceso directo de la tabla de Iceberg en el área Tablas del almacén de lago y seleccione Ver archivos.

Captura de pantalla del elemento de menú Ver archivos.

Debería mostrarse una estructura como la del ejemplo siguiente:

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.

Abra el archivo de registro de conversión para ver la hora de conversión más reciente o los detalles del error. Si no se mostrase un archivo de registro de conversión, esta última no se intentó.

Si no se intentó la conversión

Si no se mostrase un archivo de registro de conversión, entonces esta última no se intentó. Aquí se muestran dos razones comunes por las que podría no intentarse realizar la conversión:

El acceso directo no se creó en el lugar correcto.

Para que un acceso directo a una tabla de Iceberg se convierta al formato de Delta Lake, el acceso directo deberá colocarse directamente en la carpeta Tablas de un almacén de lago no habilitado para esquemas. El acceso directo no debería colocarse en la sección Archivos o en otra carpeta en caso de querer que la tabla se virtualice automáticamente como tabla de Delta Lake.
La ruta de acceso de destino del acceso directo no es la ruta de acceso de la carpeta de Iceberg.

Al crear el acceso directo, la ruta de acceso a la carpeta que se seleccione en la ubicación de almacenamiento de destino solo deberá ser la carpeta de la tabla de Iceberg. Esta carpeta contiene las carpetas metadata y data.

Mensaje de error "Región de capacidad de tejido no se puede validar" en Snowflake

Si usa Snowflake para escribir una nueva tabla de Iceberg en OneLake, es posible que vea el siguiente mensaje de error:

No se puede validar la región de capacidad del tejido. Motivo: 'Token de acceso no válido. Esto puede deberse a la autenticación y al alcance. Compruebe los ámbitos delegados.

Si ve este error, haga que el administrador de inquilinos de Fabric compruebe que ha habilitado ambas opciones de configuración de inquilino mencionadas en la sección Escritura de una tabla de Iceberg en OneLake mediante Snowflake :

En la esquina superior derecha de la interfaz de usuario de Fabric, abra Configuración y seleccione Portal de administración.
En Configuración de inquilinos, en la sección Configuración del desarrollador, habilite la configuración etiquetada Principales de servicio puedan usar las API de Fabric.
En la misma área, en la sección Configuración de OneLake , habilite la configuración etiquetada Usuarios puede acceder a los datos almacenados en OneLake con aplicaciones externas a Fabric.

Limitaciones y consideraciones

Tenga en cuenta las siguientes limitaciones temporales al usar esta característica:

Supported data types (Tipos de datos admitidos)

Los siguientes tipos de datos de columna de Iceberg se asignan a sus tipos de Delta Lake correspondientes mediante esta característica.

Tipo de columna de Iceberg	Tipo de columna de Delta Lake	Comentarios
`int`	`integer`
`long`	`long`	Consulte Problema de ancho de tipo.
`float`	`float`
`double`	`double`	Consulte Problema de ancho de tipo.
`decimal(P, S)`	`decimal(P, S)`	Consulte Problema de ancho de tipo.
`boolean`	`boolean`
`date`	`date`
`timestamp`	`timestamp_ntz`	El tipo de datos de Iceberg `timestamp` no contiene información sobre zona horaria. El tipo de Delta Lake `timestamp_ntz` no es totalmente compatible con las cargas de trabajo de Fabric. Se recomienda el uso de marcas de tiempo con zonas horarias incluidas.
`timestamptz`	`timestamp`	Para usar este tipo en Snowflake, especifique `timestamp_ltz` como tipo de columna durante la creación de la tabla de Iceberg. Aquí encontrará más información sobre los tipos de datos de Iceberg admitidos en Snowflake.
`string`	`string`
`binary`	`binary`
`time`	No disponible	No está soportado

Problema de ancho de tipo

En caso de usar Snowflake para escribir la tabla de Iceberg y esta contuviera tipos de columna INT64, double o Decimal con precisión >= 10, es posible que todos los motores de Fabric no consuman la tabla virtual de Delta Lake resultante. Es posible que vea errores como los siguientes:
```
Parquet column cannot be converted in file ... Column: [ColumnA], Expected: decimal(18,4), Found: INT32.
```
Estamos trabajando para solucionar el problema.

Solución alternativa: en caso de usar la interfaz de usuario de vista previa de la tabla del almacén de lago y ver este problema, se resolverá este error al cambiar a la vista de punto de conexión de SQL (en la esquina superior derecha, seleccione la vista de almacén de lago y cambie a Punto de conexión de SQL) y se obtendrá una vista previa de la tabla desde allí. Al volver a la vista de almacén de lago, la vista previa de la tabla debería mostrarse correctamente.

En caso de ejecutar un cuaderno o un trabajo de Spark y encontrarse este problema, se resolverá este error estableciendo la configuración de Spark de spark.sql.parquet.enableVectorizedReader en false. Este es un comando de PySpark de ejemplo para su ejecución en un cuaderno de Spark:
```
spark.conf.set("spark.sql.parquet.enableVectorizedReader","false")
```
El almacenamiento de metadatos de tabla de Iceberg no es portátil

Los archivos de metadatos de una tabla de Iceberg se hacen referencia entre sí mediante referencias de ruta de acceso absoluta. Al copiar o mover el contenido de la carpeta de una tabla de Iceberg a otra ubicación sin reescribir los archivos de metadatos de Iceberg, la tabla se volverá ilegible para los lectores de Iceberg, incluyendo esta característica de OneLake.

Solución alternativa:

En caso de necesitar mover la tabla de Iceberg a otra ubicación para usar esta característica, use la herramienta que originalmente escribió la tabla de Iceberg para escribir nuevas tablas de Iceberg en la ubicación deseada.
Las carpetas de tablas de Iceberg solo deben contener un conjunto de archivos de metadatos

Al quitar y volver a crear tablas de Iceberg en Snowflake, los archivos de metadatos no se limpiarán. Este comportamiento es por diseño, en compatibilidad con la UNDROP característica en Snowflake. Sin embargo, como el acceso directo apunta directamente a una carpeta y esa carpeta ya tiene varios conjuntos de archivos de metadatos dentro de ella, no es posible convertir la tabla hasta que se quiten los archivos de metadatos de la tabla anterior.

La conversión fallará si se encuentra más de un conjunto de archivos de metadatos en la carpeta de metadatos de la tabla Iceberg.

Solución alternativa:

Para asegurarse de que la tabla convertida refleje la versión correcta de la tabla:
- Asegúrese de que no se esté almacenando más de una tabla de Iceberg en la misma carpeta.
- Limpie cualquier contenido de una carpeta de tabla de Iceberg después de quitarla antes de volver a crear la tabla.
Los cambios de metadatos no se reflejan inmediatamente

En caso de realizar cambios en los metadatos en la tabla de Iceberg, como agregar una columna, eliminar una columna, cambiar el nombre de una columna o cambiar un tipo de columna, es posible que la tabla no se vuelva a convertir hasta que se realice un cambio de datos, como agregar una fila de datos.

Se está trabajando en una corrección que recoja el archivo de metadatos correcto más reciente que incluya el cambio de metadatos más reciente.

Solución alternativa:

Después de realizar el cambio de esquema en la tabla de Iceberg, agregue una fila de datos o realice cualquier otro cambio en los datos. Después de ese cambio, debería poder actualizar y ver la vista más reciente de la tabla en Fabric.
Limitación de disponibilidad de regiones

La característica aún no está disponible en las siguientes regiones:
- Centro de Catar
- Oeste de Noruega
Solución alternativa:

Las áreas de trabajo adjuntas a las capacidades de Fabric en otras regiones pueden usar esta característica. Consulte la lista completa de regiones en las que Microsoft Fabric está disponible.
Los vínculos privados no son compatibles

Esta característica no se admite actualmente para inquilinos o áreas de trabajo que tengan habilitados vínculos privados.

Se está trabajando en una mejora para quitar esta limitación.
Los accesos directos de OneLake deben ser de la misma región

Existe una limitación temporal sobre el uso de esta característica con accesos directos que apunten a ubicaciones de OneLake: la ubicación de destino del acceso directo debe estar en la misma región que el propio acceso directo.

Se está trabajando en una mejora para quitar este requisito.

Solución alternativa:

En caso de tener un acceso directo de OneLake a una tabla de Iceberg en otro almacén de lago, asegúrese de que el otro almacén de lago esté asociado a una capacidad de la misma región.
No se admiten determinados tipos de transformación de partición de Iceberg

Actualmente, no se admiten los tipos de bucket[N], truncate[W]y void .

Si la tabla Iceberg que se va a convertir contiene estos tipos de transformación de partición, la virtualización al formato Delta Lake no tendrá éxito.

Se está trabajando en una mejora para quitar esta limitación.

Usa Snowflake para escribir o leer tablas Iceberg en OneLake.
Más información sobre la seguridad de Fabric y OneLake.
Obtenga más información sobre los accesos directos de OneLake.