Use tabelas Iceberg com OneLake

2025-07-02

No Microsoft OneLake, você pode trabalhar perfeitamente com tabelas nos formatos Delta Lake e Apache Iceberg.

Essa flexibilidade é habilitada por meio da virtualização de metadados, um recurso que permite que as tabelas iceberg sejam interpretadas como tabelas delta lake e vice-versa. Você pode escrever diretamente tabelas de Iceberg ou criar atalhos para elas, tornando essas tabelas acessíveis em várias cargas de trabalho do Fabric. Da mesma forma, as tabelas Fabric escritas no formato Delta Lake podem ser lidas usando leitores Iceberg.

Quando você grava ou cria um atalho para uma pasta de tabela Iceberg, o OneLake gera automaticamente metadados virtuais do Delta Lake (log Delta) para a tabela, habilitando seu uso com cargas de trabalho do Fabric. Por outro lado, as tabelas delta lake agora incluem metadados de Iceberg virtuais, permitindo compatibilidade com leitores de Iceberg.

Importante

Esse recurso está em preview.

Diagrama mostrando a virtualização de tabela do Iceberg para o Delta Lake.

Embora este artigo inclua diretrizes para usar tabelas iceberg com Snowflake, esse recurso destina-se a trabalhar com quaisquer tabelas iceberg com arquivos de dados formatados por Parquet no armazenamento.

Virtualizar tabelas do Delta Lake como Iceberg

Para configurar a conversão automática e a virtualização de tabelas do formato Delta Lake para o formato Iceberg, siga estas etapas.

Habilite a virtualização automática de tabelas do Delta Lake para o formato Iceberg ativando a configuração delegada do OneLake chamada Habilitar o Delta Lake para a virtualização de formato de tabela do Apache Iceberg nas configurações do workspace.

Observação

Essa configuração controla um recurso que está atualmente em versão prévia. Essa configuração será removida em uma atualização futura quando o recurso estiver habilitado para todos os usuários e não estiver mais em versão prévia.
Verifique se a tabela Delta Lake, ou um atalho para ela, está localizada na Tables seção do item de dados. O item de dados pode ser um lakehouse ou outro item de dados do Fabric.

Dica

Se o lakehouse tiver o esquema habilitado, o diretório da tabela ficará localizado diretamente dentro de um esquema como dbo. Se o lakehouse não tiver suporte a esquemas, o diretório da tabela ficará diretamente dentro do diretório Tables.
Confirme se a tabela Delta Lake foi convertida com sucesso para o formato Iceberg virtual. Você pode fazer isso examinando o diretório por trás da tabela.

Para exibir o diretório se a tabela estiver em um lakehouse, clique com o botão direito do mouse na tabela na interface do usuário do Fabric e selecione Exibir arquivos.

Se a tabela estiver em outro tipo de item de dados, como um warehouse, um banco de dados ou um banco de dados espelhado, você precisará usar um cliente como o Gerenciador de Armazenamento do Azure ou o Gerenciador de Arquivos Do OneLake, em vez da interface do usuário do Fabric, para exibir os arquivos atrás da tabela.
Você deverá ver um diretório nomeado metadata dentro da pasta da tabela e ele deve conter vários arquivos, incluindo o arquivo de log de conversão. Abra o arquivo de log de conversão para ver mais informações sobre a conversão de Delta Lake para Iceberg, incluindo o carimbo de data/hora da conversão mais recente e quaisquer detalhes de erro.
Se o arquivo de log de conversão mostrar que a tabela foi convertida com êxito, leia a tabela Iceberg usando seu serviço, aplicativo ou biblioteca de sua escolha.

Dependendo do leitor de Iceberg usado, você precisará saber o caminho para o diretório de tabela ou para o arquivo mais recente .metadata.json mostrado no metadata diretório.

Você pode ver o caminho HTTP para o arquivo de metadados mais recente da tabela abrindo a exibição Propriedades do *.metadata.json arquivo com o número de versão mais alto. Anote este caminho.

O caminho para a pasta do seu item de dado Tables pode ter esta aparência:
```
https://onelake.dfs.fabric.microsoft.com/83896315-c5ba-4777-8d1c-e4ab3a7016bc/a95f62fa-2826-49f8-b561-a163ba537828/Tables/
```
Dentro dessa pasta, o caminho relativo para o arquivo de metadados mais recente pode ser semelhante dbo/MyTable/metadata/321.metadata.json.

Para ler sua tabela Iceberg virtual usando Snowflake, siga as etapas neste guia.

Crie um atalho de tabela para uma tabela Iceberg

Se você já tiver uma tabela Iceberg em um local de armazenamento compatível com atalhos do OneLake, siga essas etapas para criar um atalho e fazer com que sua tabela Iceberg apareça com o formato Delta Lake.

Localize sua mesa Iceberg. Descubra onde sua tabela Iceberg está armazenada, o que pode ser no Azure Data Lake Storage, OneLake, Amazon S3, Google Cloud Storage ou um serviço de armazenamento compatível com S3.

Observação

Se você estiver usando o Snowflake e não tiver certeza de onde sua tabela Iceberg está armazenada, você pode executar a seguinte instrução para ver o local de armazenamento da sua tabela Iceberg.

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

A execução dessa instrução retorna um caminho para o arquivo de metadados da tabela Iceberg. Esse caminho informa qual conta de armazenamento contém a tabela Iceberg. Por exemplo, aqui estão as informações relevantes para encontrar o caminho de uma tabela Iceberg armazenada no 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"}

A pasta da sua tabela Iceberg precisa conter uma pasta metadata, que contém pelo menos um arquivo terminado em .metadata.json.
Em seu Fabric Lakehouse, crie um novo atalho de tabela na área Tabelas de uma casa do lago.

Dica

Se você vir esquemas como o "dbo" na pasta Tabelas do seu lakehouse, então o lakehouse está habilitado para esquemas. Nesse caso, clique com o botão direito do mouse no esquema e crie um atalho de tabela no esquema.
Para o caminho de destino do seu atalho, selecione a pasta da tabela Iceberg. A pasta da tabela Iceberg contém as pastas metadata e data.
Depois que seu atalho for criado, você verá automaticamente essa tabela refletida como uma tabela Delta Lake em seu lakehouse, pronta para uso em todo o Fabric.

Se o seu novo atalho de tabela Iceberg não aparecer como uma tabela utilizável, verifique a seção Solução de problemas.

Solução de problemas

As dicas a seguir podem ajudar a garantir que suas mesas Iceberg sejam compatíveis com esse recurso:

Verifique a estrutura de pastas da sua tabela Iceberg

Abra sua pasta Iceberg na sua ferramenta de armazenamento preferida e verifique a listagem de diretórios da sua pasta Iceberg em seu local original. Você deverá ver uma estrutura de pastas como no exemplo a seguir.

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

Se você não vir a pasta de metadados ou se não vir arquivos com as extensões mostradas nesse exemplo, talvez você não tenha uma tabela Iceberg gerada corretamente.

Verifique o log de conversão

Quando uma tabela Iceberg é virtualizada como uma tabela Delta Lake, uma pasta chamada _delta_log/ pode ser encontrada dentro da pasta de atalho. Essa pasta contém os metadados do formato Delta Lake (o log Delta) após a conversão bem-sucedida.

Essa pasta também inclui o arquivo latest_conversion_log.txt, que contém os detalhes do sucesso ou falha da última tentativa de conversão.

Para ver o conteúdo desse arquivo após criar seu atalho, abra o menu do atalho da tabela Iceberg na área Tabelas do seu lakehouse e selecione Exibir arquivos.

Captura de tela do item de menu Exibir arquivos.

Você deverá ver uma estrutura como o exemplo a seguir:

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 o arquivo de log de conversão para ver o horário da conversão mais recente ou os detalhes da falha. Se você não vir um arquivo de log de conversão, a conversão não foi tentada.

Se a conversão não foi tentada

Se você não vir um arquivo de log de conversão, a conversão não foi tentada. Aqui estão dois motivos comuns pelos quais a conversão não é tentada:

O atalho não foi criado no lugar certo.

Para que um atalho para uma tabela Iceberg seja convertido para o formato Delta Lake, o atalho deve ser colocado diretamente na pasta Tabelas de um lakehouse não habilitado para esquema. Você não deve colocar o atalho na seção Arquivos ou em outra pasta se quiser que a tabela seja virtualizada automaticamente como uma tabela Delta Lake.
O caminho de destino do atalho não é o caminho da pasta Iceberg.

Ao criar o atalho, o caminho da pasta selecionado no local de armazenamento de destino deve ser somente a pasta da tabela Iceberg. Essa pasta contém as pastas metadata e data.

Mensagem de erro no Snowflake: "Não é possível validar a região de capacidade do fabric"

Se você estiver usando o Snowflake para escrever uma nova tabela iceberg no OneLake, poderá ver a seguinte mensagem de erro:

A região de capacidade do tecido não pode ser validada. Motivo: 'Token de acesso inválido. Isso pode ser devido à autenticação e à definição de escopo. Verifique os escopos delegados.

Se você vir esse erro, peça ao administrador do locatário do Fabric para verificar se você habilitou ambas as configurações de locatário mencionadas na seção Gravar uma tabela Iceberg no OneLake usando Snowflake.

No canto superior direito da interface do usuário do Fabric, abra Configurações e selecione o portal de administração.
Nas configurações de locatário, na seção Configurações do Desenvolvedor, habilite a configuração rotulada Principais de serviço podem usar APIs do Fabric.
Na mesma área, na seção de configurações do OneLake , habilite a configuração rotulada Os usuários podem acessar dados armazenados no OneLake com aplicativos externos ao Fabric.

Limitações e considerações

Tenha em mente as seguintes limitações temporárias ao usar esse recurso:

Tipos de dados com suporte

Os seguintes tipos de dados da coluna Iceberg são mapeados para seus tipos Delta Lake correspondentes usando esse recurso.

Tipo de coluna iceberg	Tipo de coluna Delta Lake	Comentários
`int`	`integer`
`long`	`long`	Veja Problema de largura de tipo.
`float`	`float`
`double`	`double`	Veja Problema de largura de tipo.
`decimal(P, S)`	`decimal(P, S)`	Veja Problema de largura de tipo.
`boolean`	`boolean`
`date`	`date`
`timestamp`	`timestamp_ntz`	O tipo de dados `timestamp` Iceberg não contém informações de fuso horário. O tipo `timestamp_ntz` Delta Lake não é totalmente suportado em cargas de trabalho do Fabric. Recomendamos o uso de carimbos de data/hora com fusos horários incluídos.
`timestamptz`	`timestamp`	No Snowflake, para usar esse tipo, especifique `timestamp_ltz` como o tipo de coluna durante a criação da tabela Iceberg. Mais informações sobre os tipos de dados Iceberg suportados no Snowflake podem ser encontradas aqui.
`string`	`string`
`binary`	`binary`
`time`	Não aplicável	Sem suporte

Problema de largura de tipo

Se você usar o Snowflake para escrever sua tabela Iceberg e a tabela contiver tipos de coluna INT64, double ou Decimal com precisão >= 10, a tabela virtual Delta Lake resultante poderá não ser consumível por todos os mecanismos do Fabric. Você pode ver erros como:
```
Parquet column cannot be converted in file ... Column: [ColumnA], Expected: decimal(18,4), Found: INT32.
```
Estamos trabalhando para corrigir esse problema.

Solução alternativa: Se você estiver usando a interface de visualização de tabela do Lakehouse e observar esse problema, poderá resolver esse erro alternando para a exibição do SQL Endpoint (canto superior direito, selecione a exibição do Lakehouse, alterne para o SQL Endpoint) e visualizando a tabela a partir daí. Se você retornar para a visualização Lakehouse, a visualização da tabela deverá ser exibida corretamente.

Se você estiver executando um notebook ou trabalho do Spark e encontrar esse problema, poderá resolver esse erro definindo a configuração spark.sql.parquet.enableVectorizedReader Spark como false. Aqui está um exemplo de comando PySpark para executar em um notebook Spark:
```
spark.conf.set("spark.sql.parquet.enableVectorizedReader","false")
```
O armazenamento de metadados da tabela Iceberg não é portátil

Os arquivos de metadados de uma tabela Iceberg referem-se uns aos outros usando referências de caminho absolutas. Se você copiar ou mover o conteúdo da pasta de uma tabela Iceberg para outro local sem reescrever os arquivos de metadados do Iceberg, a tabela se tornará ilegível para os leitores Iceberg, incluindo esse recurso do OneLake.

Solução alternativa:

Se você precisar mover sua tabela Iceberg para outro local para usar esse recurso, use a ferramenta que escreveu originalmente a tabela Iceberg para escrever uma nova tabela Iceberg no local desejado.
As pastas da tabela Iceberg devem conter apenas um conjunto de arquivos de metadados

Se você remover e recriar uma tabela Iceberg no Snowflake, os arquivos de metadados não serão limpos. Esse comportamento é por design, em suporte ao UNDROP recurso no Snowflake. Entretanto, como seu atalho aponta diretamente para uma pasta e essa pasta agora tem vários conjuntos de arquivos de metadados dentro dela, não podemos converter a tabela até que você remova os arquivos de metadados da tabela antiga.

A conversão falhará se mais de um conjunto de arquivos de metadados for encontrado na pasta de metadados da tabela Iceberg.

Solução alternativa:

Para garantir que a tabela convertida reflita a versão correta da tabela:
- Certifique-se de não armazenar mais de uma tabela Iceberg na mesma pasta.
- Limpe todo o conteúdo de uma pasta de tabela Iceberg após removê-la, antes de recriá-la.
As alterações de metadados não são imediatamente refletidas

Se você fizer alterações de metadados na sua tabela Iceberg, como adicionar uma coluna, excluir uma coluna, renomear uma coluna ou alterar um tipo de coluna, a tabela poderá não ser reconvertida até que uma alteração de dados seja feita, como adicionar uma linha de dados.

Estamos trabalhando em uma correção que coleta o arquivo de metadados mais recente e correto que inclui a alteração de metadados mais recente.

Solução alternativa:

Depois de fazer a alteração de esquema na sua tabela Iceberg, adicione uma linha de dados ou faça qualquer outra alteração nos dados. Após essa alteração, você poderá atualizar e ver a visualização mais recente da sua tabela no Fabric.
Limitação de disponibilidade da região

O recurso ainda não está disponível nas seguintes regiões:
- Catar Central
- Oeste da Noruega
Solução alternativa:

Espaços de trabalho anexados às capacidades do Fabric em outras regiões podem usar esse recurso. Veja a lista completa de regiões onde o Microsoft Fabric está disponível.
Links privados não suportados

Atualmente, esse recurso não é compatível com locatários ou espaços de trabalho que tenham links privados habilitados.

Estamos trabalhando em uma melhoria para remover essa limitação.
Os atalhos do OneLake devem ser da mesma região

Temos uma limitação temporária no uso desse recurso com atalhos que apontam para locais do OneLake: o local de destino do atalho deve estar na mesma região que o próprio atalho.

Estamos trabalhando em uma melhoria para remover esse requisito.

Solução alternativa:

Se você tiver um atalho do OneLake para uma mesa Iceberg em outro lakehouse, certifique-se de que o outro lakehouse esteja associado a uma capacidade na mesma região.
Não há suporte para determinados tipos de transformação de partição do Iceberg

Atualmente, os tipos de partição iceberg, bucket[N], truncate[W], e void não são suportados.

Se a tabela Iceberg que está sendo convertida contiver esses tipos de transformação de partição, a virtualização no formato Delta Lake não terá êxito.

Estamos trabalhando em uma melhoria para remover essa limitação.

Use Snowflake para escrever ou ler tabelas Iceberg no OneLake.
Saiba mais sobre a segurança do Fabric e do OneLake.
Saiba mais sobre atalhos OneLake.