Converter uma tabela externa do Delta Lake para uma tabela gerenciada no Unity Catalog

Para converter uma tabela externa em uma tabela gerenciada pelo Unity Catalog no Azure Databricks, use o comando ALTER TABLE ... SET MANAGED ou o Explorador de Catálogos. A conversão minimiza o tempo de inatividade e retém o histórico, as permissões e as exibições da tabela.

SET MANAGED Visão geral

Use SET MANAGED para converter uma tabela externa em uma tabela gerenciada do Catálogo do Unity. Embora você também possa usar CREATE TABLE AS SELECT (CTAS) para conversão, o Databricks recomenda os seguintes SET MANAGED benefícios:

• Minimiza o tempo de inatividade do leitor e do gravador.
• Gerencia operações de gravações simultâneas durante a conversão.
• Retém o histórico da tabela.
• Mantém as mesmas configurações de tabela, incluindo nome, configurações, permissões e exibições.
• Dá suporte à reversão de uma tabela gerenciada convertida em uma tabela externa.
• Redireciona leituras e gravações baseadas em caminho para permitir que o código herdado funcione após a conversão.

Prerequisites

• Você deve usar o Databricks Runtime 17.3 LTS ou superior ou a computação sem servidor para usar SET MANAGED, UNSET MANAGEDou TRUNCATE UNIFORM HISTORY.
• A tabela deve estar no formato Delta Lake.
• Os leitores e gravadores do Azure Databricks para as suas tabelas de origem devem usar o Databricks Runtime 15.4 LTS ou posterior. Se seus leitores ou gravadores utilizarem a versão 14.3 LTS ou anterior, consulte a seção Opção alternativa para leitores e gravadores no Databricks Runtime 14.3 LTS ou anterior.
• Clientes externos (que não sejam do Databricks) devem oferecer suporte à leitura de tabelas gerenciadas pelo Unity Catalog. Consulte Acessar tabelas com clientes Delta.
  • Use o painel do Access Insights para verificar se os leitores e gravadores que acessam suas tabelas são do Databricks Runtime ou externos, não pertencentes ao Databricks.
• Se a tabela tiver minReaderVersion=2, minWriterVersion=7 e tableFeatures={..., columnMapping}, o comando SET MANAGED falha com um erro DELTA_TRUNCATED_TRANSACTION_LOG. Verifique se a tabela tem essas propriedades usando DESCRIBE DETAIL. Consulte a compatibilidade de recursos e protocolos do Delta Lake.

Após a conversão, as leituras e gravações baseadas em caminho são redirecionadas automaticamente para o novo local gerenciado com uma pequena sobrecarga de desempenho. O Databricks recomenda migrar todo o acesso baseado em caminho para acesso baseado em nome para evitar a sobrecarga de desempenho. Consulte o redirecionamento baseado em caminho.

Converter de externo para tabela gerenciada

Gerenciador de Catálogos

Quando você converte usando o Gerenciador de Catálogos, o acesso baseado em nome é usado automaticamente. Você pode converter uma ou mais tabelas externas em um esquema de cada vez.

1. Vá para a tabela ou esquema que você deseja converter no Gerenciador de Catálogos.

2. Em Sobre essa tabela (página de detalhes da tabela) ou Sobre esse esquema (página de detalhes do esquema), clique em Explorar otimizações.

3. Na caixa de diálogo Por que migrar para tabelas gerenciadas do Catálogo do Unity? clique em Continuar.

   

4. Selecione as tabelas externas que você deseja converter. Se você abriu a caixa de diálogo de uma página de detalhes da tabela, sua tabela será pré-selecionada. Use a barra de pesquisa para localizar tabelas adicionais. Tabelas gerenciadas não são selecionáveis.

   

5. Clique em Criar bloco de anotações de conversão.

6. Opcionalmente, insira um nome para o bloco de anotações. Por padrão, o bloco de anotações é salvo na pasta inicial. Clique em Procurar para salvá-lo em um local diferente.

   

7. No notebook, examine as práticas recomendadas e verifique se você atende a todos os pré-requisitos.

8. Execute a célula de SET consultas MANAGED.

Após a execução da célula, o tipo de tabela é exibido como GERENCIADO em vez de EXTERNAL no Gerenciador de Catálogos. Atualize a página se o status não for atualizado imediatamente.

SQL

Dependendo se a tabela externa tem leituras do Apache Iceberg (UniForm) habilitadas, execute um dos comandos a seguir. Consulte Verificar se as leituras do Iceberg estão habilitadas para verificar se a tabela tem leituras do Apache Iceberg (UniForm) habilitadas.

• Para tabelas externas do Unity Catalog sem a função de leitura do Apache Iceberg (UniForm) habilitada:

  ALTER TABLE catalog.schema.my_external_table SET MANAGED;
  

  Após a conversão, você pode habilitar as leituras do Iceberg em sua tabela gerenciada sem preocupações de compatibilidade.

• Para tabelas externas do Catálogo Unity nas quais as leituras do Apache Iceberg (UniForm) já estão habilitadas:

  ALTER TABLE catalog.schema.my_external_table SET MANAGED TRUNCATE UNIFORM HISTORY;
  

  Inclua TRUNCATE UNIFORM HISTORY para manter o desempenho ideal da tabela e a compatibilidade. TRUNCATE UNIFORM HISTORY trunca apenas o histórico do UniForm Iceberg e não remove o histórico do Delta. Esse comando causa um breve período de inatividade nas operações de leitura e gravação do Iceberg após o truncamento.

Se o comando for interrompido durante a cópia de dados, reinicie-o. O comando retoma de onde parou.

Após a conversão da tabela, os fluxos de leitura e gravação existentes falham. Reinicie os fluxos com as mesmas configurações para usar automaticamente o redirecionamento baseado em caminho. Verifique se seus leitores e gravadores estão funcionando com a tabela gerenciada. Consulte o comportamento de Streaming.

A otimização preditiva é habilitada automaticamente após a conversão, a menos que você a desative manualmente. Consulte Verificar se a otimização preditiva está habilitada.

Com a otimização preditiva habilitada, Azure Databricks exclui automaticamente os dados no local externo do Catálogo do Unity após 14 dias. Se a otimização preditiva estiver desativada, execute VACUUM (requer o Databricks Runtime 17.3 LTS ou superior ou computação sem servidor) na tabela gerenciada recém-convertida após 14 dias.

VACUUM my_converted_table

Verificar a conversão

Gerenciador de Catálogos

Atualize a página. Na guia Detalhes , em Sobre esta tabela, o tipo de tabela é exibido como Gerenciado.

SQL

Execute o seguinte comando para confirmar se a tabela externa foi convertida em uma tabela gerenciada:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

A tabela Type é exibida como MANAGED.

Opção alternativa para leitores e gravadores no Databricks Runtime 14.3 LTS ou versões anteriores

A Databricks recomenda atualizar todos os leitores e gravadores para o Databricks Runtime 15.4 LTS ou acima para usar todos os recursos de SET MANAGED, incluindo a capacidade de preservar o histórico da tabela.

Você ainda poderá usar SET MANAGED se tiver leitores ou gravadores no Databricks Runtime 14.3 LTS ou inferior. No entanto, após a conversão para uma tabela gerenciada, você só poderá acessar commits históricos por versão, e não por carimbo de data/hora. Se você reverter para uma tabela externa dentro do intervalo de 14 dias, a função de “viagem no tempo” para acessar commits históricos realizados antes da conversão será reativada.

Em todos os casos, a viagem no tempo usando carimbos de data e hora não funciona para commits realizados na tabela gerenciada convertida entre a conversão e a reversão.

Para gravar em uma tabela após a conversão com o Databricks Runtime 15.4 LTS ou versões anteriores, é necessário excluir o recurso inCommitTimestamp:

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Redirecionamento baseado em caminho

No Databricks Runtime 18.1 e versões posteriores, após converter uma tabela externa em uma tabela gerenciada pelo Unity Catalog, as leituras e gravações baseadas em caminho no local externo anterior são redirecionadas automaticamente para o novo local gerenciado. O redirecionamento baseado em caminho reduz o tempo e o esforço necessários para migrar para tabelas gerenciadas, permitindo que o código herdado que usa caminhos de armazenamento continue funcionando sem refatoração.

Para casos de uso de baixa latência, Azure Databricks recomenda migrar o acesso baseado em caminho para acesso baseado em nome. O redirecionamento baseado em caminho adiciona várias centenas de milissegundos de sobrecarga para cada operação de leitura ou gravação baseada em caminho e exige que os logs Delta antigos permaneçam ativos no local externo do Unity Catalog. As leituras e gravações baseadas em nome não têm sobrecarga de desempenho adicional.

Comportamento de streaming

Para transmissão com redirecionamento baseado no caminho:

• O suporte para leituras está disponível no Databricks Runtime 18.1 e versões superiores.
• No Databricks Runtime 18.2 e superior, há suporte para gravações.

Após a conversão, é necessário reiniciar todas as tarefas de streaming para evitar a leitura ou gravação no local anterior da tabela.

As leituras e gravações de streaming baseadas em caminho falham e são interrompidas no próximo ponto de verificação, acompanhadas de uma mensagem de migração:

• Para leituras, o fluxo gera um erro: DELTA_STREAMING_INTERRUPTED_BY_MANAGED_TABLE_CONVERSION: The table at <path> has been converted to a Unity Catalog managed table. The stream has been stopped to ensure data consistency. Restart the stream and it will automatically resume from the last committed offset using the converted table.
• Para gravações, o primeiro microlote após a conversão gera um erro: Operation not allowed: STREAMING WRITE cannot be performed on a table with redirect feature. The no redirect rules are not satisfied [].

Para resolver erros, reinicie os fluxos com as mesmas configurações. O acesso baseado em caminho redireciona automaticamente para a tabela gerenciada.

Limitações

O redirecionamento baseado em caminho possui compatibilidade retroativa apenas para o processo de migração e não permite o acesso baseado em caminho às tabelas gerenciadas pelo Unity Catalog.

Solução de problemas de falhas de conversão

Esta seção descreve problemas comuns ao converter tabelas externas em tabelas gerenciadas do Catálogo do Unity e como resolvê-las.

Consistência de versão do Databricks Runtime

Evite executar ou repetir a conversão da mesma tabela usando diferentes versões do Databricks Runtime. Os metadados podem ser serializados de forma diferente entre versões, o que causa uma VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED falha. Se a conversão falhar, tente sempre usar a mesma versão do Databricks Runtime.

Desligamento do cluster durante a conversão

Se o cluster for desligado durante a conversão, o comando poderá falhar com DELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERROR. Repita o comando para retomar a conversão.

Tabela externa corrompida

Se a tabela externa já estiver corrompida (por exemplo, estado de tabela não válido), a conversão poderá falhar com erros como DELTA_TRUNCATED_TRANSACTION_LOG, DELTA_TXN_LOG_FAILED_INTEGRITYou DELTA_STATE_RECOVER_ERRORS. Antes de tentar a conversão, verifique se você pode executar operações básicas na tabela externa, como DESCRIBE DETAIL.

Falha na validação de arquivo

O comando SET MANAGED valida que todos os arquivos no instantâneo mais recente da tabela são copiados para o novo local da tabela gerenciada. Se houver arquivos ausentes, o comando falhará com um DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED erro.

Para resolver esse problema:

1. Verifique os logs de driver do Spark para identificar quais arquivos não puderam ser migrados.
2. Verifique se esses arquivos existem no local da tabela externa de origem e se estão acessíveis.
3. Tente novamente o ALTER TABLE ... SET MANAGED comando.

Se o problema persistir, entre em contato com o suporte do Databricks.

Reverter para uma tabela externa

Depois de converter uma tabela externa em uma tabela gerenciada, você pode reverter dentro de 14 dias usando o comando UNSET MANAGED.

A reversão das atualizações faz com que os metadados da tabela voltem a apontar para o local externo original. Todas as escritas realizadas no local gerenciado após a conversão são preservadas. Os commits realizados no local gerenciado entre a conversão e a reversão permitem a viagem no tempo por versão, mas não por carimbo de data/hora.

Sete dias após a reversão, Azure Databricks exclui automaticamente os dados no local gerenciado.

Para reverter para uma tabela externa, execute o seguinte comando:

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

Se o comando de reversão for interrompido, execute-o novamente para tentar novamente.

Você também deve reiniciar seus trabalhos de streaming após restaurar, assim como faz na conversão.

Verificar a reversão

Execute o seguinte comando para confirmar se a conversão foi revertida:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

A tabela Type é exibida como EXTERNAL.

Se você estiver exibindo a tabela no Gerenciador de Catálogos, atualize a página. Na guia Detalhes , em Sobre esta tabela, o tipo de tabela é exibido como EXTERNAL.

Tempo de inatividade e tempos de cópia de dados

O SET MANAGED comando minimiza ou elimina o tempo de inatividade em comparação com abordagens alternativas como DEEP CLONE. O processo de conversão usa uma abordagem de duas etapas:

1. Cópia inicial de dados (sem tempo de inatividade): Os dados da tabela e o log de transações Delta são copiados do local externo para o local gerenciado. Leitores e gravadores continuam operando normalmente sem impacto nas operações em andamento.
2. Alternar para o local gerenciado (breve tempo de inatividade): As confirmações feitas no local externo durante a primeira etapa são movidas para o local gerenciado e os metadados da tabela são atualizados para registrar o novo local gerenciado. Durante essa etapa, todas as gravações no local externo são temporariamente bloqueadas, resultando em tempo de inatividade do gravador. Os leitores no Databricks Runtime 16.4 LTS ou superior não experimentam tempo de inatividade, mas os leitores no Databricks Runtime 15.4 LTS podem experimentar tempo de inatividade.

A tabela a seguir mostra o tempo de inatividade estimado com base no tamanho da tabela de origem:

As estimativas pressupõem uma taxa de taxa de transferência de 0,5 a 2 GB/núcleo/minuto da CPU.

Limitações

• Você deve reiniciar todos os trabalhos de streaming após a conversão. Consulte o comportamento de Streaming.

• Histórico de tabelas para confirmações feitas após a conversão, mas antes da reversão permite viagem no tempo por versão, mas não por carimbo de data/hora.

• O OpenSharing não é totalmente compatível com o SET MANAGED comando. O OpenSharing funciona conforme o esperado, mas o compartilhamento entre Databricks não atualiza automaticamente a localização gerenciada da tabela do destinatário. O receptor continua a ler do local antigo até que a tabela seja recompartilhada. Para compartilhar novamente a tabela:

  ALTER SHARE <share_name> REMOVE TABLE <table_name>;
  ALTER SHARE <share_name> ADD TABLE <table_name> AS <table_share_name> WITH HISTORY;
  

• Se o local gerenciado padrão do seu metastore, catálogo ou esquema do Catálogo do Unity estiver em uma região de nuvem diferente do local de armazenamento da tabela externa, você poderá incorrer em custos adicionais de transferência de dados entre regiões do seu provedor de nuvem.

  Para verificar os locais do seu esquema, catálogo e metastore:

  DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;
  
  DESC CATALOG EXTENDED <catalog_name>;
  
  SELECT * FROM system.information_schema.metastores;