Convertire una tabella esterna in una tabella gestita del Unity Catalog

Questa pagina descrive come convertire una tabella esterna in una tabella gestita del catalogo Unity in Azure Databricks usando il comando ALTER TABLE ... SET MANAGED 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.
  • Reindirizza letture e scritture basate sul percorso per consentire il funzionamento del codice legacy dopo la conversione.

Prerequisites

  • È 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 gli scrittori 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. Consulta Accedere alle 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.

Dopo la conversione, le letture e le scritture basate su percorso vengono reindirizzate automaticamente alla nuova posizione gestita con un sovraccarico delle prestazioni ridotto. Databricks consiglia di eseguire la migrazione di tutti gli accessi basati sul percorso all'accesso basato sui nomi per evitare il sovraccarico delle prestazioni. Vedere Reindirizzamento basato su percorso.

Important

Per evitare conflitti, annullare eventuali processi di comando esistenti OPTIMIZE (clustering liquido, compattazione, ZORDER) che operano nella tabella e non pianificare processi durante la conversione delle tabelle esterne in tabelle gestite.

Eseguire la conversione da una tabella esterna a una tabella gestita

Important

La conversione esterna in tabelle gestite tramite Esplora cataloghi è in versione beta.

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.

    Finestra di dialogo Perché eseguire la migrazione a tabelle gestite del catalogo Unity con il pulsante 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.

    Schermata di selezione tabella che mostra una tabella esterna pre-selezionata e una tabella gestita non disponibile

  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.

    La finestra di dialogo Crea taccuino di conversione che mostra il campo Nome e l'opzione Sfoglia

  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.

Warning

Databricks consiglia di evitare di eseguire più SET MANAGED comandi contemporaneamente nella stessa tabella, che può causare uno stato di tabella incoerente.

Dopo la conversione delle tabelle, i flussi di lettura e scrittura hanno esito negativo. Riavviare i flussi con le stesse configurazioni per usare automaticamente il reindirizzamento basato sul percorso. Verifica che i lettori e gli scrittori operino con la tabella gestita. Vedere Comportamento di streaming.

L'ottimizzazione predittiva viene abilitata automaticamente dopo la conversione, a meno che non sia stata disattivata 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 è disattivata, eseguire VACUUM (richiede Databricks Runtime 17.0 o versione successiva o servizi di calcolo serverless) sulla tabella gestita appena convertita, dopo che sono trascorsi 14 giorni dalla conversione.

VACUUM my_converted_table

Note

In alcuni casi, i dati nella posizione esterna di Unity Catalog potrebbero non essere eliminati dopo 14 giorni, anche con l'ottimizzazione predittiva abilitata, ad esempio se la tabella gestita non viene usata di frequente o è molto piccola. In questi casi, eseguire VACUUM manualmente dopo 14 giorni per rimuovere i dati precedenti.

Azure Databricks elimina solo i dati nella posizione esterna. Il log delle transazioni Delta e il riferimento alla tabella in Unity Catalog vengono mantenuti.

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;

Reindirizzamento basato su percorso

Important

Il reindirizzamento basato sul percorso è disponibile in anteprima pubblica. Per eseguire la registrazione, completare il modulo.

In Databricks Runtime 18.1 e versioni successive, dopo aver convertito una tabella esterna in una tabella gestita di Unity Catalog, le operazioni di lettura e scrittura basate sul percorso esterno precedente vengono reindirizzato automaticamente alla nuova posizione gestita. Il reindirizzamento basato su percorso riduce il tempo e il lavoro necessario per eseguire la migrazione alle tabelle gestite perché consente al codice legacy che accede alle tabelle in base al percorso di archiviazione di continuare a funzionare senza richiedere il refactoring.

Per i casi d'uso a bassa latenza, Azure Databricks consiglia di eseguire la migrazione dell'accesso basato sul percorso all'accesso basato sui nomi. Il reindirizzamento basato su percorso aggiunge diverse centinaia di millisecondi di overhead per ogni lettura o scrittura basata su percorso e richiede che i vecchi log Delta rimangano attivi nella posizione esterna di Unity Catalog. Le operazioni di lettura e scrittura basate su nomi non comportano un sovraccarico aggiuntivo per le prestazioni.

Comportamento di streaming

Per lo streaming con reindirizzamento basato sul percorso:

  • Le letture sono supportate in Databricks Runtime 18.1 e versioni successive.
  • Le scritture sono supportate in Databricks Runtime 18.2 e versioni successive.

Dopo la conversione, è necessario riavviare tutti i processi di streaming per evitare di leggere o scrivere nella posizione precedente della tabella.

Le operazioni di lettura e scrittura basate sul percorso falliscono e si arrestano al checkpoint successivo con un messaggio di migrazione.

  • Per le letture, il flusso genera un errore: 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.
  • Per le scritture, il primo micro batch dopo la conversione genera un errore: Operation not allowed: STREAMING WRITE cannot be performed on a table with redirect feature. The no redirect rules are not satisfied [].

Per risolvere gli errori, riavviare i flussi con le stesse configurazioni. L'accesso basato sul percorso reindirizza automaticamente alla tabella gestita.

Limitazioni

  • Il reindirizzamento basato su percorso offre compatibilità con le versioni precedenti solo per il processo di migrazione e non abilita l'accesso basato sul percorso alle tabelle gestite di Unity Catalog.

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

Important

Il UNSET MANAGED comando richiede Databricks Runtime 17.0 o versione successiva o calcolo serverless.

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:

Dimensioni della tabella Dimensioni del cluster consigliate Tempo per la copia dei dati Tempo di inattività del lettore e dello scrittore
100 GB o meno 32 core/ X-Large SQL Warehouse ~6 min o meno ~1-2 min o minore
1TB 64-core / 2X-Large SQL Warehouse ~30 min ~1-2 min
10 TB Magazzino SQL da 256 core / 4X-Large ~1,5 ore ~1-5 min

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

Note

Il tempo di inattività può variare in base a fattori quali le dimensioni del file, il numero di file e il numero di commit.

Limitazioni

  • È necessario riavviare tutti i processi di streaming dopo la conversione. Vedere Comportamento di streaming.

  • La cronologia delle tabelle per i commit effettuati dopo la conversione, ma prima del rollback, consente il viaggio nel tempo per versione ma non per timestamp.

  • Delta Sharing non è completamente compatibile con il SET MANAGED comando. 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;

  • 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 dal provider di servizi cloud.

    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;
  • Last updated on