Converter uma tabela Delta externa em uma tabela Unity Catalog .

Esta página descreve como converter uma tabela externa em uma tabela de gerenciamento Unity Catalog no Databricks usando o comando ALTER TABLE ... SET MANAGED ou o Explorador de Catálogo.

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 Databricks Runtime 17.0 ou superior ou compute sem servidor para usar SET MANAGED ou UNSET MANAGED.
• A tabela deve estar no formato Delta.
• Para converter tabelas Unity Catalog com leituras Iceberg (UniForm) já habilitadas, você deve usar Databricks Runtime 17.2 ou superior ou compute sem servidor para usar TRUNCATE UNIFORM HISTORY.
• Databricks Os leitores e escritores devem usar o site Databricks Runtime 15.4 LTS ou acima. Se seus leitores ou redatores usarem a versão 14.3 LTS ou abaixo, consulte Opção alternativa para leitores e redatores em Databricks Runtime 14.3 LTS ou abaixo.
• O comando SET MANAGED falha com um erro DELTA_TRUNCATED_TRANSACTION_LOG se sua tabela tiver minReaderVersion=2, minWriterVersion=7 e tableFeatures={..., columnMapping}. Você pode verificar se sua tabela possui essas propriedades usando DESCRIBE DETAIL.
• 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).

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 a sua tabela externa tiver as leituras Apache Iceberg (UniForm) habilitadas, execute um dos seguintes comandos. Consulte a seção "Verificar se as leituras do Iceberg (UniForm) estão habilitadas" para verificar se sua tabela possui as leituras do Apache Iceberg (UniForm) habilitadas.

• 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 e ele continuará 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 falham. Reinicie as transmissões com as mesmas configurações para usar automaticamente o redirecionamento baseado em caminho. Verifique se seus leitores e escritores trabalham com a tabela gerencia. Veja o 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 ativada, Databricks exclui automaticamente os dados do seu local externo Unity Catalog após 14 dias. Se a otimização preditiva estiver desativada, a execução VACUUM (requer Databricks Runtime 17.0 ou superior ou compute sem servidor) na tabela gerencia recém-convertida após 14 dias.

SQL

VACUUM my_converted_table

nota

Em alguns casos, os dados no seu local externo Unity Catalog podem não ser excluídos após 14 dias, mesmo com a otimização preditiva ativada — por exemplo, se a sua tabela de gerenciamento não for usada com frequência ou for muito pequena. Nestes casos, execute VACUUM manualmente após 14 dias para remover os dados anteriores.

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

Databricks recomenda atualizar todos os leitores e gravadores para Databricks Runtime 15.4 LTS ou superior para aproveitar SET MANAGED, incluindo a capacidade de reter o histórico da tabela.

Você ainda pode usar SET MANAGED se tiver leitores ou escritores no Databricks Runtime 14.3 ou inferior. No entanto, após a conversão para uma tabela de gerenciamento, você não pode usar o tempo para fazer commits históricos por timestamp — apenas por versão. Se você reverter para uma tabela externa dentro do período de 14 dias, a opção "viagem do tempo para commit histórico feito antes da conversão" será reativada.

Em todos os casos, reverter para uma tabela externa Unity Catalog por timestamp não funciona para qualquer commit feito na sua tabela gerencia Unity Catalog convertida entre a conversão e a reversão.

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 de gerenciamento 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 de gerenciamento. O redirecionamento baseado em caminho reduz o tempo e o esforço necessários para migrar para tabelas gerenciadas, pois permite que o código legado que acessa tabelas por caminho de armazenamento continue funcionando sem a necessidade de 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 oferece compatibilidade com versões anteriores apenas para o processo de migração e não permite novo acesso baseado em caminho às tabelas de gerenciamento 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 comando UNSET MANAGED requer Databricks Runtime 17.0 ou superior ou compute sem servidor.

Depois de converter uma tabela externa em uma tabela gerenciar, o senhor pode reverter dentro de 14 dias.

Ao reverter a alteração, os metadados da tabela são atualizados para apontar novamente para o local externo original. Todas as gravações feitas no local de gerenciamento após a conversão são preservadas. As alterações feitas no local de gerenciamento entre a conversão e o rollback permanecem transitáveis no 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 o local de gerenciamento (breve período de inatividade): os commits feitos no local externo durante a primeira etapa são movidos para o local de gerenciamento e os metadados da tabela são atualizados para registrar o novo local de gerenciamento. Durante esse período, todas as gravações no local externo são bloqueadas temporariamente, resultando em inatividade do gravador. Usuários do Databricks Runtime 16.1 ou superior não experimentam interrupções; usuários do Databricks Runtime 15.4 podem experimentar interrupções.

Tempo estimado de inatividade:

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 tabela de histórico para commits feitos após a conversão, mas antes do rollback, permite a viagem do tempo por versão, mas não por timestamp.

• Delta Sharing não é totalmente compatível com o comando SET MANAGED . O Open Delta Sharing funciona como esperado, mas o compartilhamento Databricks-to-Databricks não atualiza automaticamente a localização de gerenciamento da tabela destinatária. O destinatário continua a ler a partir da localização antiga até que a tabela seja compartilhada novamente. Para compartilhar a mesa 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;