SYNC

Aplica-se a: Databricks SQL Databricks Runtime apenas Unity Catalog

Use o SYNC comando para atualizar tabelas externas no Hive Metastore para tabelas externas no Unity Catalog. Você também pode usar SYNC para converter tabelas geridas do Hive que estão armazenadas fora do espaço de trabalho Databricks (também conhecido como raiz DBFS) em tabelas externas no Unity Catalog. Não é possível usá-lo para atualizar tabelas gerenciadas do Hive armazenadas no armazenamento do espaço de trabalho. Para atualizar essas tabelas, use CREATE TABLE CLONE.

Você pode usar SYNC para criar novas tabelas no Unity Catalog a partir de tabelas existentes do Hive Metastore, bem como atualizar as tabelas do Unity Catalog quando as tabelas de origem no Hive Metastore forem modificadas.

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

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

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

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

  • target_schema

    Um esquema existente no Unity Catalog dentro do qual o usuário está autorizado a criar tabelas.

  • esquema_fonte

    Um esquema existente no hive_metastore catálogo, que é de propriedade do usuário.

• TABLE

  SYNC uma tabela individual.

  • tabela_destino

    Uma tabela nova ou existente no Unity Catalog em um esquema no qual o usuário está autorizado a criar tabelas. Se a tabela já existir, ela será substituída para corresponder source_tablee o usuário também deverá ser o proprietário da tabela. Se a tabela não existir, ela será criada.

  • tabela_fonte

    Uma tabela existente em hive_metastore que o usuário possui.

• Principal

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

• AS EXTERNAL

  SYNC uma tabela ou esquema gerido pelo Hive que está armazenada fora do armazenamento no espaço de trabalho Databricks (por vezes chamado de DBFS root) para tabelas externas no Unity Catalog. Não é possível usar AS EXTERNAL para atualizar tabelas gerenciadas do Hive armazenadas no armazenamento de espaço de trabalho.

• DRY RUN

  Quando especificado, verifica se source_table ou as tabelas dentro de source_schema podem ser atualizadas sem realmente criar ou modificar as tabelas de destino. O comando retorna DRY_RUN_SUCCESS se uma tabela puder ser atualizada.

• AS EXTERNAL Iniciando o Databricks Runtime 13.2 e superior, essa cláusula opcional pode ser adicionada para especificar que as tabelas gerenciadas no metastore hive sejam atualizadas como tabelas externas no Unity Catalog. Quando usado com SYNC SCHEMA, ele se aplica a todas as tabelas, incluindo tabelas geridas na source_schema.

Devoluções

Um relatório com as seguintes colunas:

• source_schema STRING

  O nome do esquema de origem. O esquema é 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 de tabela: MANAGED ou EXTERNAL

• target_catalog STRING NOT NULL

  O catálogo de destino no Unity Catalog onde a tabela é sincronizada.

• target_schema STRING NOT NULL

  O esquema de destino no Unity Catalog onde a tabela é sincronizada.

• target_name STRING NOT NULL

  O nome da tabela no Catálogo Unity com a qual a tabela de origem está sincronizada. Esse nome corresponde ao nome da tabela de origem.

• status_code STRING NOT NULL

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

• description STRING

  Uma mensagem descritiva sobre o status do comando sync para a tabela de origem.

Códigos de status comuns retornados por SYNC

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

• DRY_RUN_SUCCESS: Corrida a seco bem-sucedida.

  A tabela pode ser atualizada para o Unity Catalog usando o SYNC comando.

• DBFS_ROOT_LOCATION: Tabela localizada na raiz do sistema de arquivos Databricks.

  A tabela está localizada no local raiz do Sistema de Arquivos Databricks. Isso não é suportado no Unity Catalog. Copie os dados da tabela para o local do Catálogo Unity usando o 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 armazenamento gerido pelo Unity Catalog. Se a tabela precisar estar sob o armazenamento gerido, atualize a tabela como uma tabela gerida usando um CREATE TABLE comando com a DEEP CLONE opção ou mova a localização da tabela para fora do armazenamento gerido do Unity Catalog.

• HIVE_SERDE: A tabela não é qualificada para uma atualização do Hive Metastore para o Unity Catalog. Motivo: Hive SerDe Table.

  As tabelas Hive SerDe não são suportadas pelo Unity Catalog. Altere as tabelas para o formato Delta e execute o SYNC comando para atualizar.

• INVALID_DATASOURCE_FORMAT: Formato de fonte de dados não especificado ou não é suportado.

  Use um dos formatos de fonte de dados suportados: 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.

  Existem mais de um local externo que são subdiretórios do caminho fornecido para a tabela. Verifique se os locais externos dentro do local da tabela são necessários.

• MULTIPLE_TARGET_TABLE: Já existe uma tabela sincronizada diferente. Apenas uma tabela de destino por tabela de origem é permitida.

  A tabela de origem já foi sincronizada com uma tabela de destino diferente anteriormente, o que não é permitido. Para forçar a tabela SYNC para uma tabela diferente, remova a propriedade de tabela upgraded_to da tabela de origem ou remova a tabela previamente sincronizada do Unity Catalog se já não for necessária.

• NOT_EXTERNAL: A tabela não é qualificada para atualização do Hive Metastore para o Unity Catalog. Motivo: Não é uma tabela externa.

  SYNC comando suporta apenas a migração de tabelas externas para o Unity Catalog. Para tabelas gerenciadas, crie uma tabela gerenciada no Unity Catalog usando um CREATE TABLE comando com a DEEP CLONE opção. Como alternativa, use a AS EXTERNAL cláusula com o SYNC comando para criar uma tabela externa no Unity Catalog.

• 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 do tipo de compartilhamento delta que é somente leitura. As tabelas dentro de um catálogo de apenas 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 da tabela escolhida já existe no Unity Catalog. Renomeie ou remova a tabela existente no Unity Catalog e execute novamente o SYNC comando.

• TEMP_TABLE_NOT_SUPPORTED: Não há suporte para tabelas ou exibições temporárias.

  Tabelas ou exibições temporárias não podem ser atualizadas para o Catálogo Unity. Para usar tabelas ou exibições temporárias, recrie-as no Unity Catalog usando o SHOW CREATE TABLE comando no Unity Catalog.

• TIMEOUT: A tarefa de sincronização atingiu o tempo limite.

  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 exceder o limite de tempo, nesse caso, 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, contacte o suporte.

• VIEWS_NOT_SUPPORTED: As visualizações não são suportadas.

  Recrie as visualizações manualmente usando SHOW CREATE TABLE o comando no Unity Catalog.

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

Soluçã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 Unity Catalog usando o comando SYNC, os comentários da tabela que incluem caracteres não-ASCII (como texto japonês ou chinês) podem aparecer corrompidos. Por exemplo, os comentários afetados podem ser exibidos como uma série de pontos de interrogação (???) ou não serem renderizados 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 oferece suporte a caracteres não-ASCII. Quando o Unity Catalog recupera comentários usando SYNC, caracteres não suportados podem ser perdidos ou corrompidos.

  Para recuperar ou restaurar caracteres não-ASCII em comentários após a atualização com SYNC, execute o seguinte comando na tabela afetada no Unity Catalog:

  MSCK REPAIR TABLE <catalog>.<schema>.<table_name> SYNC METADATA;
  

Artigos relacionados

• CREATE TABLE
• CREATE VIEW
• SHOW CREATE TABLE