Convertire una tabella esterna in una tabella gestita del Unity Catalog

Questa pagina descrive come convertire una tabella esterna in una tabella gestita di Unity Catalog in Azure Databricks usando il ALTER TABLE ... SET MANAGED comando o Esplora cataloghi.

SET MANAGED Panoramica

Usare SET MANAGED per convertire una tabella esterna in una tabella gestita del catalogo Unity. Sebbene sia anche possibile usare CREATE TABLE AS SELECT (CTAS) per la conversione, Databricks consiglia SET MANAGED di ottenere i vantaggi seguenti:

• Riduce al minimo i tempi di inattività del lettore e del writer.
• Gestisce le scritture simultanee durante la conversione.
• Mantiene la cronologia delle tabelle.
• Mantiene le stesse configurazioni di tabella, tra cui nome, impostazioni, autorizzazioni e viste.
• Supporta il ripristino di una tabella gestita convertita in una tabella esterna.

Prerequisites

• Tutti i lettori e i writer nelle tabelle esterne devono usare l'accesso basato sul nome. Per esempio:

  SELECT * FROM catalog_name.schema_name.table_name;
  

  L'accesso basato sul percorso non è supportato e potrebbe non riuscire dopo la conversione della tabella.

• È necessario usare Databricks Runtime 17.0 o versione successiva oppure il calcolo serverless per utilizzare SET MANAGED o UNSET MANAGED.

• Per convertire le tabelle del catalogo Unity con le letture Iceberg (UniForm) già abilitate, è necessario usare Databricks Runtime 17.2 o versione successiva oppure il calcolo serverless per usare TRUNCATE UNIFORM HISTORY.

• I lettori e i writer di Azure Databricks devono usare Databricks Runtime 15.4 LTS o versione successiva. Se i lettori o i writer usano 14.3 LTS o versioni precedenti, vedere Opzione alternativa per lettori e writer in Databricks Runtime 14.3 LTS o versioni precedenti.

• Il SET MANAGED comando ha esito negativo e viene visualizzato un DELTA_TRUNCATED_TRANSACTION_LOG errore se la tabella contiene minReaderVersion=2, minWriterVersion=7e tableFeatures={..., columnMapping}. È possibile verificare se la tabella ha queste proprietà usando DESCRIBE DETAIL.

• I client esterni (non Databricks) devono supportare le letture nelle tabelle gestite di Unity Catalog. Vedere Leggere le tabelle con i client Delta.

  • Usare il dashboard di Access Insights per verificare se i lettori e i writer che accedono alle tabelle sono Databricks Runtime o esterni non Databricks.

Eseguire la conversione da una tabella esterna a una tabella gestita

Esploratore di cataloghi

Quando si esegue la conversione con Esplora cataloghi, l'accesso basato sul nome viene usato automaticamente. È possibile convertire una o più tabelle esterne in uno schema alla volta.

1. Passare alla tabella o allo schema da convertire in Esplora cataloghi.

2. In Informazioni su questa tabella (pagina dei dettagli tabella) o Informazioni su questo schema (pagina dei dettagli dello schema), fare clic su Esplora ottimizzazioni.

3. Nella finestra di dialogo Perché eseguire la migrazione a tabelle gestite di Unity Catalog fare clic su Continua.

   

4. Selezionare le tabelle esterne da convertire. Se è stata aperta la finestra di dialogo da una pagina dei dettagli della tabella, la tabella è pre-selezionata. Usare la barra di ricerca per trovare tabelle aggiuntive. Le tabelle gestite non sono selezionabili.

   

5. Fai clic su Crea notebook di conversione.

6. Facoltativamente, immettere un nome per il notebook. Per impostazione predefinita, il notebook viene salvato nella home folder. Fare clic su Sfoglia per salvarlo in un percorso diverso.

   

7. Nel notebook esaminare le procedure consigliate e verificare di soddisfare tutti i prerequisiti.

8. Eseguire la cella Query Gestite.

Dopo l'esecuzione della cella, il tipo di tabella viene visualizzato come MANAGED anziché EXTERNAL in Catalog Explorer. Aggiornare la pagina se lo stato non viene aggiornato immediatamente.

SQL

A seconda che la tabella esterna disponga di letture Apache Iceberg (UniForm) abilitate, eseguire uno dei comandi seguenti. Vedere Verificare che le letture di Iceberg (UniForm) siano abilitate per verificare se la tabella include letture Apache Iceberg (UniForm) abilitate.

• Per le tabelle esterne di Unity Catalog senza le letture di Apache Iceberg (UniForm) abilitate:

  ALTER TABLE catalog.schema.my_external_table SET MANAGED;
  

  Dopo la conversione, è possibile abilitare le letture Iceberg nella tabella gestita senza problemi di compatibilità.

• Per le tabelle esterne del Catalogo Unity con le letture di Apache Iceberg (UniForm) già abilitate:

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

  Includere TRUNCATE UNIFORM HISTORY per mantenere prestazioni e compatibilità ottimali delle tabelle. TRUNCATE UNIFORM HISTORY tronca solo la cronologia di UniForm Iceberg e non rimuove la cronologia delta. Questo comando comporta una breve interruzione delle operazioni di lettura e scrittura per Iceberg dopo il troncamento.

Se il comando viene interrotto durante la copia dei dati, riavviarlo e continuare da dove è stato interrotto.

Dopo che la tabella è stata convertita, è necessario:

• Riavvia tutte le attività di streaming (lettura o scrittura) usando la tabella esterna per evitare la lettura o la scrittura nel percorso precedente. Arrestare il processo corrente e avviare un nuovo processo con la stessa configurazione.
• Verifica che i lettori e gli scrittori operino con la tabella gestita.

L'ottimizzazione predittiva viene abilitata automaticamente dopo la conversione, a meno che non sia stata disabilitata manualmente. Vedere Verificare se l'ottimizzazione predittiva è abilitata.

Con l'ottimizzazione predittiva abilitata, Azure Databricks elimina automaticamente i dati nella posizione esterna di Unity Catalog dopo 14 giorni. Se l'ottimizzazione predittiva è disabilitata, eseguire VACUUM (richiede Databricks Runtime 17.0 o versione successiva o serverless) nella tabella gestita appena convertita dopo 14 giorni.

VACUUM my_converted_table

Verificare la conversione

Esploratore di cataloghi

Aggiornare la pagina. Nella scheda Dettagli , in Informazioni su questa tabella, la tabella Tipo viene visualizzata come gestita.

SQL

Eseguire il comando seguente per verificare che la tabella esterna sia stata convertita in una tabella gestita:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

La tabella Type viene visualizzata come MANAGED.

Opzione alternativa per lettori e scrittori su Databricks Runtime 14.3 LTS o versioni precedenti

Databricks consiglia di aggiornare tutti i lettori e i writer a Databricks Runtime 15.4 LTS o versione successiva per sfruttare i vantaggi di SET MANAGED, inclusa la possibilità di conservare la cronologia delle tabelle.

È comunque possibile usare SET MANAGED se si hanno lettori o writer in Databricks Runtime 14.3 o versioni precedenti. Tuttavia, dopo la conversione in una tabella gestita, non è possibile viaggiare nel tempo verso revisioni cronologiche utilizzando il timestamp, solo tramite versione. Se si esegue il rollback a una tabella esterna nell'intervallo di 14 giorni, il recupero cronologico dei commit storici effettuati prima che la conversione venga riattivata è nuovamente abilitato.

In tutti i casi, il rollback a una tabella esterna del catalogo Unity in base al timestamp non funziona per i commit eseguiti nella tabella gestita di Unity Catalog convertita tra conversione e rollback.

La scrittura in una tabella dopo la conversione con Databricks Runtime 15.4 LTS o versioni precedenti richiede l'eliminazione della inCommitTimestamp funzionalità:

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Risoluzione degli errori di conversione

Questa sezione descrive i problemi comuni durante la conversione di tabelle esterne in tabelle gestite del catalogo Unity e come risolverle.

Coerenza della versione di Databricks Runtime

Evitare di eseguire o ripetere la conversione della stessa tabella usando versioni di Databricks Runtime diverse. I metadati possono essere serializzati in modo diverso tra le versioni, causando un VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED errore. Se la conversione non riesce, riprovare sempre usando la stessa versione di Databricks Runtime.

Arresto del cluster durante la conversione

Se il cluster si spegne durante la conversione, il comando potrebbe non riuscire con DELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERROR. Ripetere il comando per riprendere la conversione.

Tabella esterna danneggiata

Se la tabella esterna è già danneggiata (ad esempio, lo stato della tabella non valido), la conversione potrebbe non riuscire con errori come DELTA_TRUNCATED_TRANSACTION_LOG, DELTA_TXN_LOG_FAILED_INTEGRITYo DELTA_STATE_RECOVER_ERRORS. Prima di tentare la conversione, verificare che sia possibile eseguire operazioni di base nella tabella esterna, ad esempio DESCRIBE DETAIL.

Errore di convalida dei file

Il SET MANAGED comando verifica che tutti i file nello snapshot più recente della tabella vengano copiati nel nuovo percorso della tabella gestita. Se mancano dei file, il comando fallisce con un errore DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED.

Per risolvere il problema:

1. Controllare i log del driver Spark per identificare i file di cui non è possibile eseguire la migrazione.
2. Verificare che questi file esistano nel percorso della tabella esterna di origine e siano accessibili.
3. Ripetere il ALTER TABLE ... SET MANAGED comando.

Se il problema persiste, contattare il supporto di Databricks.

Eseguire il rollback a una tabella esterna

Dopo aver convertito una tabella esterna in una tabella gestita, è possibile eseguire il rollback entro 14 giorni.

Quando si esegue il rollback, i metadati della tabella vengono aggiornati per tornare alla posizione esterna originale. Tutte le scritture effettuate nella posizione gestita dopo la conversione vengono mantenute. I commit eseguiti nella posizione gestita tra la conversione e il rollback rimangono accessibili nel tempo in base alla versione, ma non attraverso il timestamp.

Sette giorni dopo il rollback, Azure Databricks elimina automaticamente i dati nella posizione gestita.

Per ripristinare una tabella esterna, eseguire il comando seguente:

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

Se il comando di rollback viene interrotto, eseguirlo di nuovo per riprovare.

È anche necessario riavviare i processi di streaming dopo il rollback, in modo analogo alla conversione.

Verificare il rollback

Eseguire il comando seguente per confermare che sia stato eseguito il rollback della conversione:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

La tabella Type viene visualizzata come EXTERNAL.

Se si visualizza la tabella in Esplora cataloghi, aggiornare la pagina. Nella scheda Dettagli , in Informazioni su questa tabella, la tabella Tipo visualizza come EXTERNAL.

Tempi di inattività e copia dei dati

Il SET MANAGED comando riduce al minimo o elimina i tempi di inattività rispetto agli approcci alternativi, ad esempio DEEP CLONE. Il processo di conversione usa un approccio in due passaggi:

1. Copia dati iniziale (senza interruzioni operative): I dati della tabella e il log delle transazioni Delta vengono copiati dal percorso esterno alla posizione gestita. I lettori e gli scrittori continuano a operare normalmente senza alcun impatto sulle operazioni in corso.
2. Passare alla posizione gestita (breve tempo di inattività): I commit eseguiti nel percorso esterno durante il primo passaggio vengono spostati nella posizione gestita e i metadati della tabella vengono aggiornati per registrare la nuova posizione gestita. Durante questo passaggio, tutte le scritture nella posizione esterna vengono temporaneamente interrotte, causando tempi di inattività dello scrittore. I lettori in Databricks Runtime 16.1 o versione successiva non riscontrano tempi di inattività; i lettori in Databricks Runtime 15.4 potrebbero riscontrare tempi di inattività.

Tempo di inattività stimato:

Le stime presuppongono una velocità effettiva di 0,5-2 GB/core CPU/minuto.

Limitazioni note

• Client di streaming: È necessario riavviare tutti i processi di streaming dopo la conversione.

• Vincoli di cronologia delle tabelle dopo il rollback: La cronologia delle tabelle per i commit effettuati dopo la conversione ma prima del rollback è accessibile attraverso le versioni, ma non attraverso il timestamp.

• Limitazioni di Delta Sharing: Il SET MANAGED comando non è completamente compatibile con Delta Sharing. Open Delta Sharing funziona come previsto, ma la condivisione da Databricks a Databricks non aggiorna automaticamente la posizione gestita della tabella del destinatario. Il destinatario continua a leggere dalla posizione precedente fino a quando la tabella non viene ricondivisa. Per ricondividere la tabella:

  ALTER SHARE <share_name> REMOVE TABLE <table_name>;
  ALTER SHARE <share_name> ADD TABLE <table_name> AS <table_share_name> WITH HISTORY;
  

• Più aree cloud: Se la posizione gestita predefinita del metastore, del catalogo o dello schema di Unity si trova in un'area cloud diversa dalla posizione di archiviazione della tabella esterna, è possibile che vengano addebitati costi aggiuntivi per il trasferimento dei dati tra aree. Il provider di servizi cloud impone questi addebiti al di fuori del controllo di Databricks.

  Per verificare i percorsi dello schema, del catalogo e del metastore:

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