Dela via

SYNC

Gäller endast för:markerad ja Databricks SQL markerad ja Databricks Runtime markerad ja Unity Catalog

SYNC Använd kommandot för att uppgradera externa tabeller i Hive Metastore till externa tabeller i Unity Catalog. Du kan också använda SYNC för att uppgradera Hive-hanterade tabeller som lagras utanför Databricks-arbetsytans lagring (kallas ibland DBFS-rot) till externa tabeller i Unity Catalog. Du kan inte använda den för att uppgradera Hive-hanterade tabeller som lagras i arbetsytelagring. Om du vill uppgradera dessa tabeller använder du CREATE TABLE CLONE.

Du kan använda SYNC för att skapa nya tabeller i Unity Catalog från befintliga Hive Metastore-tabeller samt uppdatera Unity Catalog-tabellerna när källtabellerna i Hive-metaarkivet ändras.

Kommandot SYNC kan köras på schemanivå med hjälp av syntaxen SYNC SCHEMA eller för en enskild tabell med hjälp av syntaxen SYNC TABLE .

Kommandot utför en skrivåtgärd (ALTER TABLE) till varje källtabell som den uppgraderar för att lägga till ytterligare tabellegenskaper för sin bokföring. Om det gäller Delta-tabeller måste det kluster eller SQL Warehouse som kör kommandot ha skrivåtkomst till tabellplatsen för att kunna utföra skrivåtgärden.

I Databricks Runtime 12.2 LTS eller senare kan det här beteendet inaktiveras genom att ställa in Spark-konfigurationen spark.databricks.sync.command.disableSourceTableWrites på true innan kommandot körs SYNC . När värdet är inställt på lägger true du inte till SYNCnya tabellegenskaper och kan därför inte identifiera om tabellen tidigare har uppgraderats till Unity Catalog. I så fall förlitar den sig uteslutande på tabellnamnet för att avgöra om tabellen tidigare har uppgraderats till Unity Catalog. Om källtabellen har bytt namn sedan det senaste kommandot SYNC måste användaren byta namn på måltabellen manuellt innan kommandot SYNC körs igen när konfigurationen true.

Viktigt!

När ett SYNC kommando körs lägger åtgärden SET TBLPROPERTIES till en tabellegenskap som anger den externa tabellreferensen för målkatalogen för Unity Catalog. Den här åtgärden beräknar en ny deltaögonblicksbild och lägger till en ny post i deltaloggen i tabellen och skriver till måltabellsökvägen i molnlagringen.

Syntax

SYNC { SCHEMA target_schema [AS EXTERNAL] FROM source_schema |
       TABLE target_table [AS EXTERNAL] FROM source_table }
  [SET OWNER principal]
  [DRY RUN]

Parametrar

  • SCHEMA

    SYNC alla tabeller i ett schema.

    • target_schema

      Ett befintligt schema i Unity Catalog där användaren har behörighet att skapa tabeller.

    • källschema

      Ett befintligt schema i hive_metastore katalogen som ägs av användaren.

  • TABLE

    SYNC en enskild tabell.

    • target_table

      En ny eller befintlig tabell i Unity Catalog i ett schema där användaren har behörighet att skapa tabeller. Om tabellen redan finns ersätts den för att matcha source_table, och användaren måste också äga tabellen. Om tabellen inte finns skapas den.

    • källtabell

      En befintlig tabell hive_metastore där användaren äger.

  • rektor

    Du kan också ange ägaren till de uppgraderade tabellerna i Unity Catalog till principal. Standardägaren är den aktuella användaren.

  • AS EXTERNAL

    SYNC en Hive-hanterad tabell eller ett schema som lagras utanför Databricks-arbetsytans lagring (kallas ibland DBFS-rot) för externa tabeller i Unity Catalog. Du kan inte använda AS EXTERNAL för att uppgradera Hive-hanterade tabeller som lagras i arbetsytelagring.

  • DRY RUN

    När du anger det kontrollerar du om tabellerna source_table eller i source_schema kan uppgraderas utan att skapa eller uppgradera måltabellerna. Kommandot returnerar DRY_RUN_SUCCESS om en tabell kan uppgraderas.

  • AS EXTERNAL Om du startar Databricks Runtime 13.2 och senare kan du lägga till den här valfria satsen för att ange att hanterade tabeller i hive-metaarkivet uppgraderas som externa tabeller i Unity Catalog. När det används med SYNC SCHEMAgäller det för alla tabeller, inklusive hanterade tabeller i source_schema.

Returer

En rapport med följande kolumner:

  • source_schema STRING

    Namnet på källschemat. Schemat är NULL om källan är en temporär vy som inte stöds.

  • source_name STRING NOT NULL

    Namnet på källtabellen.

  • source_type STRING NOT NULL

    Tabellens typ: MANAGED eller EXTERNAL

  • target_catalog STRING NOT NULL

    Målkatalogen i Unity Catalog där tabellen synkroniseras.

  • target_schema STRING NOT NULL

    Målschemat i Unity Catalog där tabellen synkroniseras.

  • target_name STRING NOT NULL

    Namnet på tabellen i Unity Catalog som källtabellen synkroniseras till. Det här namnet matchar källtabellens namn.

  • status_code STRING NOT NULL

    En statuskod för resultatet av SYNC kommandot för källtabellen.

  • description STRING

    Ett beskrivande meddelande om status för synkroniseringskommandot för källtabellen.

Vanliga statuskoder som returneras av SYNC

Kommandot SYNC innehåller ett unikt status_code fält i utdata för varje tabell som ska uppgraderas till Unity-katalogen som representerar uppgraderingens status. Några vanliga statuskoder tillsammans med rekommendationerna för att åtgärda dem är:

  • DRY_RUN_SUCCESS: Torrkörning lyckades.

    Tabellen kan uppgraderas till Unity Catalog med hjälp av SYNC kommandot .

  • DBFS_ROOT_LOCATION: Tabell som finns i roten för Databricks-filsystemet.

    Tabellen finns i rotsökvägen för Databricks File System. Detta stöds inte i Unity Catalog. Kopiera tabelldata till Unity Catalog-platsen med hjälp av ett CREATE TABLE-kommando med alternativet DEEP CLONE.

  • EXTERNAL_TABLE_IN_MANAGED_LOCATION: Den externa tabellsökvägen kan inte vara under hanterad lagring.

    Sökvägen som anges för den externa tabellen finns i Unity Catalog hantera lagring. Om tabellen måste finnas under den hanterade lagringen uppgraderar du tabellen som en hanterad tabell med hjälp av ett CREATE TABLE-kommando med alternativet DEEP CLONE eller flyttar tabellplatsen från den hanterade lagringsplatsen i Unity Catalog.

  • HIVE_SERDE: Tabellen är inte berättigad till en uppgradering från Hive Metastore till Unity Catalog. Orsak: Hive SerDe-tabell.

    Hive SerDe-tabeller stöds inte av Unity Catalog. Ändra tabellerna till Delta-format och utfärda SYNC kommandot för att uppgradera.

  • INVALID_DATASOURCE_FORMAT: Datakällans format har inte angetts eller stöds inte.

    Använd något av de datakällformat som stöds: Delta, Parquet, CSV, JSON, ORC, TEXT, AVRO

  • LOCATION_OVERLAP: Indatasökvägen överlappar andra externa tabeller.

    Tabellplatsen överlappar andra externa tabeller. Använd en annan plats för tabellen eller ta bort de överlappande externa tabellerna.

  • MULTIPLE_EXT_LOCATIONS: Indatasökvägen innehåller andra externa platser.

    Det finns fler än en extern plats som är underkataloger till den angivna tabellsökvägen. Kontrollera om de externa platserna i tabellplatsen är nödvändiga.

  • MULTIPLE_TARGET_TABLE: Det finns redan en annan synkroniserad tabell. Endast en måltabell per källtabell tillåts.

    Källtabellen har redan synkroniserats till en annan måltabell tidigare, vilket inte är tillåtet. Om du vill tvinga SYNC till en annan tabell tar du bort tabellegenskapen upgraded_to från källtabellen eller tar bort den tidigare synkroniserade tabellen från Unity Catalog om den inte längre behövs.

  • NOT_EXTERNAL: Tabellen är inte berättigad till uppgradering från Hive Metastore till Unity Catalog. Orsak: Inte en extern tabell.

    SYNC kommandot stöder endast migrering av externa tabeller till Unity Catalog. För hanterade tabeller skapar du en hanterad tabell i Unity Catalog med hjälp av ett CREATE TABLE kommando med alternativet DEEP CLONE. Du kan också använda AS EXTERNAL -satsen med SYNC kommandot för att skapa en extern tabell i Unity Catalog.

  • READ_ONLY_CATALOG: Data i en deltadelningskatalog är skrivskyddade och kan inte ändras eller tas bort.

    Den valda katalogen är en deltadelningskatalog som är skrivskyddad. Det går inte att uppdatera tabeller i en skrivskyddad katalog med kommandot SYNC .

  • SUCCESS: Tabellen har synkroniserats.

  • TABLE_ALREADY_EXISTS: Måltabellen finns redan.

    Det finns redan en tabell med samma namn som den valda tabellen i Unity Catalog. Byt namn på eller ta bort den befintliga tabellen i Unity Catalog och kör kommandot igen SYNC .

  • TEMP_TABLE_NOT_SUPPORTED: Tillfälliga tabeller eller vyer stöds inte.

    Tillfälliga tabeller eller vyer kan inte uppgraderas till Unity Catalog. Om du vill använda temporära tabeller eller vyer återskapar du dem i Unity Catalog med hjälp av kommandot SHOW CREATE TABLE i Unity Catalog.

  • TIMEOUT: Tidsgränsen för synkroniseringsaktiviteten har överskrids.

    Det tog mer än 600 sekunder att slutföra kommandouppgiften för synkroniseringstabellen. Öka spark.databricks.sync.command.task.timeout till ett högre värde i sekunder.

    Alternativt kan en synkroniseringsschemauppgift tidsavbrytas, i vilket fall du kommer att se en TimeoutException. Öka spark.databricks.sync.command.task.create.timeout till ett högre värde i sekunder.

    Standardvärdet för båda flaggorna är 600. Kontakta supporten om problemet kvarstår.

  • VIEWS_NOT_SUPPORTED: Vyer stöds inte.

    Återskapa vyerna manuellt med kommandot SHOW CREATE TABLE i Unity Catalog.

Exempel

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

Felsökning

  • Icke-ASCII-tecken i tabellkommentar synkroniseras inte korrekt

    När du uppgraderar tabeller från Hive-metaarkivet till Unity Catalog med kommandot SYNC kan tabellkommentar som innehåller icke-ASCII-tecken (till exempel japansk eller kinesisk text) se skadade ut. Berörda kommentarer kan till exempel visas som en serie frågetecken (???) eller inte återges i Katalogutforskaren. Om du frågar efter kommentarerna med hjälp av DESCRIBE TABLE EXTENDED returneras dock rätt värden.

    Det här problemet beror på att Hive-metaarkivet kan lagra kommentarer med hjälp av teckenuppsättningen latin1 som standard, vilket inte stöder icke-ASCII-tecken. När Unity Catalog hämtar kommentarer med SYNC kan tecken som inte stöds gå förlorade eller skadas.

    Om du vill återställa icke-ASCII-tecken i kommentarer efter uppgradering med SYNCkör du följande kommando i den berörda tabellen i Unity Catalog:

    MSCK REPAIR TABLE <catalog>.<schema>.<table_name> SYNC METADATA;