Partilhar via

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

Esta página descreve o uso do ALTER TABLE ... SET MANAGED comando para converter uma tabela externa em uma tabela gerenciada pelo Unity Catalog no Azure Databricks.

Visão geral SET MANAGED

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

  • Minimização do tempo de inatividade do leitor e do gravador.
  • Gestão de escritas simultâneas durante a conversão.
  • Retenção do histórico da tabela.
  • Manter as mesmas configurações de tabela, incluindo o mesmo nome, definições, permissões e vistas.
  • Capacidade de reverter uma tabela gerenciada convertida para uma tabela externa.

Prerequisites

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

  • 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 a computação serverless para utilizar SET MANAGED ou UNSET MANAGED.

  • Para converter tabelas do Unity Catalog com leituras Iceberg (UniForm) já ativadas, deve usar o Databricks Runtime 17.2 ou superior ou a computação sem servidor para utilizar 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}. Você pode verificar se sua tabela tem essas 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.

Important

Para evitar conflitos, cancele todos os trabalhos de comando existentes OPTIMIZE (cluster líquido, compactação, ZORDER) operando em sua tabela e não agende nenhum trabalho enquanto converte suas tabelas externas em tabelas gerenciadas.

Converter de tabela externa para tabela gerenciada

Important

O comando SET MANAGED está disponível no Databricks Runtime 17.0 ou superior, bem como em computação serverless.

O TRUNCATE UNIFORM HISTORY comando está disponível no Databricks Runtime 17.2 ou superior e em computação sem servidor.

Execute um dos seguintes comandos para converter sua tabela externa do Unity Catalog em uma tabela gerenciada pelo Unity Catalog.

  • 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 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 ideais da tabela. TRUNCATE UNIFORM HISTORY trunca apenas o histórico do UniForm Iceberg e não remove o histórico 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 de dados, você poderá reiniciá-lo e ele continuará de onde parou.

Warning

O Databricks recomenda não executar vários SET MANAGED comandos simultaneamente na mesma tabela, o que pode levar a um estado de tabela inconsistente.

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

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

A otimização preditiva é ativada automaticamente, exceto se você a tiver desativado manualmente. Consulte 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, pode executar 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

Note

Em alguns casos, os dados em seu local externo do Catálogo Unity podem não ser excluídos após 14 dias, mesmo com a otimização preditiva ativada. Por exemplo, se a tabela gerenciada do Unity Catalog não for usada com freqüência ou for muito pequena, a exclusão automática pode não ocorrer. Nestes casos, após 14 dias, execute manualmente VACUUM (requer Databricks Runtime 17.0 ou superior ou computação serverless) sobre a tabela gerida recém-convertida para remover os dados antigos.

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 que sua tabela externa foi convertida em uma tabela gerenciada:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Verifique a saída deste comando para confirmar que a tabela foi convertida. A tabela Type deve mostrar 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 exibido como MANAGED.

Opção alternativa para leitores e escritores no Databricks Runtime 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 comando, incluindo a capacidade de reter o SET MANAGED histórico da tabela.

Você ainda pode usar o SET MANAGED comando se tiver leitores ou gravadores com o Databricks Runtime 14.3 ou inferior. No entanto, após a conversão numa tabela gerida, não pode viajar no tempo para confirmações históricas por data/hora. Só pode fazê-lo através de versões. Se reverteres para uma tabela externa na janela de 14 dias, a funcionalidade de viagem no tempo para registos históricos de commits feitos antes da transformação será reativada.

Em todos os casos (independentemente da versão DBR), reverter para UC externo por carimbo de data/hora não funciona para nenhum registo feito na sua tabela UC gerida, entre o momento em que terminou a conversão e antes de tentar reverter.

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;

Solução de problemas 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 DBR

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

Important

O UNSET MANAGED comando está disponível no Databricks Runtime 17.0 ou superior e em computação sem servidor.

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 transferidas no tempo por versão, mas não por carimbo de data/hora. 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á executá-lo novamente para tentar novamente, semelhante ao SET comando MANAGED.

Verificar 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 que a tabela foi revertida. A tabela Type deve mostrar 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 exibido como EXTERNAL.

Você também deve reiniciar os seus trabalhos de streaming após reverter para uma tabela externa, assim como ocorre na conversão.

Tempo de inatividade e tempos de cópia de dados

A interrupção pode ocorrer quando leitores ou escritores 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 paragem para leitores e escritores. Os leitores no Databricks Runtime 16.1 ou superior não experienciam nenhum tempo de inatividade. Os leitores e escritores não são afetados durante a primeira etapa, quando os dados da tabela e do log delta são copiados.

Durante a segunda etapa, as escritas no local externo do Catálogo Unity são bloqueadas, e os commits feitos no local externo durante a primeira cópia de dados serão transferidos. Esta segunda etapa de cópia de dados causará tempo de inatividade para escritores e leitores no Databricks Runtime 15.4 LTS ou inferior.

Depois disso, os leitores e gravadores são movidos para a localização gerida pelo Catálogo Unity, e a nova localização da tabela gerida é registada no Catálogo Unity. Os leitores com Databricks Runtime 16.1 ou superior praticamente não terão tempo de inatividade.

O tempo de inatividade estimado é:

Tamanho da tabela Tamanho de cluster recomendado Tempo para cópia dos dados Tempo de inatividade do leitor e do escritor
100 GB ou menos 32-core / DBSQL pequeno ~6min ou menos ~1-2min ou menos
1 TB Configuração média / 64-core / DBSQL ~30 minutos ~1-2min
10 terabytes 256-core / DBSQL x-grande ~1,5 horas ~1-5min

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

Note

O tempo de inatividade pode variar. O desempenho da conversão depende de fatores como o tamanho do arquivo, o número de arquivos e o número de confirmações.

Limitações conhecidas

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

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

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

  • Limitações do Delta Sharing: O SET MANAGED comando não é totalmente compatível com o Delta Sharing. Embora o Compartilhamento Delta aberto funcione conforme o esperado, o compartilhamento de Databricks para Databricks não atualiza automaticamente o local gerenciado da tabela de destinatários. 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;

  • Várias regiões de nuvem: se o local gerenciado padrão do metastore, catálogo ou esquema do Unity Catalog 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 essas cobranças fora do controle da Databricks.

    Para verificar os locais do 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;
  • Last updated on