Converter uma tabela externa em uma tabela gerenciar 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.

Pré-requisitos

• Todos os leitores e gravadores das tabelas externas devem usar o acesso baseado em nomes. Por exemplo:

  SQL

  SELECT * FROM catalog_name.schema_name.table_name;

  O acesso baseado em caminho não é suportado e pode resultar em corrupção ou perda de dados, dependendo da versão do seu Databricks Runtime ou cliente OSS.

• Você deve usar Databricks Runtime 17.0 ou superior ou compute sem servidor para usar SET MANAGED ou UNSET MANAGED.

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

• Os clientes externos (nãoDatabricks) devem suportar leituras em tabelas gerenciais Unity Catalog. Consulte Ler 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).

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, você deve:

• Reinicie qualquer tarefa de transmissão (leitura ou gravação) que utilize a tabela externa para evitar a leitura ou gravação no local anterior. Pare o trabalho atual e inicie um novo trabalho com a mesma configuração.
• Verifique se seus leitores e escritores trabalham com a tabela gerencia.

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;

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 conhecidas

• clientes de transmissão: Você deve reiniciar qualquer Job de transmissão após a conversão.

• Restrições do histórico da tabela após o rollback: O histórico da tabela para commits feitos após a conversão, mas antes do rollback, pode ser acessado no tempo por versão, mas não por timestamp.

• LimitaçõesDelta Sharing : O comando SET MANAGED não é totalmente compatível com Delta Sharing. 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;

• Regiões cloud múltiplas: 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. O provedor cloud impõe essas taxas fora do controle Databricks .

  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;