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

Para converter uma tabela externa em uma tabela gerenciada do Unity Catalog no Databricks, use o comando ALTER TABLE ... SET MANAGED ou o Catalog Explorer. A conversão minimiza o tempo de inatividade e retém o histórico, as permissões e as views da tabela.

Visão geralSET MANAGED

Use SET MANAGED para converter uma tabela externa em uma tabela gerencia Unity Catalog . Embora você 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.
• Gerencia gravações concorrentes durante a conversão.
• Mantém a história da tabela.
• Mantém as mesmas configurações da tabela, incluindo nome, configurações, permissões e visualização.
• Permite reverter uma tabela `gi` convertida para uma tabela externa.
• Redireciona leituras e gravações baseadas em caminho para permitir que o código legado funcione após a conversão.

Pré-requisitos

• Você deve usar o Databricks Runtime 17.3 LTS ou acima ou compute serverless para usar SET MANAGED, UNSET MANAGED ou TRUNCATE UNIFORM HISTORY.

• A tabela deve estar no formato Delta Lake.

• Os leitores e gravadores do Databricks para suas tabelas de origem devem usar o Databricks Runtime 15.4 LTS ou acima. Se seus leitores ou gravadores usam a versão 14.3 LTS ou anterior, consulte a opção alternativa para leitores e gravadores no Databricks Runtime 14.3 LTS ou anterior.

• Clientes externos (nãoDatabricks) devem suportar leituras em tabelas gerenciadas Unity Catalog . Consulte a seção "Acessar tabelas com clientes Delta".

  • Utilize o painel de percepções do Access para verificar se os leitores e escritores que acessam suas tabelas são usuários internos ( Databricks Runtime ) ou externos (non-Databricks).

• Se sua tabela tiver minReaderVersion=2, minWriterVersion=7 e tableFeatures={..., columnMapping}, o comando SET MANAGED falhará com um erro DELTA_TRUNCATED_TRANSACTION_LOG. Verifique se sua tabela tem estas propriedades usando DESCRIBE DETAIL. Consulte compatibilidade e protocolos de recursos do Delta Lake.

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

importante

Para evitar conflitos, cancele qualquer trabalho de comando OPTIMIZE existente (líquido clustering, compactação, ZORDER) que esteja operando na sua tabela e não programe nenhum trabalho enquanto o senhor converte as tabelas externas em tabelas gerenciáveis.

Converter de externo para ger tabela

info

Beta

A conversão de tabelas externas para tabelas usando o Catalog Explorer está em versão Beta.

Catalog Explorer

Ao converter usando o Catalog Explorer, o acesso baseado em nomes é usado automaticamente. Você pode converter uma ou mais tabelas externas em um esquema por vez.

1. Acesse a tabela ou o esquema que deseja converter no Explorador de Catálogo.

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

3. Na seção "Por que migrar para o Unity Catalog ?", gerencie as tabelas? Na caixa de diálogo, clique em Continuar .

   

4. Selecione as tabelas externas que deseja converter. Se você abriu a caixa de diálogo a partir da página de detalhes de uma tabela, sua tabela já está pré-selecionada. Utilize a barra de pesquisa para encontrar tabelas adicionais. As tabelas não podem ser selecionadas.

   

5. Clique em Criar caderno de conversão .

6. Opcionalmente, insira um nome para o caderno. Por default, o Bloco de Anotações é salvo na sua pasta principal. Clique em Procurar para salvar em um local diferente.

   

7. No Notebook, revise as melhores práticas e verifique se você atende a todos os pré-requisitos.

8. execução da célula SET Gerenciando Consultas .

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

SQL

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

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

  SQL

  ALTER TABLE catalog.schema.my_external_table SET MANAGED;

  Após a conversão, você pode habilitar leituras Iceberg na sua tabela gerencial sem problemas de compatibilidade.

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

  SQL

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

  Inclua TRUNCATE UNIFORM HISTORY para manter o desempenho e a compatibilidade ideais da tabela. TRUNCATE UNIFORM HISTORY trunca apenas UniForm Iceberg história e não remove Delta história. Este comando resulta em um breve período 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, reinicie-o. O comando retoma de onde parou.

atenção

Databricks recomenda que você evite executar vários comandos SET MANAGED simultaneamente na mesma tabela, o que pode levar a um estado inconsistente da tabela.

Após a conversão da tabela, as transmissões de leitura e gravação existentes falham. Reinicie as transmissões com as mesmas configurações para usar automaticamente o redirecionamento baseado em caminho. Verifique se seus leitores e escritores estão trabalhando com a tabela gerenciada. Consulte Comportamento de transmissão.

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

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

SQL

VACUUM my_converted_table

nota

Mesmo com a otimização preditiva ativada, os dados no seu local externo do Unity Catalog podem não ser excluídos após 14 dias. Por exemplo, isso pode ocorrer quando a tabela gerenciada é pouco utilizada ou muito pequena. Se os dados anteriores permanecerem, execute VACUUM manualmente para removê-los.

O 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

Catalog Explorer

Atualize a página. Na tab Detalhes , em Sobre esta tabela , o Tipo de tabela é exibido como gerenciar .

SQL

Execute o seguinte comando para confirmar que sua tabela externa foi convertida em uma tabela gerenciável:

SQL

DESCRIBE EXTENDED catalog_name.schema_name.table_name

A tabela Type é exibida como MANAGED.

Opção alternativa para leitores e escritores em Databricks Runtime 14.3 LTS ou abaixo

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

Você ainda pode usar SET MANAGED se tiver leitores ou escritores no Databricks Runtime 14.3 LTS ou inferior. No entanto, após a conversão para uma tabela gerenciada, a viagem do tempo para commits históricos pode ser feita somente por versão e não por timestamp. Se você reverter para uma tabela externa dentro do período de 14 dias, a viagem do tempo para commits históricos feitos antes da conversão será reativada.

Em todos os casos, a viagem no tempo com carimbos de data/hora não funciona para commits feitos na tabela gerenciada convertida entre a conversão e o rollback.

Para gravar em uma tabela após a conversão com Databricks Runtime 15.4 LTS ou abaixo, é necessário remover o recurso inCommitTimestamp:

SQL

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Redirecionamento baseado em caminho

info

Visualização

O redirecionamento baseado em caminho está em versão prévia pública. Para se inscrever, preencha este formulário.

No Databricks Runtime 18.1 e versões superiores, após converter uma tabela externa em uma tabela gerenciada do Unity Catalog, as operações de leitura e gravação 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 legado que usa caminhos de armazenamento continue funcionando sem refatoração.

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

comportamento

Para transmissão com redirecionamento baseado em caminho:

• A leitura é suportada no Databricks Runtime 18.1 e versões superiores.
• A gravação de dados é suportada no Databricks Runtime 18.2 e versões superiores.

Após a conversão, você deve reiniciar todos os trabalhos de transmissão para evitar a leitura ou gravação na localização da tabela anterior.

As operações de leitura e gravação baseadas em caminho falham e param no próximo ponto de verificação com uma mensagem de migração:

• Para leituras, a transmissão 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 escritas, os primeiros microlotes após a conversão geram 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 os erros, reinicie a transmissão com as mesmas configurações. O acesso baseado em caminho redireciona automaticamente para a tabela de gerenciamento.

Limitações

O redirecionamento baseado em caminho só possui compatibilidade retroativa para o processo de migração e não habilita novo 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 de gerenciamento Unity Catalog e como resolvê-los.

Consistência da versão do Databricks Runtime

Evite executar ou tentar novamente a conversão da mesma tabela usando versões diferentes do Databricks Runtime. Os metadados podem ser serializados de forma diferente entre as versões, o que causa uma falha VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED . Se a conversão falhar, tente sempre novamente usando 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_INTEGRITY ou 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 do arquivo

O comando SET MANAGED valida se todos os arquivos no Snapshot mais recente da tabela foram copiados para o novo local da tabela gerencia. Se algum arquivo estiver faltando, o comando falhará com um erro DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED .

Para resolver este problema:

1. Verifique os logs do driver 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 são acessíveis.
3. Tente novamente o comando ALTER TABLE ... SET MANAGED .

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

Reverter para uma tabela externa

importante

O UNSET MANAGED comando requer compute serverless ou compute com Databricks Runtime 17.3 LTS ou acima.

Após converter uma tabela externa em uma tabela gerenciada, você pode reverter a alteração em até 14 dias usando o comando UNSET MANAGED .

A reversão atualiza os metadados da tabela para apontarem de volta para a localização externa original. Todas as gravações feitas no local gerenciado após a conversão são preservadas. Commits feitos no local gerenciado entre a conversão e o rollback permitem a viagem do tempo por versão, mas não por carimbo de data/hora.

Sete dias após o rollback, Databricks exclui automaticamente os dados no local gerenciado.

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

SQL

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

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

Você também deve reiniciar seu Job de transmissão após reverter, de forma semelhante à conversão.

Verificar reversão

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

SQL

DESCRIBE EXTENDED catalog_name.schema_name.table_name

A tabela Type é exibida como EXTERNAL.

Se você estiver visualizando a tabela no Explorador de Catálogo, refresh a página. Na tab Detalhes , em Sobre esta tabela , o Tipo de tabela é exibido como EXTERNAL.

Tempo de inatividade e tempos de cópia de dados

O comando SET MANAGED 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 duas etapas:

1. Cópia inicial de dados (sem tempo de inatividade): Os dados da tabela e log de transações Delta são copiados do local externo para o local de gerenciamento. Leitores e escritores continuam trabalhando normalmente, sem impacto nas operações em andamento.
2. Mudança para local gerenciado (breve período de inatividade): Os commits feitos no local externo durante a primeira etapa são movidos para o local gerenciado e os metadados da tabela são atualizados para registrar o novo local gerenciado. Durante esta etapa, todas as gravações no local externo são bloqueadas temporariamente, resultando em inatividade do sistema de gravação. Usuários do Databricks Runtime 16.4 LTS ou superior não sofrem interrupções, mas usuários do Databricks Runtime 15.4 LTS podem sofrer interrupções.

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

Tamanho da tabela	Tamanho recomendado do clustering	Hora da cópia dos dados	Tempo de inatividade do leitor e do escritor
100 GB ou menos	SQL warehousede 32 núcleos / X-Large	Aproximadamente 6 minutos ou menos	~1-2 minutos ou menos
1 TB	SQL warehousede 64 núcleos / 2X-Large	~30 minutos	~1-2 minutos
10 TB	SQL warehousede 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.

nota

O tempo de inatividade pode variar dependendo de fatores como tamanho do arquivo, número de arquivos e número de commits.

Limitações

• Você deve reiniciar qualquer tarefa de transmissão após a conversão. Veja o comportamento de transmissão.

• A história de commits feitos após a conversão, mas antes do rollback, permite a viagem do tempo por versão, mas não por timestamp.

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

  SQL

  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 de gerenciamento default do seu metastore, catálogo ou esquema Unity Catalog estiver em uma região cloud diferente do local de armazenamento da tabela externa, você poderá incorrer em custos adicionais de transferência de dados entre regiões por parte do seu provedor cloud .

  Para verificar a localização do seu esquema, catálogo e metastore:

  SQL

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