Partilhar via

SYNC

  • Artigo

Aplica-se a:marca de verificação sim Databricks SQL marca de verificação sim Databricks Runtime marca de verificação sim apenas Unity Catalog

Use o comando SYNC para atualizar tables externos no Hive Metastore para tables externos no Unity Catalog. Você também pode usar o SYNC para atualizar tables geridos pelo Hive, que estão armazenados fora do armazenamento do espaço de trabalho do Databricks (às vezes chamado de raiz DBFS), para tables externos no Unity Catalog. Não é possível usá-lo para atualizar o Hive gerenciado tables armazenado no armazenamento do espaço de trabalho. Para atualizar os tables, utilize o CREATE TABLE CLONE.

Você pode usar SYNC para criar novos tables no Unity Catalog a partir de tables existentes do Hive Metastore, bem como update o Catalogtables Unity quando os tables de origem no Hive Metastore forem modificados.

O comando SYNC pode ser executado em um nível schema usando a sintaxe SYNC SCHEMA ou para um indivíduo table usando a sintaxe SYNC TABLE.

O comando executa uma operação de gravação (ALTER TABLE) para cada fonte table que atualiza, adicionando algumas propriedades adicionais de table para efeitos de contabilidade. No caso do Delta tables, 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 table.

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 set para true, SYNC não adiciona novas propriedades table e, portanto, pode não detetar se o table foi atualizado anteriormente para Unity Catalog. Nesse caso, ele se baseia exclusivamente no nome table para determinar se o table foi atualizado anteriormente para Unity Catalog. Se o table de origem tiver sido renomeado desde o último comando SYNC, o usuário precisará renomear manualmente o table de destino antes de executar novamente o comando SYNC quando a configuração estiver true.

Importante

Quando um comando SYNC é executado, a operação SET TBLPROPERTIES adiciona uma propriedade table que indica o destino Unity Catalog referência de table externa. Esta operação calcula um novo instantâneo Delta e adiciona uma nova entrada ao log Delta table, escrevendo no caminho de destino table 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]

Parameters

  • SCHEMA

    SYNC todos os tables dentro de um schema.

    • target_schema

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

    • source_schema

      Um schema existente no hive_metastorecatalog, pertencente ao utilizador.

  • TABLE

    SYNC um indivíduo table.

    • target_table

      Um table novo ou existente no Unity Catalog em um schema dentro do qual o usuário está autorizado a criar tables. Se o table já existe, ele é substituído para corresponder source_table, e o usuário também deve possuir o table. Se o table não existir, ele será criado.

    • source_table

      Uma table existente em hive_metastore que o utilizador possui.

  • Principal

    Opcionalmente, set o proprietário do tables que foi atualizado no Unity Catalog para principal. O proprietário padrão é o usuário atual.

  • AS EXTERNAL

    SYNC um table ou schema gerenciado pelo Hive que é armazenado fora do armazenamento do espaço de trabalho Databricks (às vezes chamado de raiz DBFS) para tables externos no Unity Catalog. Não é possível usar AS EXTERNAL para atualizar tables geridos pelo Hive armazenados no espaço de trabalho.

  • DRY RUN

    Quando especificado, verifica se o source_table ou tables dentro do source_schema pode ser atualizado sem realmente criar ou atualizar o destino tables. O comando retorna DRY_RUN_SUCCESS se um table pode ser atualizado.

  • AS EXTERNAL Iniciando o Databricks Runtime 13.2 e superior, essa cláusula opcional pode ser adicionada para especificar que os tables gerenciados no metastore hive sejam atualizados como tables externos no Unity Catalog. Quando usado com SYNC SCHEMA, ele se aplica a todos os tables, incluindo tables gerenciados no source_schema.

Devoluções

Um relatório com as seguintes columns:

  • source_schema STRING

    O nome da fonte schema. O schema é NULL se a origem for uma vista temporária não suportada.

  • source_name STRING NOT NULL

    O nome da fonte table.

  • source_type STRING NOT NULL

    O tipo de table: MANAGED ou EXTERNAL

  • target_catalog STRING NOT NULL

    O catalog de destino no Unity Catalogwhere o table é sincronizado.

  • target_schema STRING NOT NULL

    O schema de destino no Unity Catalogwhere o table é sincronizado.

  • target_name STRING NOT NULL

    O nome do table no Unity Catalog com o qual o table de origem está sincronizado. Este nome corresponde ao nome de origem table.

  • status_code STRING NOT NULL

    Um código de status para o resultado do comando SYNC para o código-fonte table.

  • description STRING

    Uma mensagem descritiva sobre o estado do comando sync para a fonte table.

Códigos de status comuns retornados por SYNC

O comando SYNC fornece um campo status_code único na saída, para que cada table seja atualizado para o Unity Catalog, 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.

    O table pode ser atualizado para Unity Catalog usando o comando SYNC.

  • DBFS_ROOT_LOCATION: Table localizado na raiz do sistema de arquivos Databricks.

    O table está localizado no local raiz do sistema de arquivos Databricks. Isso não é suportado no Unity Catalog. Copie os dados table para o local do Unity Catalog usando um comando CREATE TABLE com a opção DEEP CLONE.

  • EXTERNAL_TABLE_IN_MANAGED_LOCATION: O caminho de table externo não pode estar sob armazenamento gerenciado.

    O caminho fornecido para o table externo está dentro da gestão de armazenamento do Unity Catalog. Se o table precisar estar dentro do armazenamento gerido, atualize o table como table gerido usando um comando CREATE TABLE com a opção de DEEP CLONE ou mova o local de table para fora do armazenamento gerido do Unity Catalog.

  • HIVE_SERDE: O table não é elegível para uma atualização do Hive Metastore para o Unity Catalog. Motivo: Hive SerDe Table.

    Os tables do Hive SerDe não são suportados pelo Unity Catalog. Altere o tables para o formato Delta e emita o comando SYNC 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 sobrepõe-se a outros elementos externos tables.

    A localização table sobrepõe-se a outras localizações tablesexternas. Use um local diferente para o table ou remove do tablesexterno sobreposto.

  • MULTIPLE_EXT_LOCATIONS: O caminho de entrada contém outros locais externos.

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

  • MULTIPLE_TARGET_TABLE: Já existe um table sincronizado diferente. Só é permitido um alvo table por origem table.

    O table de origem já foi sincronizado com um destino diferente table anteriormente, o que não é permitido. Para forçar o SYNC a um tablediferente, remove a propriedade tableupgraded_to do table de origem ou remove o table sincronizado anteriormente do Unity Catalog se não for mais necessário.

  • NOT_EXTERNAL: Table não é elegível para atualização do Hive Metastore para o Unity Catalog. Motivo: Não é um tableexterno.

    O comando SYNC permite apenas a migração de tables externos para o Unity Catalog. Para tablesgerenciado , crie um table gerenciado no Unity Catalog 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 um table externo no Unity Catalog.

  • READ_ONLY_CATALOG: Os dados dentro de um catalog de compartilhamento Delta são somente leitura e não podem ser modificados ou excluídos.

    O catalog escolhido é uma partilha delta catalog que é apenas de leitura. Tables dentro de um catalog de leitura apenas não pode ser atualizada usando o comando SYNC.

  • SUCCESS: Table sincronizado com êxito.

  • TABLE_ALREADY_EXISTS: O alvo table já existe.

    Uma table com o mesmo nome da table escolhida já existe em Unity Catalog. Renomeie ou remove o table existente no Unity Catalog e execute novamente o comando SYNC.

  • TEMP_TABLE_NOT_SUPPORTED: Não há suporte para tables ou views temporárias.

    Os tables ou views temporários não podem ser atualizados para o Unity Catalog. Para utilizar os tables temporários ou views, recrie-os no Unity Catalog utilizando o comando SHOW CREATE TABLE no Unity Catalog.

  • TIMEOUT: Sync tarefa expirou.

    A tarefa de comando sync 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: Views não são suportados.

    Recrie o views 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
  ------------- ----------- ----------- -------------- ------------- ----------- -----------     ---------------------------------
  ...