Sdílet prostřednictvím

SYNC

platí pro:zaškrtnuto Ano Databricks SQL zaškrtnuto Ano Databricks Runtime zaškrtnuto Ano pouze Unity Catalog.

Pomocí příkazu SYNC upgradujte externí tabulky v Metastore Hive na externí tabulky v katalogu Unity. Můžete také použít SYNC k upgradu spravovaných tabulek Hive, které jsou uložené mimo úložiště pracovních prostorů Databricks (někdy označované jako kořen DBFS) na externí tabulky v katalogu Unity. Nemůžete ji použít k upgradu spravovaných tabulek Hive uložených v úložišti pracovního prostoru. Pokud chcete tyto tabulky upgradovat, použijte CREATE TABLE CLONE.

Pomocí SYNC můžete vytvářet nové tabulky v katalogu Unity z existujících tabulek metastoru Hive a aktualizovat tabulky katalogu Unity při úpravě zdrojových tabulek v metastoru Hive.

Příkaz SYNC lze spustit na úrovni schématu pomocí syntaxe SYNC SCHEMA nebo pro jednotlivé tabulky pomocí syntaxe SYNC TABLE.

Příkaz provede operaci zápisu (ALTER TABLE) pro každou zdrojovou tabulku, kterou upgraduje, aby přidal některé dodatečné vlastnosti tabulky pro své vedení záznamů. V případě tabulek Delta musí mít cluster nebo SQL Warehouse, který spouští příkaz, přístup k zápisu do umístění tabulky, aby mohl provést operaci zápisu.

V Databricks Runtime 12.2 LTS nebo novějším můžete toto chování vypnout nastavením konfigurace spark.databricks.sync.command.disableSourceTableWrites Sparku na true před spuštěním SYNC příkazu. Pokud je nastavená hodnota true, SYNC nepřidá nové vlastnosti tabulky, a proto nemusí zjistit, jestli byla tabulka dříve upgradována na Katalog Unity. V takovém případě se výhradně spoléhá na název tabulky a určí, jestli byla tabulka dříve upgradována na katalog Unity. Pokud byla zdrojová tabulka přejmenována od posledního příkazu SYNC, musí uživatel před opětovným spuštěním příkazu SYNC znovu přejmenovat cílovou tabulku, když je konfigurace true.

Důležité

Když se spustí příkaz SYNC, operace SET TBLPROPERTIES přidá vlastnost tabulky, která označuje cílovou externí tabulku katalogu Unity. Tato operace vypočítá nový snímek Delta a přidá novou položku do protokolu Delta tabulky; zapisuje do cílové cesty tabulky v cloudovém úložišti.

Syntaxe

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

Parametry

  • SCHEMA

    SYNC všechny tabulky v rámci schématu.

    • cílové_schema

      Existující schéma v katalogu Unity, ve kterém má uživatel oprávnění vytvářet tabulky.

    • zdrojové schéma

      Existující schéma v katalogu hive_metastore, které vlastní uživatel.

  • TABLE

    SYNC jednotlivá tabulka.

    • cílová_tabulka

      Nová nebo existující tabulka v katalogu Unity ve schématu, ve kterém má uživatel oprávnění vytvářet tabulky. Pokud tabulka již existuje, je nahrazena tak, aby odpovídala source_table, a uživatel musí také vlastnit tabulku. Pokud tabulka neexistuje, vytvoří se.

    • zdrojová_tabule

      Existující tabulka v hive_metastore, kterou uživatel vlastní.

  • hlavní

    Volitelně můžete nastavit vlastníka upgradovaných tabulek v katalogu Unity na principal. Výchozím vlastníkem je aktuální uživatel.

  • AS EXTERNAL

    SYNC spravovanou tabulku nebo schéma Hive uložené mimo úložiště pracovního prostoru Databricks (někdy označované jako kořen DBFS) do externích tabulek v katalogu Unity. Nemůžete použít AS EXTERNAL k upgradu spravovaných tabulek Hive uložených v úložišti pracovního prostoru.

  • DRY RUN

    Při zadání zkontroluje, zda je možné upgradovat source_table nebo tabulky v rámci source_schema, aniž by skutečně došlo k vytvoření nebo upgradu cílových tabulek. Příkaz vrátí DRY_RUN_SUCCESS, pokud je možné upgradovat tabulku.

  • AS EXTERNAL Od Databricks Runtime verze 13.2 a výše lze přidat tuto volitelnou klauzuli, aby se určilo, že spravované tabulky v Hive metastoru se upgradují na externí tabulky v Katalogu Unity. Při použití s SYNC SCHEMAse vztahuje na všechny tabulky, včetně spravovaných tabulek v source_schema.

Návraty

Sestava s následujícími sloupci:

  • source_schema STRING

    Název zdrojového schématu. Schéma je 'NULL', pokud je zdrojem nepodporované dočasné zobrazení.

  • source_name STRING NOT NULL

    Název zdrojové tabulky.

  • source_type STRING NOT NULL

    Typ tabulky: MANAGED nebo EXTERNAL

  • target_catalog STRING NOT NULL

    Cílový katalog v katalogu Unity, kde se tabulka synchronizuje.

  • target_schema STRING NOT NULL

    Cílové schéma v katalogu Unity, kde se tabulka synchronizuje.

  • target_name STRING NOT NULL

    Název tabulky v katalogu Unity, do které se zdrojová tabulka synchronizuje. Tento název odpovídá názvu zdrojové tabulky.

  • status_code STRING NOT NULL

    Stavový kód pro výsledek příkazu SYNC u zdrojové tabulky.

  • description STRING

    Popisná zpráva o stavu příkazu synchronizace pro zdrojovou tabulku

Běžné stavové kódy vrácené SYNC

Příkaz SYNC poskytuje jedinečné pole status_code ve výstupu pro upgrade každé tabulky na katalog Unity představující stav upgradu. Mezi běžné stavové kódy a doporučení k jejich řešení patří:

  • DRY_RUN_SUCCESS: Suchý běh proběhl úspěšně.

    Tabulku je možné upgradovat na Katalog Unity pomocí příkazu SYNC.

  • DBFS_ROOT_LOCATION: Tabulka umístěná v kořenovém adresáři systému souborů Databricks.

    Tabulka se nachází v kořenovém umístění systému souborů Databricks. Toto není podporováno v katalogu Unity. Data tabulky zkopírujte do umístění katalogu Unity pomocí příkazu CREATE TABLE s volbou DEEP CLONE.

  • EXTERNAL_TABLE_IN_MANAGED_LOCATION: Cesta k externí tabulce nemůže být ve spravovaném úložišti.

    Cesta uvedená pro externí tabulku se nachází ve spravovaném úložišti Katalogu Unity. Pokud musí být tabulka pod spravovaným úložištěm, upgradujte tabulku jako spravovanou tabulku pomocí příkazu CREATE TABLE s možností DEEP CLONE nebo přesuňte umístění tabulky ze spravovaného úložiště Katalogu Unity.

  • HIVE_SERDE: Tabulka nemá nárok na upgrade z metastoru Hive na katalog Unity. Důvod: Tabulka Hive SerDe

    Katalog Unity nepodporuje tabulky Hive SerDe. Změňte tabulky do formátu Delta a zadejte příkaz SYNC k upgradu.

  • INVALID_DATASOURCE_FORMAT: Formát zdroje dat není zadán nebo není podporován.

    Použijte jeden z podporovaných formátů zdroje dat: Delta, Parquet, CSV, JSON, ORC, TEXT, AVRO.

  • LOCATION_OVERLAP: Vstupní cesta se překrývá s jinými externími tabulkami.

    Umístění tabulky se překrývá s jinými externími tabulkami. Pro tabulku použijte jiné umístění nebo odeberte překrývající se externí tabulky.

  • MULTIPLE_EXT_LOCATIONS: Vstupní cesta obsahuje další externí umístění.

    Existuje více než jedno externí umístění, které jsou podadresářem zadané cesty k tabulce. Zkontrolujte, zda jsou externí umístění v rámci tabulky nutná.

  • MULTIPLE_TARGET_TABLE: Již existuje jiná synchronizovaná tabulka. Je povolena pouze jedna cílová tabulka na jednu zdrojovou tabulku.

    Zdrojová tabulka byla již dříve synchronizována s jinou cílovou tabulkou, což není povoleno. Pokud chcete vynutit SYNC na jinou tabulku, odeberte vlastnost tabulky upgraded_to ze zdrojové tabulky nebo odeberte dříve synchronizovanou tabulku z katalogu Unity, pokud už ji nepotřebujete.

  • NOT_EXTERNAL: Tabulka nemá nárok na upgrade z metastoru Hive na katalog Unity. Důvod: Nejedná se o externí tabulku.

    SYNC příkaz podporuje pouze migraci externích tabulek do katalogu Unity. Pro spravované tabulky vytvořte spravovanou tabulku v katalogu Unity pomocí příkazu CREATE TABLE s možností DEEP CLONE. Případně můžete pomocí klauzule AS EXTERNAL s příkazem SYNC vytvořit externí tabulku v katalogu Unity.

  • READ_ONLY_CATALOG: Data v katalogu sdílení Delta jsou určená jen pro čtení a nelze je upravovat ani odstraňovat.

    Zvolený katalog je sdílený katalog delta, který je pouze pro čtení. Tabulky v katalogu jen pro čtení nelze aktualizovat pomocí příkazu SYNC.

  • SUCCESS: Tabulka se úspěšně synchronizovala.

  • TABLE_ALREADY_EXISTS: Cílová tabulka již existuje.

    Tabulka se stejným názvem jako vybraná tabulka již v katalogu Unity existuje. Přejmenujte nebo odeberte existující tabulku v katalogu Unity a spusťte příkaz SYNC znovu.

  • TEMP_TABLE_NOT_SUPPORTED: Dočasné tabulky nebo zobrazení nejsou podporovány.

    Dočasné tabulky nebo zobrazení nelze upgradovat na katalog Unity. Pokud chcete použít dočasné tabulky nebo zobrazení, vytvořte je znovu v Katalogu Unity pomocí příkazu SHOW CREATE TABLE v katalogu Unity.

  • TIMEOUT: Vypršel časový limit úlohy synchronizace.

    Dokončení úlohy příkazu synchronizační tabulky trvalo déle než 600 sekund. Zvyšte spark.databricks.sync.command.task.timeout na vyšší hodnotu během několika sekund.

    Případně může dojít k vypršení časového limitu úlohy schématu synchronizace, v takovém případě uvidíte TimeoutException. Zvyšte spark.databricks.sync.command.task.create.timeout na vyšší hodnotu během několika sekund.

    Výchozí hodnota obou příznaků je 600. Pokud problém přetrvává, obraťte se na podporu.

  • VIEWS_NOT_SUPPORTED: Zobrazení nejsou podporována.

    Znovu vytvořte zobrazení ručně pomocí příkazu SHOW CREATE TABLE v katalogu Unity.

Příklady

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

Řešení problémů

  • Znaky jiné než ASCII v komentářích tabulky se nesynchronizují správně

    Při upgradu tabulek z Hive metastore na Unity Catalog pomocí příkazu SYNC se můžou zobrazit komentáře tabulky, které obsahují znaky jiné než ASCII (například japonský nebo čínský text). Ovlivněné komentáře se můžou například zobrazit jako řada otazník (???) nebo se v Průzkumníku katalogu nevykreslí. Dotazování komentářů pomocí DESCRIBE TABLE EXTENDED vrátí správné hodnoty.

    K tomuto problému dochází, protože metastore Hive může ve výchozím nastavení ukládat komentáře pomocí latin1 znakové sady, která nepodporuje znaky jiné než ASCII. Když Katalog Unity načte komentáře pomocí SYNC, může dojít ke ztrátě nebo poškození nepodporovaných znaků.

    Pokud chcete znovu získat nebo obnovit znaky jiné než ASCII v komentářích po upgradu, spusťte následující příkaz v ovlivněné tabulce v katalogu Unity:

    MSCK REPAIR TABLE <catalog>.<schema>.<table_name> SYNC METADATA;
  • Last updated on