Partilhar via

Use tabelas Iceberg com OneLake

  • Artigo

No Microsoft OneLake, você pode criar atalhos para suas tabelas Apache Iceberg, permitindo seu uso na ampla variedade de cargas de trabalho do Fabric. Essa funcionalidade é possível através de um recurso chamado virtualização de metadados, que permite que as tabelas Iceberg sejam interpretadas como tabelas Delta Lake da perspetiva do atalho. Quando você cria um atalho para uma pasta de tabela Iceberg, o OneLake gera automaticamente os metadados Delta Lake correspondentes (o log Delta) para essa tabela, tornando os metadados Delta Lake acessíveis através do atalho.

Importante

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

Diagrama ilustrando a virtualização de metadados Delta Lake.

Embora este artigo inclua orientações para escrever tabelas Iceberg de Snowflake para OneLake, esse recurso destina-se a funcionar com qualquer tabela Iceberg com arquivos de dados Parquet.

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.

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

  2. Em sua casa de lago de malha, crie um novo atalho na área Tabelas de uma casa de lago não habilitada para esquema.

    Nota

    Se você vir esquemas como dbo na pasta Tabelas da sua casa do lago, então a casa do lago está habilitada para esquema e ainda não é compatível com esse recurso.

    Captura de tela mostrando o item de menu de criação de atalho em Tabelas.

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

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

    Captura de tela mostrando a criação bem-sucedida de atalhos da tabela Iceberg.

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

Escreva uma mesa Iceberg para OneLake usando Snowflake

Se você usar o Snowflake no Azure, poderá escrever tabelas Iceberg no OneLake seguindo estas etapas:

  1. Verifique se a capacidade do Fabric está no mesmo local do Azure que sua instância do Snowflake.

    Identifique a localização da capacidade de malha associada à sua casa de lago de malha. Abra as configurações do espaço de trabalho Malha que contém sua casa do lago.

    Captura de tela mostrando a região de capacidade da malha.

    No canto inferior esquerdo da interface da conta do Snowflake no Azure, verifique a região do Azure da conta do Snowflake.

    Captura de tela mostrando a região da conta Snowflake.

    Se essas regiões forem diferentes, você precisará usar uma capacidade de malha diferente na mesma região que sua conta do Snowflake.

  2. Abra o menu da área Arquivos da sua casa do lago, selecione Propriedades e copie o URL (o caminho HTTPS) dessa pasta.

    Captura de tela mostrando o item de menu Propriedades.

  3. Identifique sua ID de locatário do Fabric. Selecione seu perfil de usuário no canto superior direito da interface do usuário do Fabric e passe o mouse sobre o balão de informações ao lado do Nome do locatário. Copie o ID do locatário.

    Captura de ecrã a mostrar o ID do inquilino.

  4. No Snowflake, configure EXTERNAL VOLUME o seu usando o caminho para a pasta Arquivos em sua casa do lago. Mais informações sobre a configuração de volumes externos Snowflake podem ser encontradas aqui.

    Nota

    Snowflake requer que o esquema de URL seja azure://, por isso certifique-se de mudar https:// para azure://.

    CREATE OR REPLACE EXTERNAL VOLUME onelake_exvol
STORAGE_LOCATIONS =
(
    (
        NAME = 'onelake_exvol'
        STORAGE_PROVIDER = 'AZURE'
        STORAGE_BASE_URL = 'azure://<path_to_Files>/icebergtables'
        AZURE_TENANT_ID = '<Tenant_ID>'
    )
);

    Neste exemplo, todas as tabelas criadas usando esse volume externo são armazenadas no Fabric lakehouse, dentro da Files/icebergtables pasta.

  5. Agora que seu volume externo foi criado, execute o seguinte comando para recuperar a URL de consentimento e o nome do aplicativo que o Snowflake usa para gravar no OneLake. Esta aplicação é usada por qualquer outro volume externo na sua conta Snowflake.

    DESC EXTERNAL VOLUME onelake_exvol;

    A saída deste comando retorna as AZURE_CONSENT_URL propriedades e AZURE_MULTI_TENANT_APP_NAME . Tome nota de ambos os valores. O nome do aplicativo multilocatário do Azure se parece com <name>_<number>, mas você só precisa capturar a <name> parte.

  6. Abra o URL de consentimento da etapa anterior em uma nova guia do navegador. Se você quiser continuar, consinta com as permissões de aplicativo necessárias, se solicitado.

  7. De volta ao Fabric, abra seu espaço de trabalho e selecione Gerenciar acesso e, em seguida , Adicionar pessoas ou grupos. Conceda ao aplicativo usado pelo volume externo do Snowflake as permissões necessárias para gravar dados em lakehouses em seu espaço de trabalho. Recomendamos conceder a função de Colaborador .

  8. De volta ao Snowflake, use seu novo volume externo para criar uma mesa Iceberg.

    CREATE OR REPLACE ICEBERG TABLE MYDATABASE.PUBLIC.Inventory (
    InventoryId int,
    ItemName STRING
)
EXTERNAL_VOLUME = 'onelake_exvol'
CATALOG = 'SNOWFLAKE'
BASE_LOCATION = 'Inventory/';

    Com esta instrução, uma nova pasta de tabela Iceberg chamada Inventory é criada dentro do caminho da pasta definido no volume externo.

  9. Adicione alguns dados à sua tabela Iceberg.

    INSERT INTO MYDATABASE.PUBLIC.Inventory
VALUES
(123456,'Amatriciana');

  10. Finalmente, na área Tabelas da mesma casa do lago, você pode criar um atalho OneLake para sua mesa Iceberg. Através desse atalho, sua tabela Iceberg aparece como uma tabela Delta Lake para consumo em cargas de trabalho do Fabric.

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/
        |-- snow_A5WYPKGO_2o_APgwTeNOAxg_0_1_002.parquet
        |-- snow_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.

    Captura de tela mostrando o posicionamento correto de um atalho na pasta Tabelas.

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

    Captura de tela mostrando o conteúdo de um caminho de destino de atalho durante a criação do atalho.

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

  • 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 tabelas de iceberg devem ser mais profundas do que o nível da raiz

    A pasta da tabela Iceberg no armazenamento deve estar localizada em um diretório mais profundo do que o nível do bucket ou do contêiner. As tabelas de iceberg armazenadas diretamente no diretório raiz de um bucket ou contêiner podem não ser virtualizadas para o formato Delta Lake.

    Estamos trabalhando em uma melhoria para remover esse requisito.

    Solução:

    Certifique-se de que todas as tabelas do Iceberg estejam armazenadas em um diretório mais profundo do que o diretório raiz de um bucket ou contêiner.

  • 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. Esse comportamento é compatível com o UNDROP recurso 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.

    Atualmente, a conversão é tentada nesse cenário, o que pode resultar no conteúdo da tabela antiga e nas informações do esquema sendo mostradas na tabela Delta Lake virtualizada.

    Estamos trabalhando em uma correção na qual a conversão falha se mais de um conjunto de arquivos de metadados forem encontrados 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.

  • Espaços de trabalho habilitados para esquema ainda não suportados

    Se você criar um atalho Iceberg em uma casa de lago habilitada para esquema, a conversão não ocorrerá para esse atalho.

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

    Solução:

    Use uma casa de lago não habilitada para esquema com esse recurso. Você pode definir essa configuração durante a criação do lakehouse.

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

  • Limitação do tamanho da tabela

    Temos uma limitação temporária no tamanho da mesa Iceberg suportada por este recurso. O número máximo suportado de arquivos de dados do Parquet é de cerca de 5.000 arquivos de dados, ou aproximadamente 1 bilhão de linhas, seja qual for o limite encontrado primeiro.

    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.

Conteúdos relacionados