SYNC

  • Artikel

Gilt für: Häkchen Databricks SQL durch Häkchen mit „Ja“ markiert Databricks Runtime Häkchen gesetzt ja Nur Unity Catalog

Verwenden Sie den Befehl SYNC, um für externe Tabellen im Hive-Metastore ein Upgrade auf externe Tabellen in Unity Catalog durchzuführen. Sie können SYNC auch verwenden, um für verwaltete Hive-Tabellen, die außerhalb des (manchmal als DBFS-Stamm bezeichneten) Datenspeichers des Databricks-Arbeitsbereichs gespeichert sind, ein Upgrade auf externe Tabellen in Unity Katalog durchzuführen. Der Befehl kann jedoch nicht zum Upgraden verwalteter Hive-Tabellen verwendet werden, die im Arbeitsbereichsspeicher gespeichert sind. Verwenden Sie zum Upgraden dieser Tabellen CREATE TABLE CLONE.

Mit SYNC können Sie auf der Grundlage vorhandener Hive-Metastore-Tabellen neue Tabellen in Unity Catalog erstellen und die Unity Catalog-Tabellen aktualisieren, wenn die Quelltabellen im Hive-Metastore geändert werden.

Der SYNC-Befehl kann mithilfe der SYNC SCHEMA-Syntax auf Schemaebene oder mithilfe der SYNC TABLE-Syntax für eine einzelne Tabelle ausgeführt werden.

Der Befehl führt einen Schreibvorgang (ALTER TABLE) für jede Quelltabelle aus, die aktualisiert wird, um einige zusätzliche Tabelleneigenschaften für die Buchführung hinzuzufügen. Bei Delta-Tabellen muss zum Ausführen des Schreibvorgangs der Cluster oder SQL Warehouse, der oder das den Befehl ausführt, Schreibzugriff auf den Tabellenspeicherort haben.

In Databricks Runtime 12.2 LTS oder höher kann dieses Verhalten deaktiviert werden, indem die Spark-Konfiguration spark.databricks.sync.command.disableSourceTableWrites auf true festgelegt wird, bevor Sie den Befehl SYNC ausführen. Wenn dieser Wert auf true festgelegt ist, fügt SYNC keine neuen Tabelleneigenschaften hinzu und erkennt daher möglicherweise nicht, ob die Tabelle zuvor auf den Unity-Katalog aktualisiert wurde. In diesem Fall basiert sie ausschließlich auf dem Tabellennamen, um festzustellen, ob die Tabelle zuvor auf den Unity-Katalog aktualisiert wurde. Wenn die Quelltabelle seit dem letzten SYNC-Befehl umbenannt wurde, muss der Benutzer die Zieltabelle manuell umbenennen, bevor der SYNC-Befehl erneut ausgeführt wird, wenn die Konfiguration true ist.

Wichtig

Wenn ein SYNC-Befehl ausgeführt wird, fügt der Vorgang SET TBLPROPERTIES eine Tabelleneigenschaft hinzu, die den Externen Tabellenverweis für den Unity-Katalog angibt. Dieser Vorgang berechnet eine neue Delta-Momentaufnahme und fügt einen neuen Eintrag zum Delta-Protokoll der Tabelle hinzu, der in den Zieltabellenpfad im Cloudspeicher geschrieben wird.

Syntax

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

Parameter

  • SCHEMA

    SYNC für alle Tabellen innerhalb eines Schemas.

    • target_schema

      Ein vorhandenes Schema in Unity Catalog, in dem der Benutzer zum Erstellen von Tabellen autorisiert ist.

    • source_schema

      Ein vorhandenes Schema im hive_metastore-Katalog, dessen Besitzer der Benutzer ist.

  • TABLE

    SYNC für eine einzelne Tabelle.

    • target_table

      Eine neue oder vorhandene Tabelle in Unity Catalog in einem Schema, in dem der Benutzer zum Erstellen von Tabellen autorisiert ist. Wenn die Tabelle bereits vorhanden ist, wird sie ersetzt, um source_table zu entsprechen, und der Benutzer muss auch Besitzer der Tabelle sein. Wenn die Datei nicht vorhanden ist, wird sie erstellt.

    • source_table

      Eine vorhandene Tabelle in hive_metastore, für die der Benutzer als Besitzer fungiert.

  • principal

    Legen Sie optional den Besitzer der aktualisierten Tabellen in Unity Catalog auf principal fest. Der aktuelle Benutzer ist standardmäßig der Besitzer.

  • AS EXTERNAL

    Synchronisieren Sie mithilfe von SYNC eine verwaltete Hive-Tabelle oder ein Schema, die bzw. das außerhalb des (manchmal als DBFS-Stamm bezeichneten) Datenspeichers des Databricks-Arbeitsbereichs gespeichert ist, mit externen Tabellen in Unity Katalog. AS EXTERNAL kann nicht zum Upgraden verwalteter Hive-Tabellen verwendet werden, die im Arbeitsbereichsspeicher gespeichert sind.

  • DRY RUN

    Bei Angabe dieses Parameters wird überprüft, ob source_table oder Tabellen in source_schema aktualisiert werden können, ohne die Zieltabellen tatsächlich zu erstellen oder zu aktualisieren. Der Befehl gibt DRY_RUN_SUCCESS zurück, wenn eine Tabelle aktualisiert werden kann.

  • AS EXTERNAL In Databricks Runtime 13.2 und höher kann mit dieser optionalen Klausel angegeben werden, dass ein Upgrade der verwalteten Tabellen im Hive-Metastore auf externe Tabellen in Unity Catalog durchgeführt wird. Bei Verwendung mit SYNC SCHEMA gilt sie für alle Tabellen, einschließlich verwalteter Tabellen in source_schema.

Gibt zurück

Ein Bericht mit den folgenden Spalten:

  • source_schema STRING

    Der Name des Quellschemas. Das Schema lautet NULL, wenn die Quelle eine nicht unterstützte temporäre Sicht ist.

  • source_name STRING NOT NULL

    Der Name der Quelltabelle.

  • source_type STRING NOT NULL

    Der Typ der Tabelle: MANAGED oder EXTERNAL

  • target_catalog STRING NOT NULL

    Der Zielkatalog in Unity Catalog, in dem die Tabelle synchronisiert wird.

  • target_schema STRING NOT NULL

    Das Zielschema in Unity Catalog, in dem die Tabelle synchronisiert wird.

  • target_name STRING NOT NULL

    Der Name der Tabelle in Unity Catalog, mit der die Quelltabelle synchronisiert wird. Dieser Name entspricht dem Namen der Quelltabelle.

  • status_code STRING NOT NULL

    Ein Statuscode für das Ergebnis des SYNC-Befehls für die Quelltabelle.

  • description STRING

    Eine beschreibende Meldung zum Status des Synchronisierungsbefehls für die Quelltabelle.

Gängige Statuscodes, die von SYNC zurückgegeben werden

Der SYNC-Befehl gibt ein eindeutiges status_code-Feld in der Ausgabe für jede Tabelle an, die auf Unity Catalog aktualisiert werden soll. Das Feld gibt den Status des Upgrades an. Nachfolgend finden Sie einige gängige Statuscodes sowie Empfehlungen zu deren Behebung:

  • DRY_RUN_SUCCESS: Erfolgreicher Probelauf.

    Die Tabelle kann mithilfe des Befehls SYNC auf Unity Catalog aktualisiert werden.

  • DBFS_ROOT_LOCATION: Tabelle im Databricks-Dateisystemstamm.

    Die Tabelle befindet sich im Stammverzeichnis des Databricks-Dateisystems. Dies wird in Unity Catalog nicht unterstützt. Kopieren Sie die Tabellendaten mithilfe eines CREATE TABLE-Befehls mit der Option DEEP CLONE an den Unity Catalog-Speicherort.

  • EXTERNAL_TABLE_IN_MANAGED_LOCATION: Der externe Tabellenpfad kann nicht im verwalteten Speicher gespeichert werden.

    Der für die externe Tabelle angegebene Pfad befindet sich innerhalb des verwalteten Unity Catalog-Speichers. Wenn sich die Tabelle im verwalteten Speicher befinden muss, aktualisieren Sie die Tabelle mithilfe eines CREATE TABLE-Befehls mit der Option DEEP CLONE als verwaltete Tabelle, oder verschieben Sie den Tabellenspeicherort aus dem verwalteten Unity Catalog-Speicher.

  • HIVE_SERDE: Die Tabelle ist nicht zum Upgrade von Hive-Metastore auf Unity Catalog berechtigt. Grund: Hive SerDe-Tabelle

    Hive SerDe-Tabellen werden von Unity Catalog nicht unterstützt. Ändern Sie die Tabellen in das Delta-Format, und führen Sie zum Upgrade den Befehl SYNC aus.

  • INVALID_DATASOURCE_FORMAT: Das Datenquellenformat wurde nicht angegeben oder wird nicht unterstützt.

    Verwenden Sie eines der unterstützten Datenquellenformate: Delta, Parquet, CSV, JSON, ORC, TEXT

  • LOCATION_OVERLAP: Der Eingabepfad überschneidet sich mit anderen externen Tabellen.

    Der Tabellenspeicherort überschneidet sich mit anderen externen Tabellen. Verwenden Sie einen anderen Speicherort für die Tabelle, oder entfernen Sie die sich überlappenden externen Tabellen.

  • MULTIPLE_EXT_LOCATIONS: Der Eingabepfad enthält weitere externe Speicherorte.

    Es gibt mehrere externe Speicherorte, die Unterverzeichnisse des angegebenen Tabellenpfads sind. Überprüfen Sie, ob die externen Speicherorte innerhalb des Tabellenspeicherorts erforderlich sind.

  • MULTIPLE_TARGET_TABLE: Es ist bereits eine andere synchronisierte Tabelle vorhanden. Pro Quelltabelle ist nur eine Zieltabelle zulässig.

    Die Quelltabelle wurde bereits mit einer anderen Zieltabelle synchronisiert, was nicht zulässig ist. Um SYNC für eine andere Tabelle zu erzwingen, entfernen Sie die Tabelleneigenschaft upgraded_to aus der Quelltabelle, oder entfernen Sie die zuvor synchronisierte Tabelle aus Unity Catalog, wenn sie nicht mehr benötigt wird.

  • NOT_EXTERNAL: Die Tabelle ist nicht zum Upgrade von Hive-Metastore auf Unity Catalog berechtigt. Grund: Keine externe Tabelle

    Der Befehl SYNC unterstützt nur die Migration externer Tabellen zu Unity Catalog. Erstellen Sie für verwaltete Tabellen mithilfe eines CREATE TABLE-Befehls mit der Option DEEP CLONE eine verwaltete Tabelle in Unity Catalog. Alternativ können Sie die AS EXTERNAL-Klausel mit dem SYNC-Befehl verwenden, um eine externe Tabelle in Unity Catalog zu erstellen.

  • READ_ONLY_CATALOG: Daten in einem Delta Sharing-Katalog sind schreibgeschützt und können nicht geändert oder gelöscht werden.

    Der ausgewählte Katalog ist ein Delta Sharing-Katalog, der schreibgeschützt ist. Tabellen in einem schreibgeschützten Katalog können nicht mithilfe des SYNC-Befehls aktualisiert werden.

  • SUCCESS: Tabelle wurde erfolgreich synchronisiert.

  • TABLE_ALREADY_EXISTS: Zieltabelle ist bereits vorhanden.

    Eine Tabelle mit demselben Namen wie die ausgewählte Tabelle ist in Unity Catalog bereits vorhanden. Benennen Sie die vorhandene Tabelle in Unity Catalog um, oder entfernen Sie sie, und führen Sie den Befehl SYNC erneut aus.

  • TEMP_TABLE_NOT_SUPPORTED: Globale temporäre Tabellen oder Sichten werden nicht unterstützt.

    Temporäre Tabellen oder Sichten können nicht auf Unity Catalog aktualisiert werden. Wenn Sie temporäre Tabellen oder Sichten verwenden möchten, erstellen Sie sie in Unity Catalog mit dem Befehl SHOW CREATE TABLE in Unity Catalog neu.

  • TIMEOUT: Timeout für Synchronisierungsaufgabe.

    Die Ausführung des Synchronisierungsbefehls dauerte mehr als 300 Sekunden. Legen Sie für spark.databricks.sync.command.task.timeout einen höheren Wert (in Sekunden) fest. Der Standardwert ist 300. Wenden Sie sich an den Support, wenn der Fehler weiterhin auftritt.

  • VIEWS_NOT_SUPPORTED: Sichten werden nicht unterstützt.

    Erstellen Sie die Sichten manuell mithilfe des Befehls SHOW CREATE TABLE in Unity Catalog neu.

Beispiele

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