Condividi tramite

SYNC

  • Articolo

Si applica solo a:segno di spunta sìDatabricks SQL segno di spunta sì Databricks Runtime segno di spunta sì Unity Catalog

Usare il SYNC comando per aggiornare tabelle esterne in Metastore Hive a tabelle esterne nel catalogo Unity. È anche possibile usare SYNC per aggiornare le tabelle gestite Hive archiviate all'esterno dell'archiviazione dell'area di lavoro di Databricks (talvolta denominata radice DBFS) a tabelle esterne in Unity Catalog. Non è possibile usarlo per aggiornare le tabelle gestite Hive archiviate nell'archiviazione dell'area di lavoro. Per aggiornare tali tabelle, usare CREATE TABLE CLONE.

È possibile usare SYNC per creare nuove tabelle in Unity Catalog da tabelle Metastore Hive esistenti e aggiornare le tabelle del catalogo Unity quando vengono modificate le tabelle di origine in Metastore Hive.

Il SYNC comando può essere eseguito a livello di schema usando la SYNC SCHEMA sintassi o per una singola tabella usando la SYNC TABLE sintassi .

Il comando esegue un'operazione di scrittura (ALTER TABLE) per ogni tabella di origine che aggiorna per aggiungere alcune proprietà di tabella aggiuntive per la relativa contabilità. In caso di tabelle Delta, per eseguire l'operazione di scrittura il cluster o SQL Warehouse che esegue il comando deve avere accesso in scrittura al percorso della tabella.

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. Se impostato su true, SYNC non aggiunge nuove proprietà di tabella e pertanto potrebbe non rilevare se la tabella è stata aggiornata in precedenza a Unity Catalog. In tal caso, si basa esclusivamente sul nome della tabella per determinare se la tabella è stata precedentemente aggiornata a Unity Catalog. Se la tabella di origine è stata rinominata dall'ultimo comando SYNC, l'utente deve rinominare manualmente la tabella di destinazione prima di eseguire nuovamente il comando SYNC quando la configurazione è true.

Importante

Quando viene eseguito un SYNC comando, l'operazione SET TBLPROPERTIES aggiunge una proprietà di tabella che indica il riferimento alla tabella esterna del catalogo Unity di destinazione. Questa operazione calcola un nuovo snapshot Delta e aggiunge una nuova voce al log Delta della tabella, scrivendo nel percorso della tabella 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]

Parametri

  • SCHEMA

    SYNC tutte le tabelle all'interno di uno schema.

    • target_schema

      Schema esistente nel catalogo Unity in cui l'utente è autorizzato a creare tabelle.

    • source_schema

      Schema esistente nel hive_metastore catalogo, di proprietà dell'utente.

  • TABLE

    SYNC una singola tabella.

    • target_table

      Tabella nuova o esistente nel catalogo Unity in uno schema in cui l'utente è autorizzato a creare tabelle. Se la tabella esiste già, viene sostituita in modo che corrisponda source_tablea e l'utente deve anche essere proprietario della tabella. Se la tabella non esiste, verrà creata.

    • source_table

      Tabella esistente di hive_metastore proprietà dell'utente.

  • principal

    Facoltativamente, impostare il proprietario delle tabelle aggiornate in Unity Catalog su principal. Il proprietario predefinito è l'utente corrente.

  • AS EXTERNAL

    SYNC una tabella gestita o uno schema Hive archiviato all'esterno dell'archiviazione dell'area di lavoro di Databricks (talvolta denominata radice DBFS) in tabelle esterne nel catalogo Unity. Non è possibile usare AS EXTERNAL per aggiornare le tabelle gestite Hive archiviate nell'archiviazione dell'area di lavoro.

  • DRY RUN

    Se specificato, viene verificato se è possibile aggiornare le source_table tabelle o all'interno source_schema senza creare o aggiornare effettivamente le tabelle di destinazione. Il comando restituisce DRY_RUN_SUCCESS se è possibile aggiornare una tabella.

  • AS EXTERNAL A partire da Databricks Runtime 13.2 e versioni successive, questa clausola facoltativa può essere aggiunta per specificare che le tabelle gestite nel metastore hive vengono aggiornate come tabelle esterne in Unity Catalog. Se usato con SYNC SCHEMA, si applica a tutte le tabelle, incluse le tabelle gestite nel source_schema.

Valori restituiti

Report con le colonne seguenti:

  • source_schema STRING

    Nome dello schema di origine. Lo schema è NULL se l'origine è una visualizzazione temporanea non supportata.

  • source_name STRING NOT NULL

    Nome della tabella di origine.

  • source_type STRING NOT NULL

    Tipo della tabella: MANAGED o EXTERNAL

  • target_catalog STRING NOT NULL

    Catalogo di destinazione in Unity Catalog in cui viene sincronizzata la tabella.

  • target_schema STRING NOT NULL

    Schema di destinazione in Unity Catalog in cui viene sincronizzata la tabella.

  • target_name STRING NOT NULL

    Nome della tabella in Unity Catalog in cui viene sincronizzata la tabella di origine. Questo nome corrisponde al nome della tabella di origine.

  • status_code STRING NOT NULL

    Codice di stato per il risultato del SYNC comando per la tabella di origine.

  • description STRING

    Messaggio descrittivo sullo stato del comando di sincronizzazione per la tabella di origine.

Codici di stato comuni restituiti da SYNC

Il SYNC comando fornisce un campo univoco status_code nell'output per ogni tabella da aggiornare al catalogo Unity che rappresenta lo stato dell'aggiornamento. Alcuni codici di stato comuni insieme alle raccomandazioni per risolverli sono:

  • DRY_RUN_SUCCESS: esecuzione asciutta completata.

    La tabella può essere aggiornata a Unity Catalog usando il SYNC comando .

  • DBFS_ROOT_LOCATION: tabella che si trova nella radice del file system di Databricks.

    La tabella si trova nel percorso radice del file system di Databricks. Questo non è supportato nel catalogo unity. Copiare i dati della tabella nel percorso del catalogo Unity usando un comando CREATE TABLE con l'opzione DEEP CLONE .

  • EXTERNAL_TABLE_IN_MANAGED_LOCATION: il percorso della tabella esterna non può trovarsi nell'archiviazione gestita.

    Il percorso specificato per la tabella esterna si trova all'interno dell'archivio gestito dal catalogo unity. Se la tabella deve trovarsi nella risorsa di archiviazione gestita, aggiornare la tabella come tabella gestita usando un comando CREATE TABLE con l'opzione DEEP CLONE o spostare la posizione della tabella dall'archiviazione gestita di Unity Catalog.

  • HIVE_SERDE: la tabella non è idonea per un aggiornamento da Hive Metastore a Unity Catalog. Motivo: Tabella SerDe Hive.

    Le tabelle SerDe Hive non sono supportate dal catalogo unity. Modificare le tabelle in formato Delta ed eseguire il SYNC comando da aggiornare.

  • 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 altre tabelle esterne.

    La posizione della tabella si sovrappone ad altre tabelle esterne. Utilizzare un percorso diverso per la tabella o rimuovere le tabelle esterne sovrapposte.

  • MULTIPLE_EXT_LOCATIONS: il percorso di input contiene altre posizioni esterne.

    Esistono più posizioni esterne che sono sottodirectory del percorso della tabella specificato. Controllare se sono necessarie le posizioni esterne all'interno della posizione della tabella.

  • MULTIPLE_TARGET_TABLE: esiste già una tabella sincronizzata diversa. È consentita una sola tabella di destinazione per tabella di origine.

    La tabella di origine è già stata sincronizzata con una tabella di destinazione diversa in precedenza non consentita. Per forzare l'oggetto SYNC in una tabella diversa, rimuovere la proprietà upgraded_to table dalla tabella di origine o rimuovere la tabella sincronizzata in precedenza da Unity Catalog, se non è più necessaria.

  • NOT_EXTERNAL: la tabella non è idonea per l'aggiornamento da Metastore Hive a Unity Catalog. Motivo: non una tabella esterna.

    SYNC il comando supporta solo la migrazione di tabelle esterne a Unity Catalog. Per le tabelle gestite, creare una tabella gestita nel catalogo unity usando un comando CREATE TABLE con l'opzione DEEP CLONE . In alternativa, usare la AS EXTERNAL clausola con il SYNC comando per creare una tabella esterna nel catalogo unity.

  • READ_ONLY_CATALOG: i dati all'interno di un catalogo di condivisione Delta sono di sola lettura e non possono essere modificati o eliminati.

    Il catalogo scelto è un catalogo di condivisione differenziale di sola lettura. Non è possibile aggiornare le tabelle all'interno di un catalogo di sola lettura usando il SYNC comando .

  • SUCCESS: tabella sincronizzata correttamente.

  • TABLE_ALREADY_EXISTS: tabella di destinazione già esistente.

    Una tabella con lo stesso nome della tabella scelta esiste già in Unity Catalog. Rinominare o rimuovere la tabella esistente in Unity Catalog ed eseguire di nuovo il SYNC comando .

  • TEMP_TABLE_NOT_SUPPORTED: le tabelle o le viste temporanee non sono supportate.

    Non è possibile aggiornare tabelle o viste temporanee a Unity Catalog. Per usare tabelle o viste temporanee, ricrearle nel catalogo unity usando il comando SHOW CREATE TABLE in Unity Catalog.

  • TIMEOUT: timeout dell'attività di sincronizzazione.

    Il completamento dell'attività di comando di sincronizzazione 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: le visualizzazioni non sono supportate.

    Ricreare manualmente le visualizzazioni usando il comando SHOW CREATE TABLE nel catalogo unity.

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
  ------------- ----------- ----------- -------------- ------------- ----------- -----------     ---------------------------------
  ...