SYNC

Dotyczy: Databricks SQL Databricks Runtime tylko Unity Catalog

Użyj polecenia SYNC, aby uaktualnić tabele zewnętrzne w Hive Metastore do tabel zewnętrznych w Unity Catalog. Można również użyć SYNC, aby uaktualnić tabele zarządzane przez Hive przechowywane poza magazynem przestrzeni roboczej Databricks (czasami nazywanym katalogiem głównym systemu plików DBFS) do tabel zewnętrznych w Unity Catalog. Nie można go używać do aktualizacji tabel zarządzanych programu Hive przechowywanych w magazynie przestrzeni roboczej. Aby uaktualnić te tabele, użyj CREATE TABLE CLONE.

Można używać SYNC do tworzenia nowych tabel w katalogu Unity z istniejących tabel Metastore Hive, a także aktualizować te tabele w katalogu Unity, gdy tabele źródłowe w Metastore Hive zostaną zmodyfikowane.

Polecenie SYNC można uruchomić na poziomie schematu przy użyciu składni SYNC SCHEMA lub dla pojedynczej tabeli przy użyciu składni SYNC TABLE.

Polecenie wykonuje operację zapisu (ALTER TABLE) do każdej tabeli źródłowej, którą uaktualnia, aby dodać dodatkowe właściwości tabeli do celów księgowych. W przypadku tabel Delta, aby wykonać operację zapisu, klaster lub usługa SQL Warehouse, która uruchamia polecenie, musi mieć dostęp do zapisu w lokalizacji tabeli.

W środowisku Databricks Runtime 12.2 LTS lub nowszym to zachowanie można wyłączyć, ustawiając konfigurację spark.databricks.sync.command.disableSourceTableWrites platformy Spark na przed true uruchomieniem SYNC polecenia. W przypadku ustawienia wartości trueSYNC nie dodaje nowych właściwości tabeli i w związku z tym może nie być w stanie wykryć, czy tabela została wcześniej uaktualniona do Katalogu Unity. W takim przypadku polega wyłącznie na nazwie tabeli, aby określić, czy tabela została wcześniej uaktualniona do katalogu Unity. Jeśli nazwa tabeli źródłowej została zmieniona od ostatniego polecenia SYNC, użytkownik musi ręcznie zmienić nazwę tabeli docelowej przed ponownym uruchomieniem polecenia SYNC, gdy konfiguracja jest true.

Ważne

Po wykonaniu polecenia SYNC operacja SET TBLPROPERTIES dodaje właściwość tabeli wskazującą docelowy odnośnik do zewnętrznej tabeli katalogu Unity. Ta operacja oblicza nową migawkę Delta i dodaje nowy wpis do dziennika Delta tabeli, zapisując do docelowej ścieżki tabeli przechowywanej w chmurze.

Składnia

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 wszystkie tabele w schemacie.

  • target_schema

    Istniejący schemat w katalogu Unity, w którym użytkownik ma uprawnienia do tworzenia tabel.

  • source_schema

    Istniejący schemat w wykazie hive_metastore, który jest własnością użytkownika.

• TABLE

  SYNC pojedyncza tabela.

  • target_table

    Nowa lub istniejąca tabela w Unity Catalog w schemacie, w którym użytkownik jest upoważniony do tworzenia tabel. Jeśli tabela już istnieje, zostanie zamieniona tak, aby była zgodna z source_table, a użytkownik musi również być właścicielem tabeli. Jeśli tabela nie istnieje, zostanie utworzona.

  • source_table

    Istniejąca tabela w hive_metastore, której właścicielem jest użytkownik.

• główny

  Opcjonalnie ustaw właściciela uaktualnionych tabel w katalogu Unity na principal. Domyślnym właścicielem jest bieżący użytkownik.

• AS EXTERNAL

  SYNC tabelę zarządzaną programu Hive lub schemat przechowywany poza magazynem obszarów roboczych usługi Databricks (czasami nazywanym katalogiem głównym systemu plików DBFS) do tabel zewnętrznych w wykazie aparatu Unity. Nie można użyć AS EXTERNAL do uaktualnienia tabel zarządzanych Hive przechowywanych w pamięci przestrzeni roboczej.

• DRY RUN

  Po określeniu sprawdza, czy source_table lub tabele w source_schema można uaktualnić bez faktycznego tworzenia lub uaktualniania tabel docelowych. Polecenie zwraca DRY_RUN_SUCCESS, jeśli można uaktualnić tabelę.

• AS EXTERNAL Począwszy od środowiska Databricks Runtime 13.2 lub nowszego, tę opcjonalną klauzulę można dodać, aby określić, że zarządzane tabele w metastore Hive są uaktualniane jako tabele zewnętrzne w Unity Catalog. W przypadku użycia z SYNC SCHEMAma zastosowanie do wszystkich tabel, w tym tabel zarządzanych w source_schema.

Zwraca

Raport z następującymi kolumnami:

• source_schema STRING

  Nazwa schematu źródłowego. Schemat jest NULL, jeśli źródłem jest widok tymczasowy, który nie jest obsługiwany.

• source_name STRING NOT NULL

  Nazwa tabeli źródłowej.

• source_type STRING NOT NULL

  Typ tabeli: MANAGED lub EXTERNAL

• target_catalog STRING NOT NULL

  Docelowy katalog w Unity Catalog, w którym synchronizowana jest tabela.

• target_schema STRING NOT NULL

  Schemat docelowy w Unity Catalog, do którego synchronizowana jest tabela.

• target_name STRING NOT NULL

  Nazwa tabeli w katalogu Unity, do którego jest synchronizowana tabela źródłowa. Ta nazwa jest zgodna z nazwą tabeli źródłowej.

• status_code STRING NOT NULL

  Kod stanu dla wyniku polecenia SYNC dla tabeli źródłowej.

• description STRING

  Opisowy komunikat o stanie polecenia synchronizacji dla tabeli źródłowej.

Typowe kody stanu zwracane przez SYNC

Polecenie SYNC zapewnia unikalne pole status_code w danych wyjściowych dla każdej tabeli, która ma zostać zaktualizowana do Unity Catalog, reprezentując stan aktualizacji. Niektóre typowe kody stanu wraz z zaleceniami dotyczącymi ich rozwiązywania są następujące:

• DRY_RUN_SUCCESS: Przebieg suchy zakończył się pomyślnie.

  Tabelę można zaktualizować do Unity Catalog przy użyciu polecenia SYNC.

• DBFS_ROOT_LOCATION: tabela znajdująca się w katalogu głównym systemu plików usługi Databricks.

  Tabela znajduje się w lokalizacji głównej systemu plików usługi Databricks. Nie jest to obsługiwane w katalogu Unity. Skopiuj dane tabeli do lokalizacji Unity Catalog przy użyciu polecenia CREATE TABLE z opcją DEEP CLONE.

• EXTERNAL_TABLE_IN_MANAGED_LOCATION: Ścieżka tabeli zewnętrznej nie może znajdować się w zarządzanym magazynie danych.

  Ścieżka podana dla tabeli zewnętrznej znajduje się w katalogu unity manage storage. Jeśli tabela musi znajdować się w zarządzanym magazynie, uaktualnij ją do tabeli zarządzanej przy użyciu polecenia CREATE TABLE z opcją DEEP CLONE lub przenieś lokalizację tabeli poza zarządzany magazyn Unity Catalog.

• HIVE_SERDE: Tabela nie kwalifikuje się do uaktualnienia z Hive Metastore do Unity Catalog. Przyczyna: Tabela SerDe Hive.

  Tabele SerDe Hive nie są obsługiwane przez katalog Unity. Zmień tabele na format delta i wydaj polecenie SYNC, aby uaktualnić.

• INVALID_DATASOURCE_FORMAT: nie określono formatu źródła danych lub nie jest obsługiwany.

  Użyj jednego z obsługiwanych formatów źródła danych: Delta, Parquet, CSV, JSON, ORC, TEXT

• LOCATION_OVERLAP: ścieżka wejściowa nakłada się na inne tabele zewnętrzne.

  Lokalizacja tabeli nakłada się na inne tabele zewnętrzne. Użyj innej lokalizacji dla tabeli lub usuń nakładające się tabele zewnętrzne.

• MULTIPLE_EXT_LOCATIONS: ścieżka wejściowa zawiera inne lokalizacje zewnętrzne.

  Istnieje więcej niż jedna lokalizacja zewnętrzna, które są podkatalogami podanej ścieżki tabeli. Sprawdź, czy lokalizacje zewnętrzne w lokalizacji tabeli są niezbędne.

• MULTIPLE_TARGET_TABLE: istnieje już inna zsynchronizowana tabela. Dozwolona jest tylko jedna tabela docelowa na tabelę źródłową.

  Tabela źródłowa została już zsynchronizowana z inną tabelą docelową, która nie jest dozwolona. Aby przenieść SYNC do innej tabeli, usuń właściwość tabeli upgraded_to z tabeli źródłowej lub usuń wcześniej zsynchronizowaną tabelę z Unity Catalog, jeśli nie jest już potrzebna.

• NOT_EXTERNAL: Tabela nie kwalifikuje się do aktualizacji z Hive Metastore do Unity Catalog. Przyczyna: Nie jest to tabela zewnętrzna.

  SYNC komenda obsługuje tylko migrowanie tabel zewnętrznych do Unity Catalog. W przypadku tabel zarządzanych utwórz tabelę zarządzaną w Unity Catalog przy użyciu polecenia CREATE TABLE z opcją DEEP CLONE. Alternatywnie użyj klauzuli AS EXTERNAL z poleceniem SYNC, aby utworzyć tabelę zewnętrzną w katalogu Unity.

• READ_ONLY_CATALOG: dane w katalogu udostępniania Delta są tylko do odczytu i nie można ich modyfikować ani usuwać.

  Wybrany katalog to katalog udostępniania delta, który jest tylko do odczytu. Tabele w wykazie tylko do odczytu nie mogą być aktualizowane przy użyciu polecenia SYNC.

• SUCCESS: tabela została pomyślnie zsynchronizowana.

• TABLE_ALREADY_EXISTS: Tabela docelowa już istnieje.

  Tabela o tej samej nazwie, co wybrana tabela, już istnieje w Unity Catalogu. Zmień nazwę lub usuń istniejącą tabelę w Unity Catalog i ponownie wykonaj polecenie SYNC.

• TEMP_TABLE_NOT_SUPPORTED: Tabele tymczasowe lub widoki nie są obsługiwane.

  Nie można zaktualizować tabel tymczasowych lub widoków do Unity Catalog. Aby użyć tabel tymczasowych lub widoków, utwórz je ponownie w katalogu Unity przy użyciu polecenia SHOW CREATE TABLE.

• TIMEOUT: Upłynął limit czasu zadania synchronizacji.

  Wykonanie zadania polecenia synchronizacji trwało ponad 300 sekund. Zwiększ spark.databricks.sync.command.task.timeout wartość do wyższej w sekundach. Wartość domyślna to 300. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną.

• VIEWS_NOT_SUPPORTED: widoki nie są obsługiwane.

  Ręczne odtwarzanie widoków przy użyciu polecenia SHOW CREATE TABLE w Unity Catalog.

Przykłady

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

Powiązane artykuły

• CREATE TABLE
• CREATE VIEW
• SHOW CREATE TABLE