通过

SYNC

  • 项目

适用于：勾选“是” Databricks SQL 勾选“是” Databricks Runtime 勾选“是” 仅 Unity Catalog

使用 SYNC 命令将 Hive 元存储中的外部表升级到 Unity Catalog 中的外部表。 还可以使用 SYNC 将存储在 Databricks 工作区存储（有时称为 DBFS 根）外部的 Hive 托管表升级到 Unity Catalog 中的外部表。 无法使用此命令来升级存储在工作区存储中的 Hive 托管表。 若要升级这些表，请使用 CREATE TABLE CLONE。

可以使用 SYNC 在 Unity Catalog 中基于现有的 Hive 元存储表创建新表，并在修改 Hive 元存储中的源表时更新 Unity Catalog 表。

SYNC 命令可以使用 SYNC SCHEMA 语法在架构级别运行，也可以使用 SYNC TABLE 语法针对单个表运行。

该命令对它升级的每个源表执行写入操作 (ALTER TABLE)，以为其记帐添加一些附加表属性。 对于 Delta 表，要执行运行命令的群集或 SQL Warehouse 的写入操作，必须具有对表位置的写入访问权限。

在 Databricks Runtime 12.2 LTS 或更高版本中，可以在运行 SYNC 命令之前将 Spark 配置 spark.databricks.sync.command.disableSourceTableWrites 设置为 true 以关闭此行为。 设置为true时，SYNC不会新增表属性，因此可能无法检测到表之前是否已升级到 Unity 目录。 在这种情况下，它完全依赖于表名称以确定表是否之前已升级到 Unity 目录。 如果源表自上次 SYNC 命令以来已重命名，用户需要在配置true时在重新运行 SYNC 命令之前手动重命名目标表。

重要

执行 SYNC 命令时，SET TBLPROPERTIES 操作会添加一个表属性，该属性指示目标 Unity 目录外部表引用。 此操作将计算新的 Delta 快照，并向表 Delta 日志添加新条目，从而写入云存储中的目标表路径。

语法

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。

    • target_schema

      Unity Catalog 中的现有架构，用户有权在其中创建表。

    • source_schema

      hive_metastore 目录中的现有架构，由用户所有。

  • TABLE

    对单个表运行 SYNC。

    • target_table

      Unity Catalog 中某个架构内的新表或现有表，用户有权在该架构中创建表。 如果表已存在，则会替换该表以匹配 source_table；用户也必须拥有该表。 如果表不存在，则会创建它。

    • source_table

      用户拥有的 hive_metastore 中的现有表。

  • principal

    （可选）将在 Unity Catalog 中升级的表的所有者设置为 principal。 默认所有者为当前用户。

  • AS EXTERNAL

    使用 SYNC 将存储在 Databricks 工作区存储（有时称为 DBFS 根）外部的 Hive 托管表或架构同步到 Unity Catalog 中的外部表。 无法使用 AS EXTERNAL 来升级存储在工作区存储中的 Hive 托管表。

  • DRY RUN

    如果已指定，则会检查是否可以在不实际创建或升级目标表的情况下升级 source_table 或者 source_schema 中的表。 如果可以升级表，则该命令返回 DRY_RUN_SUCCESS。

  • AS EXTERNAL 启动 Databricks Runtime 13.2 及更高版本时，可以添加此可选子句以指定配置单元元存储中的托管表升级为 Unity Catalog 中的外部表。 与 SYNC SCHEMA 一起使用时，它适用于所有表，包括 source_schema. 中的托管表

返回

包含以下列的报告：

  • source_schema STRING

    源架构的名称。 如果源是不受支持的临时视图，则架构为 NULL。

  • source_name STRING NOT NULL

    源表的名称。

  • source_type STRING NOT NULL

    表的类型：MANAGED 或 EXTERNAL

  • target_catalog STRING NOT NULL

    Unity Catalog 中要将表同步到的目标目录。

  • target_schema STRING NOT NULL

    Unity Catalog 中要将表同步到的目标架构。

  • target_name STRING NOT NULL

    Unity Catalog 中要将源表同步到的表的名称。 此名称与源表名称匹配。

  • status_code STRING NOT NULL

    针对源表运行 SYNC 命令后的结果状态代码。

  • description STRING

    有关针对源表运行的 sync 命令状态的描述性消息。

SYNC 返回的常见状态代码

SYNC 命令在输出中针对每个要升级到 Unity Catalog 的表提供唯一的 status_code 字段用于表示升级状态。 一些常见的状态代码及其处理方法建议如下：

  • DRY_RUN_SUCCESS：试运行成功。

    可以使用 SYNC 命令将表升级到 Unity Catalog。

  • DBFS_ROOT_LOCATION：表位于 Databricks 文件系统根目录中。

    表位于 Databricks 文件系统根目录位置。 Unity Catalog 不支持此状态。 结合 DEEP CLONE 选项使用 CREATE TABLE 命令将表数据复制到 Unity Catalog 位置。

  • EXTERNAL_TABLE_IN_MANAGED_LOCATION：外部表路径不能在托管存储下。

    为外部表提供的路径在 Unity Catalog 托管存储中。 如果表需要位于托管存储下，请结合 DEEP CLONE 选项使用 CREATE TABLE 命令将表升级为托管表，或者将表位置移出 Unity Catalog 托管存储。

  • HIVE_SERDE：表不符合从 Hive 元存储升级到 Unity Catalog 的条件。 原因：Hive SerDe 表。

    Unity Catalog 不支持 Hive SerDe 表。 将表更改为 Delta 格式并发出 SYNC 命令进行升级。

  • INVALID_DATASOURCE_FORMAT：数据源格式未指定或不受支持。

    使用一种受支持的数据源格式：Delta、Parquet、CSV、JSON、ORC、TEXT

  • LOCATION_OVERLAP：输入路径与其他外部表重叠。

    表位置与其他外部表重叠。 为表使用不同的位置，或删除重叠的外部表。

  • MULTIPLE_EXT_LOCATIONS：输入路径包含其他外部位置。

    有多个外部位置是提供的表路径的子目录。 检查表位置中的外部位置是否是必要的。

  • MULTIPLE_TARGET_TABLE：已存在其他同步的表。 只允许每个源表有一个目标表。

    源表先前已同步到其他目标表，这是不允许的。 若要强制 SYNC 到其他表，请从源表中删除表属性 upgraded_to，或者从 Unity Catalog 中删除先前已同步的但不再需要的表。

  • NOT_EXTERNAL：表不符合从 Hive 元存储升级到 Unity Catalog 的条件。 原因：不是外部表。

    SYNC 命令仅支持将外部表迁移到 Unity Catalog。 对于托管表，请结合 DEEP CLONE 选项使用 CREATE TABLE 命令在 Unity Catalog 中创建托管表。 或者，将 AS EXTERNAL 子句与 SYNC 命令一起使用，以在 Unity Catalog 中创建外部表。

  • READ_ONLY_CATALOG：增量共享目录中的数据是只读的，无法修改或删除。

    所选目录是只读的增量共享目录。 无法使用 SYNC 命令更新只读目录中的表。

  • SUCCESS：表已同步成功。

  • TABLE_ALREADY_EXISTS：目标表已存在。

    Unity Catalog 中已存在与所选表同名的表。 重命名或删除 Unity Catalog 中的现有表，然后重新运行 SYNC 命令。

  • TEMP_TABLE_NOT_SUPPORTED：不支持临时表或视图。

    临时表或视图无法升级到 Unity Catalog。 若要使用临时表或视图，请在 Unity Catalog 中使用 SHOW CREATE TABLE 命令重新创建它们。

  • TIMEOUT：同步任务超时。

    完成 sync 命令任务所花费的时间超过了 300 秒。 增大 spark.databricks.sync.command.task.timeout 的值（以秒为单位）。 默认值为 300。 如果错误仍然存在，请联系支持人员。

  • VIEWS_NOT_SUPPORTED：不支持视图。

    在 Unity Catalog 中使用 SHOW CREATE TABLE 命令手动重新创建视图。

示例

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