Partager via

SYNC

S’applique à :coché Databricks SQL coché Databricks Runtime coché 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 gérées par Hive stockées en dehors de l'espace de stockage de l’espace de travail Databricks (parfois appelé racine DBFS) vers des tables externes dans Unity Catalog. En revanche, vous ne pouvez pas utiliser cette commande pour mettre à niveau des tables gérées par Hive stockées dans le stockage de l’espace 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, ainsi que pour mettre à jour les tables Unity Catalog en cas de modification des tables source du metastore Hive.

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 mise à niveau afin d'ajouter des propriétés de table supplémentaires à des fins de comptabilité. Dans le cas des tables Delta, pour effectuer l'opération d'écriture, le cluster ou l'entrepôt SQL qui exécute la commande doit avoir accès en écriture à l'emplacement de la table.

Dans Databricks Runtime 12.2 LTS et les versions ultérieures, 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. Le cas échéant, elle s'appuie exclusivement sur le nom de la table pour déterminer si celle-ci a déjà été 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 d’exécuter à nouveau la commande SYNC lorsque la configuration est true.

Importante

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 géré par Hive stocké en dehors du stockage de l'espace de travail Databricks (parfois appelé racine DBFS) vers des tables externes dans Unity Catalog. En revanche, vous ne pouvez pas utiliser AS EXTERNAL pour mettre à niveau des tables gérées par Hive stockées dans le stockage de l’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 Dans Databricks Runtime 13.2 et les versions ultérieures, cette clause facultative peut être ajoutée pour spécifier que les tables géré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 gérées dans le source_schema.

retourne :

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 de la 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 se trouve à 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 vers l’emplacement du catalogue Unity à 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 géré, mettez à niveau la table en tant que table gérée à l’aide d’une commande CREATE TABLE avec l’option DEEP CLONE ou déplacez l’emplacement de la table hors du stockage managé du catalogue Unity.

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

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

  • 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 gérées, créez une table managée dans le catalogue Unity à 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 tables ou des vues temporaires, recréez-les dans le catalogue Unity à l’aide de la commande SHOW CREATE TABLE dans le catalogue Unity.

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

    La tâche de commande de la table de synchronisation a pris plus de 600 secondes. Augmentez la valeur spark.databricks.sync.command.task.timeout en secondes.

    Une tâche de schéma de synchronisation peut également expirer, auquel cas vous verrez un TimeoutException. Augmentez la valeur spark.databricks.sync.command.task.create.timeout en secondes.

    La valeur par défaut pour les deux indicateurs est 600. Si le problème persiste, contactez le support technique.

  • 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 le Catalogue Unity.

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

Résolution des problèmes

  • Caractères non ASCII dans les commentaires de table qui ne sont pas synchronisés correctement

    Lors de la mise à niveau des tables du metastore Hive vers le catalogue Unity à l’aide de la SYNC commande, les commentaires de table qui incluent des caractères non ASCII (tels que du texte japonais ou chinois) peuvent apparaître endommagés. Par exemple, les commentaires affectés peuvent s’afficher sous la forme d’une série de points d’interrogation (???) ou ne pas être affichés dans l’Explorateur de catalogues. Toutefois, l’interrogation des commentaires à l’aide de DESCRIBE TABLE EXTENDED retourne les valeurs correctes.

    Ce problème se produit parce que le metastore Hive peut stocker des commentaires à l’aide du latin1 jeu de caractères par défaut, qui ne prend pas en charge les caractères non ASCII. Lorsque Unity Catalog récupère des commentaires à l’aide de SYNC, il se peut que des caractères non pris en charge soient perdus ou endommagés.

    Pour récupérer ou restaurer des caractères non ASCII dans les commentaires après la mise à niveau avec SYNC, exécutez la commande suivante sur la table affectée dans le catalogue Unity :

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