SYNC
Si applica a: Databricks SQL Databricks Runtime Unity Catalog
Usare il comando SYNC
per aggiornare i tables esterni nel Metastore di Hive a tables esterni in Unity Catalog. È anche possibile usare SYNC
per aggiornare i tables gestiti da Hive, archiviate all'esterno dell'archiviazione dell'area di lavoro di Databricks (talvolta denominata radice DBFS), a tables esterne in Unity Catalog. Non è possibile usarlo per aggiornare le tables gestite da Hive archiviate nel sistema di archiviazione dell'area di lavoro. Per aggiornare quei tables, usare CREATE TABLE CLONE.
È possibile usare SYNC
per creare nuovi tables in Unity Catalog da tables metastore Hive esistenti, nonché per updateCatalogtables Unity quando vengono modificati i tables di origine in Metastore Hive.
Il comando SYNC
può essere eseguito a livello di schema usando la sintassi SYNC SCHEMA
o per un singolo table usando la sintassi SYNC TABLE
.
Il comando esegue un'operazione di scrittura (ALTER TABLE
) su ciascuna origine table che aggiorna per aggiungere alcune ulteriori proprietà table alla propria contabilità.
In caso di Delta tables, il cluster o SQL Warehouse che esegue il comando deve avere accesso in scrittura al percorso table per poter eseguire l'operazione di scrittura.
In Databricks Runtime 12.2 LTS o versione successiva, questo comportamento può essere disattivato impostando la configurazione spark.databricks.sync.command.disableSourceTableWrites
di Spark su true
prima di eseguire il SYNC
comando. Quando set passa a true
, SYNC
non aggiunge nuove proprietà di table e pertanto potrebbe non rilevare se l'table è stato precedentemente aggiornato a Unity Catalog.
In tal caso, si basa esclusivamente sul nome table per determinare se il table è stato precedentemente aggiornato a Unity Catalog.
Se il table di origine è stato rinominato dall'ultimo comando SYNC, l'utente deve rinominare manualmente il table di destinazione prima di eseguire nuovamente il comando SYNC quando la configurazione è true
.
Importante
Quando viene eseguito un comando SYNC
, l'operazione di SET TBLPROPERTIES
aggiunge una proprietà table che indica la destinazione Unity Catalog riferimento esterno table. Questa operazione calcola un nuovo snapshot Delta e aggiunge una nuova voce al log Delta table, scrivendo nel percorso table di destinazione nell'archiviazione cloud.
Sintassi
SYNC { SCHEMA target_schema [AS EXTERNAL] FROM source_schema |
TABLE target_table [AS EXTERNAL] FROM source_table }
[SET OWNER principal]
[DRY RUN]
Parameters
SCHEMA
SYNC
tutte le tables che si trovano all'interno di un schema.-
Un schema esistente in Unity Catalog dove l'utente è autorizzato a creare tables.
-
Un schema esistente nella
hive_metastore
catalog, che è di proprietà dell'utente.
-
TABLE
SYNC
un individuo table.-
Un nuovo table o esistente in Unity Catalog all'interno di un schema in cui l'utente è autorizzato a creare tables. Se il table esiste già, viene sostituito in modo che corrisponda a
source_table
e l'utente deve anche possedere il table. Se il table non esiste, verrà creato. -
Un table esistente in
hive_metastore
di proprietà dell'utente.
-
-
Facoltativamente, set il proprietario del tables aggiornato in Unity Catalog a
principal
. Il proprietario predefinito è l'utente corrente. AS EXTERNAL
SYNC
un Hive gestito table o un schema che è archiviato all'esterno dell'area di lavoro di Databricks (talvolta definita root DBFS) verso tables esterni in Unity Catalog. Non è possibile usareAS EXTERNAL
per aggiornare i file tables gestiti da Hive archiviati nell'archiviazione dell'area di lavoro.DRY RUN
Se specificato, si verifica se è possibile aggiornare il
source_table
o il tables all'interno disource_schema
senza effettivamente creare o aggiornare il tablesdi destinazione. Il comando restituisceDRY_RUN_SUCCESS
se è possibile aggiornare un table.AS EXTERNAL
Avvio di Databricks Runtime 13.2 e versioni successive, questa clausola facoltativa può essere aggiunta per specificare che i tables gestiti nel metastore hive vengono aggiornati come tables esterni in Unity Catalog. Se usato conSYNC SCHEMA
, si applica a tutti i tables, inclusi i tables gestiti nelsource_schema.
Valori restituiti
Report con il columnsseguente:
source_schema STRING
Il nome della fonte schema. Il schema è
NULL
se l'origine è una visualizzazione temporanea non supportata.source_name STRING NOT NULL
Il nome della sorgente table.
source_type STRING NOT NULL
Tipo di table:
MANAGED
oEXTERNAL
target_catalog STRING NOT NULL
Il catalog di destinazione in Unity Catalogwhere è sincronizzato con il table.
target_schema STRING NOT NULL
Il schema di destinazione in Unity Catalogwhere il table viene sincronizzato.
target_name STRING NOT NULL
Nome del table in Unity Catalog a cui è sincronizzata la sorgente table. Questo nome corrisponde al nome del table di origine.
status_code STRING NOT NULL
Codice di stato per il risultato del comando
SYNC
per l'origine table.description STRING
Messaggio descrittivo sullo stato del comando sync per l'origine table.
Codici di stato comuni restituiti da SYNC
Il comando SYNC
fornisce un campo status_code
univoco nell'output per ogni table da aggiornare al Catalog Unity che rappresenta lo stato dell'aggiornamento.
Alcuni codici di stato comuni insieme alle raccomandazioni per risolverli sono:
DRY_RUN_SUCCESS
: esecuzione asciutta completata.Il table può essere aggiornato a Unity Catalog usando il comando
SYNC
.DBFS_ROOT_LOCATION
: Table che si trova nella radice del file system di Databricks."Il "table" si trova nella posizione radice del file system di Databricks." Questo non è supportato in Unity Catalog. ** Copiare i dati table nella posizione Unity Catalog usando un comando CREATE TABLE con l'opzione
DEEP CLONE
.EXTERNAL_TABLE_IN_MANAGED_LOCATION
: il percorso esterno table non può trovarsi sotto un'archiviazione gestita.Il percorso specificato per il table esterno si trova all'interno della gestione dell'archiviazione di Unity Catalog. Se il table deve trovarsi nell'archiviazione gestita, aggiornare il table come table gestito usando un comando CREATE TABLE con l'opzione
DEEP CLONE
o spostare table dall'archiviazione gestita di Unity Catalog.HIVE_SERDE
: il table non è idoneo per un aggiornamento da Hive Metastore a Unity Catalog. Motivo: Hive SerDe Table.I tables SerDe Hive non sono supportati da Unity Catalog. Modificare il tables in formato Delta ed eseguire il comando
SYNC
per eseguire l'aggiornamento.INVALID_DATASOURCE_FORMAT
: formato dell'origine dati non specificato o non supportato.Usare uno dei formati di origine dati supportati: Delta, Parquet, CSV, JSON, ORC, TEXT
LOCATION_OVERLAP
: il percorso di input si sovrappone ad altri tablesesterni.La posizione table si sovrappone ad altre tablesesterne. Usare un percorso diverso per il table o remove l'tablesesterno sovrapposto.
MULTIPLE_EXT_LOCATIONS
: il percorso di input contiene altre posizioni esterne.Esistono più posizioni esterne che sono sottodirectory del percorso di table specificato. Verificare se le ubicazioni esterne all'interno della posizione table sono necessarie.
MULTIPLE_TARGET_TABLE
: esiste già un table sincronizzato diverso. È consentito avere un solo elemento di destinazione table per ciascun elemento di origine table.Il table di origine è già stato sincronizzato in precedenza con un altro table di destinazione, cosa non consentita. Per forzare il
SYNC
a un tablediverso, remove la proprietà tableupgraded_to
dalla sorgente table oppure remove l'table precedentemente sincronizzato da Unity Catalog se non è più necessario.NOT_EXTERNAL
: Table non è idoneo per l'aggiornamento da Hive Metastore a Unity Catalog. Motivo: non si tratta di un tableesterno.Il comando
SYNC
supporta solo la migrazione degli tables esterni a Unity Catalog. Per tablesgestito, creare un table gestito in Unity Catalog usando un comando CREATE TABLE con l'opzioneDEEP CLONE
. In alternativa, usare la clausolaAS EXTERNAL
con il comandoSYNC
per creare un table esterno in Unity Catalog.READ_ONLY_CATALOG
: i dati all'interno di una condivisione Delta catalog sono di sola lettura e non possono essere modificati o eliminati.Il catalog scelto è un catalog di condivisione differenziale di sola lettura. Tables all'interno di un catalog di sola lettura non può essere aggiornato tramite il comando
SYNC
.SUCCESS
: Table sincronizzata correttamente.TABLE_ALREADY_EXISTS
: Il target table esiste già.Un table con lo stesso nome del table scelto esiste già in Unity Catalog. Rinominare o remove il table esistente in Unity Catalog ed eseguire di nuovo il comando
SYNC
.TEMP_TABLE_NOT_SUPPORTED
: le tables temporanee o le views non sono supportate.Non è possibile aggiornare i temporanei tables o views a Unity Catalog. Per utilizzare tables temporanei o views, ricrearli in Unity Catalog utilizzando il comando SHOW CREATE TABLE in Unity Catalog.
TIMEOUT
: l'attività Sync ha superato il tempo limite.Il completamento dell'attività di comando sync ha richiesto più di 300 secondi. Aumentare
spark.databricks.sync.command.task.timeout
a un valore superiore in secondi. Il valore predefinito è 300. Se l'errore persiste, contattare il supporto tecnico.VIEWS_NOT_SUPPORTED
: Views non sono supportati.Ricreare il views manualmente usando il comando SHOW CREATE TABLE in Unity Catalog.
Esempi
-- Sync an existing hive metastore table hive_metastore.default.my_tbl to a Unity Catalog
-- table named main.default.my_tbl.
> SYNC TABLE main.default.my_tbl FROM hive_metastore.default.my_tbl;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
default my_tbl external main default my_tbl SUCCESS Table main.default.my_tbl synced.
-- Sync an existing managed hive metastore table hive_metastore.default.my_tbl to an external table named main.default.my_tbl in Unity Catalog.
> SYNC TABLE main.default.my_tbl AS EXTERNAL FROM hive_metastore.default.my_tbl;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
default my_tbl managed main default my_tbl SUCCESS Table main.default.my_tbl synced.
-- SYNC a table in DRY RUN mode to evaluate the upgradability of the hive metastore table.
> SYNC TABLE main.default.my_tbl FROM hive_metastore.default.my_tbl DRY RUN;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- --------------- ---------------------------------
default my_tbl external main default my_tbl DRY_RUN_SUCCESS
-- SYNC all the eligible tables in schema hive_metastore.mydb to a Unity Catalog schema main.my_db_uc.
-- The upgraded tables in main.my_db_uc will be owned by alf@melmak.et
> SYNC SCHEMA main.my_db_uc FROM hive_metastore.my_db SET OWNER `alf@melmak.et`;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
...
-- DRY RUN mode of SYNC SCHEMA to evaluate all the tables in a schema
-- hive_metastore.mydb for upgrading to Unity Catalog.
> SYNC SCHEMA main.my_db_uc FROM hive_metastore.my_db DRY RUN;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
...
-- Sync all tables including managed tables in a schema hive_metastore.mydb
-- as external tables in Unity Catalog.
> SYNC SCHEMA main.my_db_uc AS EXTERNAL FROM hive_metastore.my_db;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
...