Converter uma tabela externa em uma tabela gerenciada do Catálogo Unity

Esta página descreve como converter uma tabela externa numa tabela gerida pelo Unity Catalog no Azure Databricks usando o ALTER TABLE ... SET MANAGED comando ou Catalog Explorer.

SET MANAGED Visão geral

Use SET MANAGED para converter uma tabela externa numa tabela gerida pelo Unity Catalog. Embora também possa usar CREATE TABLE AS SELECT (CTAS) para conversão, a Databricks recomenda SET MANAGED pelos seguintes benefícios:

• Minimiza o tempo de inatividade do leitor e do escritor.
• Gestiona as escritas simultâneas durante a conversão.
• Mantém o histórico da tabela.
• Mantém as mesmas configurações de tabelas, incluindo nome, definições, permissões e vistas.
• Suporta a reversão de uma tabela gerida convertida para uma tabela externa.

Prerequisites

• Todos os leitores e escritores das tabelas externas devem usar acesso baseado no nome. Por exemplo:

  SELECT * FROM catalog_name.schema_name.table_name;
  

  O acesso baseado em caminho não é suportado e pode falhar após a conversão da tabela.

• Deve usar o Databricks Runtime 17.0 ou superior, ou computação sem servidor, para utilizar SET MANAGED ou UNSET MANAGED.

• Para converter tabelas do Unity Catalog com leituras Iceberg (UniForm) já ativadas, deve usar Databricks Runtime 17.2 ou superior ou computação Serverless para usar TRUNCATE UNIFORM HISTORY.

• Os leitores e gravadores do Azure Databricks devem usar o Databricks Runtime 15.4 LTS ou superior. Se os seus leitores ou escritores usam o 14.3 LTS ou inferior, consulte Opção alternativa para leitores e escritores no Databricks Runtime 14.3 LTS ou inferior.

• O SET MANAGED comando falhará com um DELTA_TRUNCATED_TRANSACTION_LOG erro se a tabela tiver minReaderVersion=2, minWriterVersion=7e tableFeatures={..., columnMapping}. Pode verificar se a sua tabela tem estas propriedades usando DESCRIBE DETAIL.

• Clientes externos (não Databricks) devem suportar leituras de tabelas geridas do Unity Catalog. Veja Ler tabelas com clientes Delta.

  • Use o painel do Access Insights para ver se os leitores e gravadores que acessam suas tabelas são Databricks Runtime ou não-Databricks externos.

Converter de tabela externa para tabela gerida

Explorador de Catálogos

Quando converte usando o Explorador de Catálogo, o acesso baseado em nome é usado automaticamente. Podes converter uma ou mais tabelas externas num esquema de cada vez.

1. Vai à tabela ou esquema que queres converter no Explorador de Catálogos.

2. Em Sobre esta tabela (página de detalhe da tabela) ou Sobre este esquema (página de detalhe do esquema), clique em Explorar otimizações.

3. No diálogo Porquê migrar para tabelas geridas do Unity Catalog? , clique em Continuar.

   

4. Seleciona as tabelas externas que queres converter. Se abriste o diálogo a partir de uma página de detalhes da tabela, a tua tabela está pré-selecionada. Use a barra de pesquisa para encontrar tabelas adicionais. As tabelas geridas não são selecionáveis.

   

5. Clique em Criar caderno de conversão.

6. Opcionalmente, introduza um nome para o caderno. Por defeito, o caderno é guardado na tua pasta principal. Clique em Explorar para guardar noutro local.

   

7. No caderno, revê as melhores práticas e verifica se cumpres todos os pré-requisitos.

8. Executa a SET célula de Consultas GERIDAS .

Após a execução da célula, o tipo de tabela aparece como MANAGED em vez de EXTERNAL no Explorador de Catálogos. Atualize a página caso o estado não seja atualizado imediatamente.

SQL

Dependendo se a sua tabela externa tem o Apache Iceberg reads (UniForm) ativado, execute um dos seguintes comandos. Veja Verificar que as leituras Iceberg (UniForm) estão ativadas para verificar se a sua tabela tem as leituras Apache Iceberg (UniForm) ativadas.

• Para tabelas externas do Unity Catalog sem leituras do Apache Iceberg (UniForm) habilitadas:

  ALTER TABLE catalog.schema.my_external_table SET MANAGED;
  

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

• Para tabelas externas do Unity Catalog com leituras do Apache Iceberg (UniForm) já ativadas:

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

  Incluir TRUNCATE UNIFORM HISTORY para manter o desempenho e compatibilidade ótimos da tabela. TRUNCATE UNIFORM HISTORY trunca apenas a história do UniForm Iceberg e não remove a história do Delta. Este comando resulta em um curto tempo de inatividade de leitura e gravação para o Iceberg após o truncamento.

Se o comando for interrompido durante a cópia dos dados, reinicie-o e ele continua de onde ficou.

Após a conversão da tabela, deve fazer o seguinte:

• Reinicie quaisquer tarefas de streaming (leitura ou escrita) usando a tabela externa para evitar ler ou escrever na localização anterior. Pare o emprego atual e comece um novo com a mesma configuração.
• Verifique se os seus leitores e escritores estão a trabalhar com a tabela gerida.

A otimização preditiva é ativada automaticamente após a conversão, a menos que a tenhas desativado manualmente. Veja Verificar se a otimização preditiva está ativada.

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

VACUUM my_converted_table

Verificar conversão

Explorador de Catálogos

Atualize a página. No separador Detalhes , em Sobre esta tabela, o Tipo de tabela é apresentado como Gerido.

SQL

Execute o seguinte comando para confirmar que a sua tabela externa foi convertida numa tabela gerida:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

A tabela Type apresenta-se como MANAGED.

Opção alternativa para leitores e escritores no Databricks Runtime 14.3 LTS ou inferior

A Databricks recomenda atualizar todos os leitores e escritores para Databricks Runtime 15.4 LTS ou superior, para tirar partido de SET MANAGED, incluindo a capacidade de manter o histórico das tabelas.

Ainda pode usar SET MANAGED se tiver leitores ou escritores no Databricks Runtime 14.3 ou inferior. No entanto, depois de converter para uma tabela gerida, não se pode viajar no tempo para commits históricos por timestamp — apenas por versão. Se voltares para uma tabela externa na janela de 14 dias, a viagem no tempo até aos commits históricos feitos antes da conversão é reativada.

Em todos os casos, reverter para uma tabela externa do Unity Catalog utilizando um timestamp não funciona para quaisquer commits feitos na sua tabela convertida e gerida do Unity Catalog entre a conversão e o rollback.

Escrever numa tabela após a conversão com o Databricks Runtime 15.4 LTS ou inferior requer a remoção do recurso inCommitTimestamp.

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Resolução de falhas de conversão

Esta seção descreve problemas comuns ao converter tabelas externas em tabelas gerenciadas do Unity Catalog e como resolvê-los.

Consistência da versão em tempo de execução do Databricks

Evite executar ou tentar novamente 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 novamente a mesma versão do Databricks Runtime.

Desligamento do cluster durante a conversão

Se o cluster desligar 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 da tabela não válido), a conversão pode falhar com erros como DELTA_TRUNCATED_TRANSACTION_LOG, DELTA_TXN_LOG_FAILED_INTEGRITY, ou DELTA_STATE_RECOVER_ERRORS. Antes de tentar a conversão, verifique se consegue executar operações básicas na tabela externa, como DESCRIBE DETAIL.

Falha na validação de ficheiros

O comando SET MANAGED valida que todos os ficheiros no último snapshot da tabela são copiados para a nova localização gerida da tabela. Se algum ficheiro estiver em falta, o comando falha com um DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED erro.

Para resolver este problema:

1. Verifique os registos dos drivers do Spark para identificar quais os ficheiros que não puderam ser migrados.
2. Verifique se estes ficheiros existem na localização da tabela externa de origem e são acessíveis.
3. Tenta novamente o ALTER TABLE ... SET MANAGED comando.

Se o problema persistir, contacte o suporte da Databricks.

Voltar para uma tabela externa

Depois de converter uma tabela externa em uma tabela gerenciada, você pode reverter dentro de 14 dias.

Quando recuas, os metadados da tabela são atualizados para apontar para a localização externa original. Todas as escritas feitas na localização gerida após a conversão são preservadas. Os commits feitos no local gerido entre a conversão e o rollback continuam a ser viáveis no tempo por versão, mas não por data e hora.

Sete dias após o rollback, o Azure Databricks apaga automaticamente os dados na localização gerida.

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

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

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

Também tens de reiniciar os teus trabalhos de streaming depois de reverter, tal como acontece com a conversão.

Verificar reversão

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

DESCRIBE EXTENDED catalog_name.schema_name.table_name

A tabela Type apresenta-se como EXTERNAL.

Se estiver a visualizar a tabela no Explorador de Catálogos, atualize a página. No separador Detalhes , em Sobre esta tabela, o Tipo de tabela apresenta-se como EXTERNAL.

Períodos 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 utiliza uma abordagem em dois passos:

1. Cópia inicial dos dados (sem tempo de inatividade): Os dados da tabela e o registo de transações Delta são copiados da localização externa para a localização gerida. Leitores e escritores continuam a operar normalmente sem impacto nas operações em andamento.
2. Mudança para localização gerida (breve tempo de inatividade): Os commits feitos para a localização externa durante a primeira etapa são movidos para a localização gerida, e os metadados da tabela são atualizados para registar a nova localização gerida. Durante este passo, todas as escritas na localização externa são temporariamente bloqueadas, resultando em tempo de inatividade do escritor. Leitores no Databricks Runtime 16.1 ou superior não experienciam tempo de inatividade; os leitores no Databricks Runtime 15.4 podem experienciar períodos de inatividade.

Tempo de inatividade estimado:

As estimativas assumem uma taxa de transferência de 0,5-2 GB/núcleo de CPU/minuto.

Limitações conhecidas

• Clientes de streaming: Tens de reiniciar qualquer trabalho de streaming após a conversão.

• Restrições do histórico da tabela após rollback: O histórico da tabela para commits feitos após a conversão, mas antes do rollback, pode ser acessado por versão, mas não por marca temporal.

• Limitações da partilha Delta: O SET MANAGED comando não é totalmente compatível com o Delta Sharing. O Open Delta Sharing funciona como esperado, mas a partilha Databricks-para-Databricks não atualiza automaticamente a localização gerida da tabela destinatária. O destinatário continua a ler a partir do local antigo até que a tabela seja compartilhada novamente. 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;
  

• Múltiplas regiões de nuvem: Se a localização gerida por defeito do seu metastore, catálogo ou esquema do Catálogo Unity estiver numa região de cloud diferente da localização de armazenamento da tabela externa, poderá incorrer em custos adicionais de transferência de dados entre regiões. O provedor de nuvem impõe essas cobranças fora do controle da Databricks.

  Para verificar as localizações 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;