Partager via

SYNC

  • Article

S’applique à : coche pour oui Databricks SQL coche marquée oui Databricks Runtime case marquée oui Unity Catalog uniquement

Utilisez la commande SYNC pour mettre à niveau des tables externes dans le metastore Hive vers des tables externes dans Unity Catalog. Vous pouvez également utiliser SYNC pour mettre à niveau des tables managées Hive stockées en dehors du stockage des espaces de travail Databricks (parfois appelé racine DBFS) vers des tables externes dans Unity Catalog. Vous ne pouvez pas l’utiliser pour mettre à niveau des tables managées Hive stockées dans le stockage des espaces de travail. Pour mettre à niveau ces tables, utilisez CREATE TABLE CLONE.

Vous pouvez utiliser SYNC pour créer des tables dans Unity Catalog à partir de tables existantes du metastore Hive et mettre à jour les tables Unity Catalog quand les tables source dans le metastore Hive sont modifiées.

La commande SYNC peut être exécutée au niveau du schéma à l’aide de la syntaxe SYNC SCHEMA ou pour une table individuelle à l’aide de la syntaxe SYNC TABLE.

La commande effectue une opération d’écriture (ALTER TABLE) sur chaque table source qu’elle met à niveau pour ajouter des propriétés de table supplémentaires pour sa comptabilité. En cas de tables Delta, pour effectuer l’opération d’écriture, le cluster ou SQL Warehouse qui exécute la commande doit avoir un accès en écriture à l’emplacement de la table.

Dans Databricks Runtime 12.2 LTS ou version ultérieure, ce comportement peut être désactivé en définissant la configuration Spark spark.databricks.sync.command.disableSourceTableWrites sur true avant d’exécuter la commande SYNC. Lorsqu’elle est définie sur true, SYNC n’ajoute pas de nouvelles propriétés de table et peut donc ne pas détecter si la table a été précédemment mise à niveau vers le catalogue Unity. Dans ce cas, il s’appuie exclusivement sur le nom de la table pour déterminer si la table a été précédemment mise à niveau vers le catalogue Unity. Si la table source a été renommée depuis la dernière commande SYNC, l’utilisateur doit renommer manuellement la table de destination avant de réexécuter la commande SYNC lorsque la configuration est true.

Important

Lorsqu’une commande SYNC est exécutée, l’opération SET TBLPROPERTIES ajoute une propriété de table qui indique la référence de table externe de Unity Catalog cible. Cette opération calcule un nouvel instantané Delta et ajoute une nouvelle entrée au journal Delta de la table, en écrivant dans le chemin de la table cible du stockage cloud.

Syntaxe

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

Paramètres

  • SCHEMA

    SYNC toutes les tables d’un schéma.

    • target_schema

      Schéma existant dans Unity Catalog dans lequel l’utilisateur est autorisé à créer des tables.

    • source_schema

      Schéma existant dans le catalogue hive_metastore dont l’utilisateur est propriétaire.

  • TABLE

    SYNC une table individuelle.

    • target_table

      Table nouvelle ou existante dans Unity Catalog, dans un schéma dans lequel l’utilisateur est autorisé à créer des tables. Si la table existe déjà, elle est remplacée pour correspondre à source_table. L’utilisateur doit également être propriétaire de la table. Si la table n’existe pas, elle est créée.

    • source_table

      Table existante dans hive_metastore dont l’utilisateur est propriétaire.

  • principal

    Définissez éventuellement le propriétaire des tables mises à niveau dans Unity Catalog sur principal. Le propriétaire par défaut est l’utilisateur actuel.

  • AS EXTERNAL

    SYNC une table ou un schéma managé Hive stocké en dehors du stockage des espaces de travail Databricks (parfois appelé racine DBFS) avec des tables externes dans Unity Catalog. Vous ne pouvez pas utiliser AS EXTERNAL pour mettre à niveau des tables managées Hive stockées dans un espace de travail.

  • DRY RUN

    Si cette option est spécifiée, elle vérifie si source_table ou les tables dans source_schema peuvent être mises à niveau sans créer ni mettre à niveau les tables cible. La commande retourne DRY_RUN_SUCCESS si une table peut être mise à niveau.

  • AS EXTERNAL À compter de Databricks Runtime 13.2 et ultérieur, cette clause facultative peut être ajoutée pour spécifier que les tables managées dans le metastore Hive sont mises à niveau en tant que tables externes dans Unity Catalog. Lorsqu’elle est utilisée avec SYNC SCHEMA, elle s’applique à toutes les tables, y compris les tables managées dans le source_schema.

Retours

Rapport contenant les colonnes suivantes :

  • source_schema STRING

    Nom du schéma source. Le schéma est NULL si la source est une vue temporaire non prise en charge.

  • source_name STRING NOT NULL

    Nom de la table source.

  • source_type STRING NOT NULL

    Type de table : MANAGED ou EXTERNAL

  • target_catalog STRING NOT NULL

    Catalogue cible dans Unity Catalog où la table est synchronisée.

  • target_schema STRING NOT NULL

    Schéma cible dans Unity Catalog où la table est synchronisée.

  • target_name STRING NOT NULL

    Nom de la table dans Unity Catalog avec laquelle la table source est synchronisée. Ce nom correspond au nom de la table source.

  • status_code STRING NOT NULL

    Code d’état pour le résultat de la commande SYNC pour la table source.

  • description STRING

    Message descriptif concernant l’état de la commande de synchronisation pour la table source.

Codes d’état courants retournés par SYNC

La commande SYNC fournit un champ unique status_code dans la sortie pour chaque table à mettre à niveau vers Unity Catalog qui représente l’état de la mise à niveau. Voici certains codes d’état courants, ainsi que les recommandations pour les traiter :

  • DRY_RUN_SUCCESS : test « Dry run » réussi.

    La table peut être mise à niveau vers Unity Catalog à l’aide de la commande SYNC.

  • DBFS_ROOT_LOCATION : table située à la racine du système de fichiers Databricks.

    La table est située à l’emplacement racine du système de fichiers Databricks. Cela n’est pas pris en charge dans Unity Catalog. Copiez les données de la table à l’emplacement Unity Catalog à l’aide d’une commande CREATE TABLE avec l’option DEEP CLONE.

  • EXTERNAL_TABLE_IN_MANAGED_LOCATION : le chemin d’accès à la table externe ne peut pas être sous le stockage managé.

    Le chemin d’accès à la table externe indiqué se trouve dans le stockage managé Unity Catalog. Si la table doit se trouver sous le stockage managé, mettez à niveau la table en tant que table managée à l’aide d’une commande CREATE TABLE avec l’option DEEP CLONE ou déplacez l’emplacement de la table pour le sortir du stockage managé Unity Catalog.

  • HIVE_SERDE : la table n’est pas éligible pour une mise à niveau du metastore Hive vers Unity Catalog. Raison : table Hive SerDe.

    Les tables Hive SerDe ne sont pas prises en charge par Unity Catalog. Modifiez les tables en les convertissant au format Delta et émettez la commande SYNC pour effectuer la mise à niveau.

  • INVALID_DATASOURCE_FORMAT : le format de source de données n’est pas spécifié ou il n’est pas pris en charge.

    Utiliser l’un des formats de source de données pris en charge : Delta, Parquet, CSV, JSON, ORC, TEXT

  • LOCATION_OVERLAP : le chemin d’entrée chevauche d’autres tables externes.

    L’emplacement de la table chevauche d’autres tables externes. Utilisez un autre emplacement pour la table ou supprimez les tables externes qui présentent un chevauchement.

  • MULTIPLE_EXT_LOCATIONS : le chemin d’entrée contient d’autres emplacements externes.

    Plusieurs emplacements externes sont des sous-répertoires du chemin d’accès à la table fourni. Vérifiez si les emplacements externes dans l’emplacement de la table sont nécessaires.

  • MULTIPLE_TARGET_TABLE : une autre table synchronisée existe déjà. Une seule table cible est autorisée par table source.

    La table source a déjà été synchronisée avec une autre table cible précédemment, ce qui n’est pas autorisé. Pour forcer SYNC sur une autre table, supprimez la propriété de table upgraded_to de la table source ou supprimez la table synchronisée précédemment de Unity Catalog si celle-ci n’est plus nécessaire.

  • NOT_EXTERNAL : la table n’est pas éligible pour une mise à niveau du metastore Hive vers Unity Catalog. Raison : table non externe.

    La commande SYNC prend uniquement en charge la migration de tables externes vers Unity Catalog. Pour les tables managées, créez une table managée dans Unity Catalog à l’aide d’une commande CREATE TABLE avec l’option DEEP CLONE. Vous pouvez également utiliser la clause AS EXTERNAL avec la commande SYNC pour créer une table externe dans Unity Catalog.

  • READ_ONLY_CATALOG : les données d’un catalogue Delta Sharing sont en lecture seule. Elles ne peuvent pas être modifiées ni supprimées.

    Le catalogue choisi est un catalogue Delta Sharing en lecture seule. Les tables qui se trouvent dans un catalogue en lecture seule ne peuvent pas être mises à jour à l’aide de la commande SYNC.

  • SUCCESS : table synchronisée avec succès.

  • TABLE_ALREADY_EXISTS : la table cible existe déjà.

    Une table portant le même nom que celle choisie existe déjà dans Unity Catalog. Renommez ou supprimez la table existante dans Unity Catalog et réexécutez la commande SYNC.

  • TEMP_TABLE_NOT_SUPPORTED : les vues ou tables temporaires ne sont pas prises en charge.

    Les vues ou tables temporaires ne peuvent pas être mises à niveau vers Unity Catalog. Pour utiliser des vues ou tables temporaires, recréez-les dans Unity Catalog à l’aide de la commande SHOW CREATE TABLE dans Unity Catalog.

  • TIMEOUT : la tâche de synchronisation a expiré.

    La tâche de commande de synchronisation a duré plus de 300 secondes. Augmentez la valeur spark.databricks.sync.command.task.timeout en secondes. La valeur par défaut est 300. Si l’erreur persiste, contactez le support.

  • VIEWS_NOT_SUPPORTED : les vues ne sont pas prises en charge.

    Recréez les vues manuellement à l’aide de la commande SHOW CREATE TABLE dans Unity Catalog.

Exemples

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