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. Anche se è possibile usare (CTAS) per la conversione, Databricks consiglia di usare CREATE TABLE AS SELECTSET MANAGED per 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 verificare se la tabella include letture Apache Iceberg (UniForm) abilitate, vedere Verificare che le letture di Iceberg (UniForm) siano 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 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, è 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. Ciò garantisce che l'attività eviti la lettura o la scrittura nella vecchia posizione. Per riavviare, arrestare il processo corrente e avviare un nuovo processo con la stessa configurazione.
  • Verificare che i lettori e gli scrittori funzionino con la tabella gestita. Tutti i lettori e i writer devono usare l'accesso in base al nome per lavorare automaticamente con la tabella gestita appena convertita. L'accesso basato sul percorso non è supportato e può causare errori o danneggiamenti dei dati.

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

Eseguire il rollback a una tabella esterna

Important

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

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

Quando si esegue il rollback di una tabella convertita, 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, è 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 SET MANAGED comando riduce al minimo o elimina i tempi di inattività rispetto agli approcci alternativi, ad esempio l'uso di DEEP CLONE. Il processo di conversione usa un approccio in due passaggi per ridurre al minimo i tempi di inattività:

  1. Copia iniziale dei dati (senza tempi di inattività): durante questo primo passaggio, i dati della tabella e il log delle transazioni Delta vengono copiati dalla posizione esterna alla posizione gestita. I lettori e gli scrittori continuano a funzionare normalmente con la posizione esterna, senza alcun impatto sulle operazioni in corso.
  2. Passare alla posizione gestita (breve tempo di inattività): durante questo secondo passaggio, i commit eseguiti nella posizione esterna durante il primo passaggio vengono spostati nella posizione gestita. Inoltre, i metadati della tabella vengono aggiornati per registrare la nuova posizione della tabella gestita. Durante questo passaggio, tutte le scritture nelle posizioni esterne vengono bloccate temporaneamente (non accodate o ritentate), causando tempi di inattività del writer. I lettori su Databricks Runtime 16.1 o versione successiva non incorrono in tempi di inattività, ma i lettori su Databricks Runtime 15.4 potrebbero subire dei tempi 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
1TB 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