Condividi tramite

Convertire una tabella esterna in una tabella del catalogo Unity gestita

Questa pagina descrive l'uso del ALTER TABLE ... SET MANAGED comando per convertire una tabella esterna in una tabella gestita di Unity Catalog in Azure Databricks.

Panoramica di SET MANAGED

Usare la SET MANAGED funzionalità per convertire una tabella esterna in una tabella gestita di Unity Catalog in Azure Databricks. SET MANAGED offre i vantaggi seguenti:

  • Riduzione al minimo dei tempi di inattività del lettore e del writer.
  • Gestione delle scritture simultanee durante la conversione.
  • Conservazione della cronologia delle tabelle.
  • Mantenere le stesse configurazioni di tabella, inclusi lo stesso nome, le impostazioni, le autorizzazioni e le visualizzazioni.
  • Possibilità di eseguire il rollback di una tabella gestita convertita in una tabella esterna.

Prerequisites

Per usare la funzionalità di conversione delle tabelle, è necessario soddisfare i prerequisiti seguenti:

  • 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 o serverless per usare SET MANAGED o UNSET MANAGED.

  • Per convertire le tabelle di Unity Catalog con le letture Iceberg (UniForm) già abilitate, è necessario utilizzare Databricks Runtime 17.2 o versioni successive, oppure il computing serverless, per sfruttare 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.

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

Il SET MANAGED comando è disponibile in Databricks Runtime 17.0 o versioni successive e nel calcolo serverless.

Il TRUNCATE UNIFORM HISTORY comando è disponibile a partire da Databricks Runtime 17.2 o versione successiva e nell'elaborazione serverless.

Eseguire uno dei comandi seguenti per convertire la tabella esterna del catalogo Unity in una tabella gestita del catalogo Unity.

  • 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 Iceberg (UniForm) già abilitate:

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

    In questo caso, 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, è possibile riavviarlo e continuerà da dove è stato interrotto.

Warning

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

Dopo che la tabella è stata convertita, è necessario:

  • Riavviare tutti i processi di streaming (lettura o scrittura) usando la tabella esterna.
  • Assicurarsi che i lettori e gli scrittori lavorino con la tabella gestita.

L'ottimizzazione predittiva viene abilitata automaticamente, tranne se è stata disabilitata manualmente. Vedere Controllare 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, è possibile eseguire VACUUM (richiede Databricks Runtime 17.0 o versione successiva o di calcolo serverless) nella tabella gestita appena convertita dopo 14 giorni.

VACUUM my_converted_table

Note

In alcuni casi, i dati nella posizione esterna del catalogo Unity potrebbero non essere eliminati dopo 14 giorni, anche con l'ottimizzazione predittiva abilitata. Ad esempio, se la tabella gestita di Unity Catalog non viene usata di frequente o è molto piccola, l'eliminazione automatica potrebbe non verificarsi. In questi casi, dopo 14 giorni, eseguire VACUUM manualmente (richiede Databricks Runtime 17.0 o versione successiva o di calcolo serverless) nella tabella gestita appena convertita 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.

Controllare la conversione

È possibile verificare che la tabella esterna sia stata convertita in una tabella gestita:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Controllare l'output di questo comando per verificare che la tabella sia stata convertita. La tabella Type deve essere visualizzata come MANAGED.

Se stai visualizzando le informazioni sulla tabella in Catalog Explorer, aggiorna la pagina. Nella scheda Dettagli , in Informazioni su questa tabella, la tabella Tipo deve essere 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 versioni successive per sfruttare i vantaggi del comando, inclusa la possibilità di conservare la SET MANAGED cronologia delle tabelle.

È comunque possibile usare il SET MANAGED comando se si hanno lettori o writer con Databricks Runtime 14.3 o versione successiva. Tuttavia, dopo la conversione in una tabella gestita, non è possibile viaggiare nel tempo ai commit storici in base al timestamp. È possibile farlo solo in base alla versione. Se si esegue il rollback a una tabella esterna nell'intervallo di 14 giorni, i commit cronologici eseguiti prima della conversione verranno riabilitati.

In tutti i casi (indipendentemente dalla versione DBR), il rollback a UC external by timestamp non funziona per i commit eseguiti nella tabella gestita uc convertita, tra quando è stata completata la conversione e prima di provare a eseguire il 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 DBR

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, assicurarsi di poter eseguire operazioni di base nella tabella esterna, ad esempio DESCRIBE DETAIL.

Eseguire il rollback a una tabella esterna

Important

Il comando UNSET MANAGED è disponibile in Databricks Runtime 17.0 o versioni successive e nell'elaborazione serverless.

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

Se si esegue il rollback, i commit effettuati nella posizione esterna tra la conversione e il rollback possono essere ripristinati in base alla versione, ma non in base al timestamp. Sette giorni dopo il rollback, i dati nella posizione gestita verranno eliminati.

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, è possibile eseguirlo di nuovo per riprovare, simile al SET comando MANAGED.

Controllare il rollback

È possibile verificare che il rollback della conversione sia stato eseguito:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Verifica l'output di questo comando per confermare che la tabella sia stata ripristinata. La tabella Type deve essere visualizzata come EXTERNAL.

Se stai visualizzando le informazioni sulla tabella in Catalog Explorer, aggiorna la pagina. Nella scheda Dettagli , in Informazioni su questa tabella, la tabella Tipo deve essere visualizzata come EXTERNAL.

È inoltre necessario riavviare i processi di streaming dopo il rollback a una tabella esterna, come avviene durante la conversione.

Tempi di inattività e copia dei dati

Il tempo di inattività può verificarsi quando i lettori o gli scrittori accedono alla tabella durante la conversione. Tuttavia, rispetto al comando "DEEP CLONE", il SET MANAGED comando riduce al minimo o elimina i tempi di inattività per lettori e writer. I lettori in Databricks Runtime 16.1 o versione successiva non riscontrano tempi di inattività. I lettori e gli scrittori non sono influenzati durante il primo passaggio, quando i dati della tabella e il log differenziale vengono copiati.

Durante il secondo passaggio, le scritture nella posizione esterna del catalogo Unity vengono bloccate e i commit eseguiti nella posizione esterna durante la prima copia dei dati verranno spostati. Questo secondo passaggio di copia dei dati comporta tempi di inattività per writer e lettori in Databricks Runtime 15.4 LTS o versioni precedenti.

Successivamente, i lettori e i writer vengono spostati nella posizione gestita di Unity Catalog e la nuova posizione della tabella gestita viene registrata in Unity Catalog. I lettori con Databricks Runtime 16.1 o versione successiva sperimenteranno un'esperienza equivalente a nessun tempo di inattività.

Il 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/DBSQL di piccole dimensioni ~6min o meno ~1-2 minuti o meno
1 TB 64-core / DBSQL medio ~30 min ~1-2min
10 TB 256 core/ DBSQL x-large ~1,5 ore ~1-5min

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

Note

Il tempo di inattività può variare. Le prestazioni della conversione dipendono da fattori quali le dimensioni del file, il numero di file e il numero di commit.

Limitazioni note

La conversione esterna in tabelle gestite presenta le limitazioni seguenti:

  • Client di streaming: è necessario riavviare qualsiasi lavoro di streaming dopo la conversione.

  • Vincoli di cronologia delle tabelle dopo il rollback: Per i lettori/scrittori in Databricks Runtime 15.4 LTS o versione successiva, la cronologia delle tabelle per i commit effettuati dopo la conversione, ma prima del rollback, sarà accessibile in base alla versione, ma non in base al timestamp.

  • Limitazioni della condivisione Delta: il SET MANAGED comando non è completamente compatibile con la condivisione Delta. Anche se la condivisione delta aperta funziona come previsto, la condivisione da Databricks a Databricks non aggiorna automaticamente la posizione gestita della tabella dei destinatari. 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 da convertire, è possibile sostenere 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 controllare i percorsi dello schema, del catalogo e del metastore, è possibile usare i comandi seguenti:

    DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;

DESC CATALOG EXTENDED <catalog_name>;

SELECT * FROM system.information_schema.metastores;
  • Last updated on