`SYNC`

Aplica-se a: marque sim SQL do DatabricksDatabricks Runtime somente Catálogo do Unity

Use o comando SYNC para atualizar tabelas externas no Metastore do Hive para as tabelas externas no Catálogo do Unity. Você também pode usar SYNC para atualizar tabelas gerenciadas do Hive que estão armazenadas fora do armazenamento do workspace do Databricks (às vezes chamado de raiz do DBFS) para tabelas externas no Catálogo do Unity. Você não pode usá-lo para atualizar as tabelas gerenciadas pelo Hive armazenadas no armazenamento do workspace. Para atualizar essas tabelas, use CREATE TABLE CLONE.

Você pode usar SYNC para criar novas tabelas no Catálogo do Unity a partir de tabelas existentes do Metastore do Hive, além de atualizar as tabelas do Catálogo do Unity quando as tabelas de origem no Metastore do Hive forem alteradas.

O comando SYNC pode ser executado no nível do esquema usando a sintaxe SYNC SCHEMA ou para uma tabela individual usando a sintaxe SYNC TABLE.

O comando executa uma operação de gravação (ALTER TABLE) em cada tabela de origem que ele atualiza para adicionar mais algumas propriedades de tabela para a contabilidade. No caso de tabelas Delta, para executar a operação de gravação, o cluster ou o SQL Warehouse que executa o comando precisa ter acesso de gravação no local da tabela.

No Databricks Runtime 12.2 LTS ou superior, esse comportamento pode ser desativado definindo a configuração do Spark spark.databricks.sync.command.disableSourceTableWrites para true antes de executar o SYNC comando. Quando definido como true, SYNC não adiciona novas propriedades de tabela e, portanto, talvez não detecte se a tabela foi atualizada anteriormente para o Catálogo do Unity. Nesse caso, ele depende exclusivamente do nome da tabela para determinar se a tabela foi atualizada anteriormente para o Catálogo do Unity. Se a tabela de origem tiver sido renomeada desde o último comando SYNC, o usuário precisará renomear manualmente a tabela de destino antes de executar novamente o comando SYNC quando a configuração for true.

Importante

Quando um comando SYNC é executado, a operação SET TBLPROPERTIES adiciona uma propriedade de tabela que indica a referência de tabela externa do Catálogo do Unity de destino. Essa operação calcula um novo instantâneo Delta e adiciona uma nova entrada ao log Delta da tabela, gravando no caminho da tabela de destino no armazenamento em nuvem.

Sintaxe

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

Parâmetros

SCHEMA

SYNC todas as tabelas dentro de um esquema.
- target_schema
  
  Um esquema existente no Catálogo do Unity no qual o usuário está autorizado a criar tabelas.
- esquema_fonte
  
  Um esquema existente no catálogo hive_metastore, que pertence ao usuário.
TABLE

SYNC uma tabela individual.
- tabela_destino
  
  Uma tabela nova ou existente no Catálogo do Unity em um esquema no qual o usuário está autorizado a criar tabelas. Se a tabela já existir, ela será substituída para corresponder a source_table e o usuário deverá ser proprietário da tabela. Se a tabela não existir, ela será criada.
- tabela_fonte
  
  Uma tabela existente em hive_metastore que pertence ao usuário.
principal

Opcionalmente, defina o proprietário das tabelas atualizadas no Catálogo do Unity como principal. O proprietário padrão é o usuário atual.
AS EXTERNAL

Use SYNC para atualizar esquemas ou tabelas gerenciadas do Hive que estão armazenados fora do armazenamento do workspace do Databricks (às vezes chamado de raiz do DBFS) para tabelas externas no Catálogo do Unity. Você não pode usar AS EXTERNAL para atualizar as tabelas gerenciadas pelo Hive armazenadas no armazenamento do workspace.
DRY RUN

Quando especificado, ele verifica se o source_table ou as tabelas dentro de source_schema podem ser atualizadas sem realmente criar ou atualizar as tabelas de destino. O comando retornará DRY_RUN_SUCCESS se uma tabela puder ser atualizada.
AS EXTERNAL A partir do Databricks Runtime 13.2 e versões posteriores, essa cláusula opcional pode ser adicionada para especificar que as tabelas gerenciadas no metastore do hive são atualizadas como tabelas externas no Catálogo do Unity. Quando usado com SYNC SCHEMA, ele se aplica a todas as tabelas, incluindo tabelas gerenciadas no source_schema.

Retornos

Um relatório com as seguintes colunas:

source_schema STRING

O nome do esquema de origem. O esquema será NULL se a origem for uma exibição temporária sem suporte.
source_name STRING NOT NULL

O nome da tabela de origem.
source_type STRING NOT NULL

O tipo da tabela: MANAGED ou EXTERNAL
target_catalog STRING NOT NULL

O catálogo de destino no Catálogo do Unity em que a tabela é sincronizada.
target_schema STRING NOT NULL

O esquema de destino no Catálogo do Unity em que a tabela é sincronizada.
target_name STRING NOT NULL

O nome da tabela no Catálogo do Unity ao qual a tabela de origem é sincronizada. Esse nome corresponde ao nome da tabela de origem.
status_code STRING NOT NULL

Um código de status para o resultado do comando SYNC para a tabela de origem.
description STRING

Uma mensagem descritiva sobre o status do comando de sincronização para a tabela de origem.

Códigos de status comuns retornados por `SYNC`

O comando SYNC fornece um campo status_code exclusivo na saída para cada tabela a ser atualizada para o Catálogo do Unity. Esse campo representa o status da atualização. Alguns códigos de status comuns, juntamente às recomendações para resolvê-los, são:

DRY_RUN_SUCCESS: simulação bem-sucedida.

A tabela pode ser atualizada para o Catálogo do Unity usando o comando SYNC.
DBFS_ROOT_LOCATION: tabela localizada na raiz do Sistema de Arquivos do Databricks.

A tabela está localizada no local raiz do Sistema de Arquivos do Databricks. Isso não tem suporte no Catálogo do Unity. Copie os dados da tabela para o local do Catálogo do Unity usando um comando CREATE TABLE com a opção DEEP CLONE.
EXTERNAL_TABLE_IN_MANAGED_LOCATION: o caminho da tabela externa não pode estar sob armazenamento gerenciado.

O caminho fornecido para a tabela externa está no Catálogo do Unity para gerenciar o armazenamento. Se a tabela precisar estar sob o armazenamento gerenciado, atualize a tabela como uma tabela gerenciada usando um comando CREATE TABLE com a opção DEEP CLONE ou mova o local da tabela para fora do armazenamento gerenciado do Catálogo do Unity.
HIVE_SERDE: a tabela não está qualificada para atualização do Metastore do Hive para o Catálogo do Unity. Motivo: tabela SerDe do Hive.

Não há suporte para tabelas SerDe do Hive no Catálogo do Unity. Altere as tabelas para o formato Delta e emita o comando SYNC para atualizar.
INVALID_DATASOURCE_FORMAT: formato de fonte de dados não especificado ou sem suporte.

Use um dos formatos de fonte de dados com suporte: Delta, Parquet, CSV, JSON, ORC, TEXT, AVRO
LOCATION_OVERLAP: o caminho de entrada se sobrepõe a outras tabelas externas.

O local da tabela se sobrepõe a outras tabelas externas. Use um local diferente para a tabela ou remova as tabelas externas sobrepostas.
MULTIPLE_EXT_LOCATIONS: o caminho de entrada contém outros locais externos.

Há mais de um local externo que são subdiretórios do caminho da tabela fornecido. Verifique se os locais externos dentro do local da tabela são necessários.
MULTIPLE_TARGET_TABLE: já existe uma tabela sincronizada diferente. Somente uma tabela de destino por tabela de origem é permitida.

A tabela de origem já estava sincronizada com uma tabela de destino diferente anteriormente, o que não é permitido. Para forçar o SYNC para uma tabela diferente, remova a propriedade de tabela upgraded_to da tabela de origem ou remova a tabela sincronizada anteriormente do Catálogo do Unity se ela não for mais necessária.
NOT_EXTERNAL: a tabela não está qualificada para atualização do Metastore do Hive para o Catálogo do Unity. Motivo: não é uma tabela externa.

O comando SYNC só dá suporte à migração de tabelas externas para o Catálogo do Unity. Para tabelas gerenciadas, crie uma tabela gerenciada no Catálogo do Unity usando um comando CREATE TABLE com a opção DEEP CLONE. Como alternativa, use a cláusula AS EXTERNAL com o comando SYNC para criar uma tabela externa no Catálogo do Unity.
READ_ONLY_CATALOG: os dados dentro de um catálogo de compartilhamento Delta são somente leitura e não podem ser modificados ou excluídos.

O catálogo escolhido é um catálogo de compartilhamento Delta que é somente leitura. As tabelas em um catálogo somente leitura não podem ser atualizadas usando o comando SYNC.
SUCCESS: tabela sincronizada com êxito.
TABLE_ALREADY_EXISTS: a tabela de destino já existe.

Uma tabela com o mesmo nome que a tabela escolhida já existe no Catálogo do Unity. Renomeie ou remova a tabela existente no Catálogo do Unity e execute novamente o comando SYNC.
TEMP_TABLE_NOT_SUPPORTED: não há suporte para tabelas temporárias ou exibições.

Tabelas temporárias ou exibições não podem ser atualizadas para o Catálogo do Unity. Para usar tabelas temporárias ou exibições, recrie-as no Catálogo do Unity usando o comando SHOW CREATE TABLE no Catálogo do Unity.
TIMEOUT: tempo limite da tarefa de sincronização expirado.

A tarefa de comando da tabela de sincronização levou mais de 600 segundos para ser concluída. Aumente spark.databricks.sync.command.task.timeout para um valor mais alto em segundos.

Como alternativa, uma tarefa de esquema de sincronização pode acabar, caso em que você verá um TimeoutException. Aumente spark.databricks.sync.command.task.create.timeout para um valor mais alto em segundos.

O valor padrão para ambos os sinalizadores é 600. Se o problema persistir, entre em contato com o suporte.
VIEWS_NOT_SUPPORTED: exibições não têm suporte.

Recrie as exibições manualmente usando o comando SHOW CREATE TABLE no Catálogo do Unity.

Exemplos

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

Resolução de problemas

Caracteres não ASCII em comentários de tabela não sincronizados corretamente

Ao atualizar tabelas do metastore do Hive para o Catálogo do Unity usando o SYNC comando, comentários de tabela que incluem caracteres não ASCII (como texto japonês ou chinês) podem parecer corrompidos. Por exemplo, os comentários afetados podem ser exibidos como uma série de pontos de interrogação (???) ou não renderizar no Gerenciador de Catálogos. No entanto, consultar os comentários usando DESCRIBE TABLE EXTENDED retorna os valores corretos.

Esse problema ocorre porque o metastore do Hive pode armazenar comentários usando o latin1 conjunto de caracteres por padrão, que não dá suporte a caracteres não ASCII. Quando o Catálogo do Unity recupera comentários usando SYNC, caracteres sem suporte podem ser perdidos ou corrompidos.

Para recuperar ou restaurar caracteres não ASCII em comentários após a atualização, SYNCexecute o seguinte comando na tabela afetada no Catálogo do Unity:
```
MSCK REPAIR TABLE <catalog>.<schema>.<table_name> SYNC METADATA;
```

Comentários

Esta página foi útil?

Last updated on 2025-07-16

Compartilhar via

SYNC