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 em Azure Databricks usando o comando ALTER TABLE ... SET MANAGED ou o Explorador de Catálogos.

`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.
Redireciona leituras e escritas baseadas em caminhos para permitir que o código legado funcione após a conversão.

Prerequisites

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 escritores do Azure Databricks devem usar 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. Consulte tabelas de acesso 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.

Após a conversão, as leituras e escritas baseadas em caminhos são automaticamente redirecionadas para a nova localização gerida com ligeira sobrecarga de desempenho. A Databricks recomenda migrar todo o acesso baseado em caminhos para acesso baseado em nomes para evitar a sobrecarga de desempenho. Veja Redirecionamento baseado em caminhos.

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 gerida

Important

Converter tabelas externas para geridas usando o Explorador de Catálogo está em fase Beta.

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.

Vai à tabela ou esquema que queres converter no Explorador de Catálogos.
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.
No diálogo Porquê migrar para tabelas geridas do Unity Catalog? , clique em Continuar.
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.
Clique em Criar caderno de conversão.
Opcionalmente, introduza um nome para o caderno. Por defeito, o caderno é guardado na tua pasta principal. Clique em Explorar para guardar noutro local.
No caderno, revê as melhores práticas e verifica se cumpres todos os pré-requisitos.
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.

Warning

O Databricks recomenda que evite executar múltiplos SET MANAGED comandos em simultâneo na mesma tabela, o que pode levar a um estado inconsistente da tabela.

Após a conversão de tabelas, os fluxos de leitura e escrita falham. Reiniciar os fluxos com as mesmas configurações para usar automaticamente o redirecionamento baseado em caminhos. Verifique se os seus leitores e escritores estão a trabalhar com a tabela gerida. Ver Comportamento de streaming.

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

Com a otimização preditiva ativada, o Azure Databricks apaga automaticamente os dados na sua localização externa do Unity Catalog após 14 dias. Se a otimização preditiva estiver desativada, execute VACUUM (requer Databricks Runtime 17.0 ou superior ou computação sem servidor) na tabela gerida recém-convertida após 14 dias.

VACUUM my_converted_table

Note

Em alguns casos, os dados na localização externa do seu Catálogo Unity podem não ser eliminados após 14 dias, mesmo com a otimização preditiva ativada — por exemplo, se a sua tabela gerida não for usada frequentemente ou for muito pequena. Nestes casos, execute VACUUM manualmente após 14 dias para remover os dados anteriores.

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

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;

Redirecionamento baseado em caminhos

Important

O redirecionamento baseado em caminhos está em Pré-visualização Pública. Para se inscrever, preencha este formulário.

No Databricks Runtime 18.1 e superiores, depois de converter uma tabela externa numa tabela gerida pelo Unity Catalog, as leituras e escritas baseadas em caminhos para a localização externa anterior redirecionam automaticamente para a nova localização gerida. O redirecionamento baseado em caminhos reduz o tempo e o esforço necessários para migrar para tabelas geridas porque permite que o código legado que acede às tabelas por caminho de armazenamento continue a funcionar sem necessidade de refatorar.

Para casos de baixa latência, o Azure Databricks recomenda que migre o acesso baseado em caminhos para o acesso baseado em nomes. O redirecionamento baseado em caminhos adiciona várias centenas de milissegundos de sobrecarga para cada leitura ou escrita baseada em caminhos, e exige que os antigos registos Delta permaneçam ativos na sua localização externa do Unity Catalog. As leituras e escritas baseadas em nomes não têm sobrecarga adicional de desempenho.

Comportamento de streaming

Para streaming com redirecionamento baseado em caminhos:

As leituras são suportadas no Databricks Runtime 18.1 ou superior.
Os registos são suportados no Databricks Runtime 18.2 ou superior.

Após a conversão, deve reiniciar todos os trabalhos de streaming para evitar ler ou escrever na posição anterior da tabela.

As leituras e escritas em streaming baseadas em caminhos falham e param no próximo checkpoint com 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 operações de escrita, o primeiro micro-lote após a conversão desencadeia 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 gerida.

Limitações

O redirecionamento baseado em caminhos fornece compatibilidade retroativa apenas para o processo de migração e não permite o acesso baseado em novos caminhos às tabelas geridas pelo Unity Catalog.

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:

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

Se o problema persistir, contacte o suporte da Databricks.

Voltar para uma tabela externa

Important

O UNSET MANAGED comando requer Databricks Runtime 17.0 ou superior, ou computação sem servidor.

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:

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

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	Armazém SQL de 32 núcleos / X-Large	~6 min ou menos	~1-2 minutos ou menos
1 TB	Armazém SQL 64-core / SQL 2X-Grande	~30 minutos	~1-2 min
10 terabytes	Armazém SQL de 256 núcleos / 4X-Large	~1,5 horas	~1-5 min

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

Note

O tempo de inatividade pode variar consoante fatores como o tamanho do ficheiro, número de ficheiros e número de commits.

Limitações

Tens de reiniciar qualquer trabalho de streaming após a conversão. Ver Comportamento de streaming.
O histórico da tabela para commits feitos após a conversão, mas antes da reversão, permite a viagem no tempo por versão, mas não por marca temporal.
A Partilha Delta não é totalmente compatível com o comando SET MANAGED. 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;
```
Se a localização gerida por defeito do seu metastore, catálogo ou esquema do Catálogo Unity estiver numa região cloud diferente da localização de armazenamento da tabela externa, poderá incorrer em custos adicionais de transferência de dados entre regiões por parte do seu fornecedor de cloud.

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

Comentários

Esta página foi útil?

Last updated on 2026-05-03

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

SET MANAGED Visão geral

Prerequisites

Converter de tabela externa para tabela gerida

Explorador de Catálogos

SQL

Verificar conversão

Explorador de Catálogos

SQL

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

Redirecionamento baseado em caminhos

Comportamento de streaming

Limitações

Resolução de falhas de conversão

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

Desligamento do cluster durante a conversão

Tabela externa corrompida

Falha na validação de ficheiros

Voltar para uma tabela externa

Verificar reversão

Períodos de inatividade e tempos de cópia de dados

Limitações

Comentários

Recursos adicionais

`SET MANAGED` Visão geral