Use tabelas Iceberg com OneLake

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 tabelas Iceberg diretamente 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ê escreve ou cria um atalho para uma pasta de tabela do Iceberg, o OneLake gera automaticamente metadados virtuais do Delta Lake (log Delta) para a tabela, permitindo seu uso com cargas de trabalho do Fabric. Por outro lado, as tabelas Delta Lake agora incluem metadados virtuais do Iceberg, permitindo compatibilidade com leitores do Iceberg.

Diagrama mostrando a virtualização de tabelas de Iceberg a Delta Lake.

Embora este artigo inclua orientações para o uso de tabelas Iceberg com Snowflake, esse recurso destina-se a funcionar com qualquer tabela Iceberg com arquivos de dados formatados em Parquet no armazenamento.

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

Importante

Este recurso está em pré-visualização.

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

Nota

Essa configuração controla um recurso que está atualmente em visualização. 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 visualização.
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 Fabric.

Sugestão

Se o seu lakehouse tiver um esquema habilitado, o diretório da tabela estará localizado diretamente dentro de um esquema como dbo. Se o seu lakehouse não estiver com esquema ativado, o diretório da tabela estará diretamente dentro do diretório Tables.
Confirme se a sua tabela Delta Lake foi convertida com êxito para o formato Iceberg virtual. Você pode fazer isso examinando o diretório atrás da tabela.

Para visualizar o diretório, se a sua tabela estiver em uma lakehouse, clique com o botão direito do mouse na tabela na interface do utilizador do Fabric e selecione Exibir arquivos.

Se sua tabela estiver em outro tipo de item de dados, como um depósito, um banco de dados ou um banco de dados espelhado, você precisará usar um cliente como o Gerenciador de Armazenamento do Azure ou o Explorador de Arquivos do OneLake, em vez da interface do usuário de malha, para exibir os arquivos atrás da tabela.
Você deve 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 todos os detalhes do 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 Iceberg que você usar, você precisará saber o caminho para o diretório da 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 visualização Propriedades do *.metadata.json arquivo com o número de versão mais alto. Tome nota deste caminho.

O caminho para a pasta do seu item de dados 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 ficheiro de metadados mais recente pode ter o aspeto de dbo/MyTable/metadata/321.metadata.json.

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

Criar um atalho de tabela para uma tabela Iceberg

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

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

Nota

Se você estiver usando o Snowflake e não tiver certeza de onde sua mesa Iceberg está armazenada, você pode executar a instrução a seguir para ver o local de armazenamento da sua mesa 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 localizar o caminho de uma tabela Iceberg armazenada no Armazenamento do Azure Data Lake:

{"metadataLocation":"azure://<storage_account_path>/<path_within_storage>/<table_name>/metadata/00001-389700a2-977f-47a2-9f5f-7fd80a0d41b2.metadata.json","status":"success"}

Sua pasta de tabela Iceberg precisa conter uma metadata pasta, que contém pelo menos um arquivo que termina em .metadata.json.
No seu Fabric lakehouse, crie um novo atalho de tabela na área de tabelas de um lakehouse.

Sugestão

Se vires esquemas como dbo na pasta Tabelas da tua lakehouse, então a lakehouse está habilitada para esquemas. Nesse caso, clique com o botão direito do mouse no esquema e crie um atalho de tabela sob o esquema.
Para o caminho de destino do atalho, selecione a pasta da tabela Iceberg. A pasta da tabela Iceberg contém as metadata pastas e data .
Assim que o atalho for criado, você verá automaticamente essa tabela refletida como uma tabela Delta Lake em sua casa do lago, pronta para ser usada em toda a malha.

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

Resoluçã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 em sua ferramenta de explorador de armazenamento preferida e verifique a listagem de diretórios de sua pasta Iceberg em seu local original. Você deve ver uma estrutura de pastas como o 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 neste exemplo, talvez não tenha uma tabela Iceberg gerada corretamente.

Verifique o registo de conversão

Quando uma tabela Iceberg é virtualizada como uma tabela Delta Lake, uma pasta nomeada _delta_log/ pode ser encontrada dentro da pasta de atalho. Esta 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 latest_conversion_log.txt arquivo, que contém os detalhes de sucesso ou falha da última tentativa de conversão.

Para ver o conteúdo deste arquivo depois de criar seu atalho, abra o menu do atalho da tabela Iceberg na área Tabelas da sua casa do lago e selecione Exibir arquivos.

Captura de tela Exibir arquivo item de menu.

Você deve 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 tempo de 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 sob a pasta Tabelas de uma casa de lago não habilitada 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.

Quando você cria o atalho, o caminho da pasta selecionado no local de armazenamento de destino deve ser apenas a pasta da tabela Iceberg. Esta pasta contém as metadata pastas e data .

Mensagem de erro "A região de capacidade da malha não pode ser validada" no Snowflake

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

A região de capacidade da malha não pode ser validada. Motivo: 'Token de acesso inválido. Isso pode ser devido à autenticação e à delimitação. Verifique os âmbitos delegados.»

Se você vir esse erro, peça ao administrador do locatário do Fabric que verifique se você ativou as duas configurações de locatário mencionadas na seção Gravar uma tabela Iceberg no OneLake usando o Snowflake :

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

Limitações e considerações

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

Tipos de dados suportados

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

Tipo de coluna de iceberg	Tipo de coluna Delta Lake	Comentários
`int`	`integer`
`long`	`long`	Consulte Problema de largura do tipo.
`float`	`float`
`double`	`double`	Consulte Problema de largura do tipo.
`decimal(P, S)`	`decimal(P, S)`	Consulte Problema de largura do tipo.
`boolean`	`boolean`
`date`	`date`
`timestamp`	`timestamp_ntz`	O `timestamp` tipo de dados Iceberg não contém informações de fuso horário. O `timestamp_ntz` tipo Delta Lake não é totalmente suportado em cargas de trabalho de malha. Recomendamos o uso de carimbos de data/hora com fusos horários incluídos.
`timestamptz`	`timestamp`	Em Flocos de neve, 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/A	Não suportado

Problema de largura do tipo

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

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

Se você estiver executando um bloco de anotações ou trabalho do Spark e encontrar esse problema, poderá resolver esse erro definindo a configuração do spark.sql.parquet.enableVectorizedReader Spark como false. Aqui está um exemplo de comando PySpark para ser executado em um bloco de anotações 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 absoluto. Se você copiar ou mover o conteúdo da pasta de uma tabela do Iceberg para outro local sem reescrever os arquivos de metadados do Iceberg, a tabela se tornará ilegível pelos leitores do Iceberg, incluindo esse recurso do OneLake.

Solução:

Se você precisar mover sua mesa Iceberg para outro local para usar esse recurso, use a ferramenta que originalmente escreveu 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ê soltar e recriar uma tabela Iceberg no Snowflake, os arquivos de metadados não serão limpos. Este comportamento é intencional, em apoio à funcionalidade do UNDROP no Snowflake. No entanto, 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:

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 qualquer conteúdo de uma pasta de tabela Iceberg depois de soltá-la, antes de recriar a tabela.
Alterações de metadados não refletidas imediatamente

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

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

Solução:

Depois de fazer a alteração de esquema na tabela do 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 exibiçã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:

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

Atualmente, esse recurso não é suportado para locatários ou espaços de trabalho com 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 OneLake: o local de destino do atalho deve estar na mesma região que o atalho em si.

Estamos trabalhando em uma melhoria para remover esse requisito.

Solução:

Se você tiver um atalho OneLake para uma mesa Iceberg em outra lakehouse, certifique-se de que a outra lakehouse esteja associada a uma capacidade na mesma região.
Certos tipos de transformação de partição Iceberg não são suportados

Atualmente, os tipos 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 para o formato Delta Lake não terá êxito.

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

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

Feedback

Esta página foi útil?

Last updated on 2025-07-02