SYNC

  • Artigo

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

Use o SYNC comando para atualizar tabelas externas no Hive Metastore para tabelas externas no Unity Catalog. Você também pode usar SYNC para atualizar tabelas gerenciadas do Hive que são armazenadas fora do armazenamento do espaço de trabalho Databricks (às vezes chamado de raiz DBFS) para 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 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 SYNC comando é executado, a SET TBLPROPERTIES operação adiciona uma propriedade table que indica a referência de tabela externa do Unity Catalog de destino. Esta 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 Unity Catalog dentro do qual o usuário está autorizado a criar tabelas.

    • source_schema

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

  • TABLE

    SYNC uma tabela individual.

    • target_table

      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.

    • source_table

      Uma tabela existente na hive_metastore qual o usuário é proprietário.

  • 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 gerenciado pelo Hive que é armazenado fora do armazenamento do espaço de trabalho Databricks (às vezes chamado de raiz DBFS) 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 as source_table tabelas ou dentro source_schema podem ser atualizadas sem realmente criar ou atualizar 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 SCHEMAo , ele se aplica a todas as tabelas, incluindo tabelas gerenciadas 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 um comando CREATE TABLE com a DEEP CLONE opção.

  • 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á dentro do armazenamento de gerenciamento do Unity Catalog. Se a tabela precisar estar sob o armazenamento gerenciado, atualize a tabela como uma tabela gerenciada usando um comando CREATE TABLE com a DEEP CLONE opção ou mova o local da tabela para fora do armazenamento gerenciado 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

  • 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 fornecida. 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 SYNC tabela para uma tabela diferente, remova a propriedade upgraded_to table da tabela de origem ou remova a tabela sincronizada anteriormente do Unity Catalog se ela não for mais necessária.

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

    SYNC suporta apenas a migração de tabelas externas para o Unity Catalog. Para tabelas gerenciadas, crie uma tabela gerenciada no Unity Catalog usando um comando CREATE TABLE 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 de compartilhamento delta que é somente leitura. As tabelas dentro de um catálogo somente leitura não podem ser atualizadas usando o SYNC comando.

  • 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 comando SHOW CREATE TABLE no Unity Catalog.

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

    A tarefa de comando de sincronização levou mais de 300 segundos para ser concluída. Aumente spark.databricks.sync.command.task.timeout para um valor mais alto em segundos. O valor padrão é 300. Se o erro persistir, entre em contato com o suporte.

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

    Recrie as exibições manualmente usando o comando SHOW CREATE TABLE 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
  ------------- ----------- ----------- -------------- ------------- ----------- -----------     ---------------------------------
  ...