Uso de tablas de Iceberg con OneLake

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.

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.

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 tabla o al archivo más reciente .metadata.json que se muestra en el directorio metadata.

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 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.

Localiza tu 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 Iceberg. La carpeta de la tabla de Iceberg contiene las carpetas metadata y data.
Una vez creado el acceso directo, se debería ver automáticamente esta tabla reflejada como una tabla de Delta Lake en su data lakehouse, lista para su uso dentro de 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 de Tablas de su lakehouse 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 lakehouse sin habilitar 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 un atajo, la ruta de acceso a la carpeta que selecciones en la ubicación de almacenamiento de destino solo debe ser la carpeta de la tabla 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:

Versión compatible de Apache Iceberg

Actualmente, la característica de virtualización de formato de tabla admite Apache Iceberg V2 . Esto significa que, cuando se lee una tabla de Delta Lake con esta característica, se generan metadatos de Iceberg V2. Las tablas originales de Iceberg proporcionadas a esta función deben ser Iceberg V2 para que se produzca la conversión al formato Delta Lake.

Estamos trabajando en la compatibilidad con la lectura de tablas de Iceberg V3. ¡Manténgase atento!
Última versión de metadatos convertida

La característica de virtualización de formato de tabla convierte actualmente la versión de metadatos de tabla más reciente en el formato de tabla original. Si se escriben varias versiones en el formato de tabla original, solo se convertirá la versión de metadatos de tabla más reciente al formato de tabla virtual.

Supported data types (Tipos de datos admitidos)

Los siguientes tipos de datos de columna de Iceberg se asignan a sus correspondientes tipos de Delta Lake utilizando esta función.

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 fuente.
`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 de letra

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: Si estás utilizando la interfaz de usuario de vista previa de la tabla de Lakehouse y ves este problema, puedes resolver el error cambiando a la vista de SQL Endpoint (en la esquina superior derecha, selecciona la vista de Lakehouse y cambia a SQL Endpoint) y obteniendo una vista previa de la tabla desde allí. Si luego regresas a la vista de Lakehouse, 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 refieren entre sí mediante rutas absolutas. 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 eliminar y volver a crear una tabla de Iceberg en Snowflake, los archivos de metadatos no se eliminan. 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 eliminarla y 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 enlaces privados no se admiten

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 estar en 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.
Obtenga más información sobre los accesos directos de OneLake.

Comentarios

¿Le resultó útil esta página?

Last updated on 2026-04-27