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

Esta página descreve como usar o ALTER TABLE ... SET MANAGED comando para converter uma tabela externa em uma tabela gerenciada do Catálogo do Unity no Azure Databricks.

visão geral do SET MANAGED

Utilize o SET MANAGED recurso para converter uma tabela externa em uma tabela gerenciada pelo Unity Catalog no Azure Databricks. SET MANAGED oferece os seguintes benefícios:

• Minimizando o tempo de inatividade do leitor e do gravador.
• Manipulando escritas simultâneas durante a conversão.
• Preservando o histórico de uma tabela.
• Mantendo as mesmas configurações de tabela, incluindo o mesmo nome, configurações, permissões e exibições.
• Capacidade de reverter uma tabela gerenciada convertida para uma tabela externa.

Prerequisites

Para usar o recurso de conversão de tabela, você deve atender aos seguintes pré-requisitos:

• Todos os leitores e escritores para as tabelas externas devem usar o acesso com base em nome. Por exemplo:

  SELECT * FROM catalog_name.schema_name.table_name;
  

  Não há suporte para acesso baseado em caminho e pode falhar após a conversão da tabela.

• Você deve usar o Databricks Runtime 17.0 ou superior ou computação sem servidor, para usar SET MANAGED ou UNSET MANAGED.

• Para converter tabelas do Catálogo do Unity com leituras de Iceberg (UniForm) já habilitadas, você deve usar o Databricks Runtime 17.2 ou superior ou computação sem servidor para usar TRUNCATE UNIFORM HISTORY.

• Os leitores e gravadores do Azure Databricks devem usar o Databricks Runtime 15.4 LTS ou superior. Se seus leitores ou gravadores usarem 14.3 LTS ou abaixo, consulte a opção Alternativa para leitores e gravadores no Databricks Runtime 14.3 LTS ou abaixo.

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

• Clientes externos (não Databricks) devem suportar leituras em tabelas gerenciadas do Catálogo Unity. Consulte Leia tabelas com clientes Delta.

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

Converter de externo para tabela gerenciada

Execute um dos seguintes comandos para converter sua tabela externa do Catálogo do Unity em uma tabela gerenciada do Catálogo do Unity.

• Para tabelas externas do Catálogo do Unity sem leituras do Apache Iceberg (UniForm) habilitadas:

  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 Unity Catalog com leituras no Iceberg (UniForm) já habilitadas:

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

  Nesse caso, inclua TRUNCATE UNIFORM HISTORY para manter o desempenho e a compatibilidade da tabela ideal. TRUNCATE UNIFORM HISTORY Trunca somente o histórico do UniForm Iceberg e não remove o histórico Delta. Esse comando resulta em um tempo de inatividade de leitura e gravação curto para Iceberg após o truncamento.

Se o comando for interrompido durante a cópia de dados, você poderá reiniciá-lo e ele continuará de onde você parou.

Após a conversão da tabela, você deve:

• Reinicie todos os trabalhos de streaming (leitura ou gravação) usando a tabela externa.
• Verifique se seus leitores e escritores trabalham com a tabela gerenciada.

A otimização preditiva é habilitada automaticamente, exceto se você a desabilitou manualmente. Confira Se a otimização preditiva está habilitada.

Com a otimização preditiva habilitada, o Azure Databricks exclui automaticamente os dados em seu local externo do Catálogo do Unity após 14 dias. Se a otimização preditiva estiver desabilitada, você poderá executar VACUUM (requer o Databricks Runtime 17.0 ou superior ou computação sem servidor) na tabela gerenciada recém-convertida após 14 dias.

VACUUM my_converted_table

O Azure Databricks exclui apenas os dados no local externo. O log de transações Delta e a referência à tabela no Unity Catalog são mantidos.

Verificar conversão

Você pode confirmar se a tabela externa foi convertida em uma tabela gerenciada:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Verifique a saída deste comando para confirmar se a tabela foi convertida. A tabela Type deve ser mostrada como MANAGED.

Se você estiver exibindo as informações da tabela no Gerenciador de Catálogos, atualize a página. Na guia Detalhes , em Sobre esta tabela, o tipo de tabela deve ser mostrado como MANAGED.

Opção alternativa para usuários de leitura e escrita no Databricks Runtime versão 14.3 LTS ou inferior

O Databricks recomenda que você atualize todos os leitores e gravadores para o Databricks Runtime 15.4 LTS ou superior para aproveitar o SET MANAGED comando, incluindo a capacidade de manter o histórico da tabela.

Você ainda poderá usar o SET MANAGED comando se tiver leitores ou gravadores com o Databricks Runtime 14.3 ou inferior. No entanto, depois de converter em uma tabela gerenciada, você não pode retroceder para commits históricos por carimbo de data/hora. Você só pode fazer isso por versão. Se você reverter para uma tabela externa dentro da janela de 14 dias, o recurso de viagem no tempo para confirmações históricas realizadas antes da conversão será ativado novamente.

Em todos os casos (independentemente da versão do Databricks Runtime), reverter para o UC externo usando carimbo de data/hora não funciona para commits realizados na tabela gerenciada do UC convertida, entre o momento em que você terminou a conversão e antes de tentar reverter.

Escrever em uma tabela com o Databricks Runtime 15.4 LTS ou uma versão inferior, após a conversão, exige a remoção da funcionalidade inCommitTimestamp:

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

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 invá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.

Reverter para uma tabela externa

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

Se você reverter, as confirmações feitas no local externo entre a conversão e a reversão poderão ser acessadas por versão, mas não por marca temporal. Sete dias após a reversão, os dados no local gerenciado serão excluídos.

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, você poderá executar novamente para tentar novamente, semelhante ao SET comando MANAGED.

Verificar a reversão

Você pode confirmar que sua conversão foi revertida.

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Verifique a saída deste comando para confirmar se a tabela foi revertida. A tabela Type deve ser mostrada como EXTERNAL.

Se você estiver exibindo as informações da tabela no Gerenciador de Catálogos, atualize a página. Na guia Detalhes , em Sobre esta tabela, o tipo de tabela deve ser mostrado como EXTERNAL.

Você também deve reiniciar seus trabalhos de streaming depois de reverter para uma tabela externa, semelhante ao processo de conversão.

Tempo de inatividade e tempos de cópia de dados

Pode haver tempo de inatividade quando leitores ou gravadores acessam a tabela durante a conversão. No entanto, em comparação com o comando 'DEEP CLONE', o comando SET MANAGED minimiza ou elimina o tempo de inatividade para leitores e escritores. Os leitores no Databricks Runtime 16.1 ou superior não experimentam nenhum tempo de inatividade. Durante a primeira etapa, quando os dados da tabela e o log delta são copiados, os leitores e gravadores não são afetados.

Durante a segunda etapa, as escritas no local externo do Unity Catalog são bloqueadas, e os commits feitos no local externo durante a primeira cópia de dados serão movidos para lá. Esta segunda etapa de cópia de dados incorrerá em tempo de inatividade para gravadores e leitores no Databricks Runtime 15.4 LTS ou abaixo.

Depois disso, os leitores e escritores são transferidos para o local gerenciado do Catálogo do Unity e o novo local da tabela gerenciada é registrado no Catálogo do Unity. Os leitores com o Databricks Runtime 16.1 ou superior experimentarão um equivalente a nenhum tempo de inatividade.

O tempo de inatividade estimado é:

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

Limitações conhecidas

A conversão externa em tabelas gerenciadas tem as seguintes limitações:

• Clientes de streaming: você deve reiniciar todos os trabalhos de streaming após a conversão.

• Restrições de histórico de tabela após a reversão: para leitores/gravadores no Databricks Runtime 15.4 LTS ou superior, o histórico de tabela para confirmações feitas após a conversão, mas antes da reversão, será acessível por versão, mas não por carimbo de data/hora.

• Limitações de compartilhamento delta: o SET MANAGED comando não é totalmente compatível com o Compartilhamento Delta. Embora o compartilhamento Delta aberto funcione conforme o esperado, o compartilhamento entre Databricks não atualiza automaticamente o local gerenciado 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;
  

• Várias regiões de nuvem: 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 que está sendo convertida, você poderá incorrer em custos adicionais de transferência de dados entre regiões. O provedor de nuvem impõe esses encargos fora do controle do Databricks.

  Para verificar os locais de seu esquema, catálogo e metastore, você pode usar os seguintes comandos:

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