Compartir a través de

SYNC

  • Artículo

Se aplica a: casilla marcada como Sí Databricks SQL casilla marcada como Sí Databricks Runtime casilla marcada como Sí solo Unity Catalog

Use el comando SYNC para actualizar tablas externas del metastore de Hive a tablas externas de Unity Catalog. También puede usar SYNC para actualizar tablas administradas de Hive que se almacenan fuera del almacenamiento del área de trabajo de Databricks (a veces denominada raíz de DBFS) a tablas externas de Unity Catalog. No se puede usar para actualizar las tablas administradas de Hive guardadas en el almacenamiento del área de trabajo. Para actualizar esas tablas, use CREATE TABLE CLONE.

Puede usar SYNC para crear nuevas tablas en Unity Catalog a partir de tablas existentes en el metastore de Hive, así como para actualizar las tablas de Unity Catalog cuando se modifiquen las tablas de orígenes en el metastore de Hive.

El comando SYNC se puede ejecutar en un nivel de esquema mediante la sintaxis SYNC SCHEMA o para una tabla individual mediante la sintaxis SYNC TABLE.

El comando realiza una operación de escritura (ALTER TABLE) en cada tabla de origen que actualiza para agregar algunas propiedades de tabla adicionales para su contabilidad. En el caso de las tablas Delta, para realizar la operación de escritura, el clúster o el almacén de SQL que ejecuta el comando debe tener acceso de escritura a la ubicación de la tabla.

En Databricks Runtime 12.2 LTS o superior, este comportamiento se puede desactivar estableciendo la configuración de Spark spark.databricks.sync.command.disableSourceTableWrites en true antes de ejecutar el comando SYNC. Cuando se establece en true, SYNC no agrega nuevas propiedades de tabla y, por tanto, es posible que no detecte si la tabla se ha actualizado previamente al catálogo de Unity. En ese caso, se basa exclusivamente en el nombre de la tabla para determinar si la tabla se ha actualizado previamente al catálogo de Unity. Si se ha cambiado el nombre de la tabla de origen desde el último comando SYNC, el usuario debe cambiar manualmente el nombre de la tabla de destino antes de volver a ejecutar el comando SYNC cuando la configuración es true.

Importante

Cuando se ejecuta un comando SYNC, la operación SET TBLPROPERTIES agrega una propiedad de tabla que indica la referencia de tabla externa del catálogo de Unity de destino. Esta operación calcula una nueva instantánea Delta y agrega una nueva entrada al registro Delta de la tabla, escribiendo en la ruta de acceso de la tabla de destino en el almacenamiento en la nube.

Sintaxis

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 las tablas de un esquema.

    • target_schema

      Un esquema existente en Unity Catalog en el que el usuario está autorizado para crear tablas.

    • source_schema

      Un esquema existente en el catálogo de hive_metastore, cuyo propietario es el usuario.

  • TABLE

    SYNC una sola tabla.

    • target_table

      Una tabla nueva o existente en Unity Catalog en un esquema en el que el usuario está autorizado para crear tablas. Si la tabla ya existe, se reemplaza para que coincida con source_table y el usuario también debe ser propietario de la tabla. Si la tabla no existe, se creará.

    • source_table

      Una tabla existente en hive_metastore cuyo propietario es el usuario.

  • principal

    Opcionalmente, establezca el propietario de las tablas actualizadas de Unity Catalog en principal. El propietario predeterminado es el usuario actual.

  • AS EXTERNAL

    SYNC una tabla o esquema administrados de Hive que se almacena fuera del almacenamiento del área de trabajo de Databricks (a veces denominada raíz de DBFS) en tablas externas de Unity Catalog. No se puede usar AS EXTERNAL para actualizar las tablas administradas de Hive guardadas en el almacenamiento del área de trabajo.

  • DRY RUN

    Cuando se especifica, comprueba si source_table o las tablas de source_schema se pueden actualizar sin crear o actualizar realmente las tablas de destino. El comando devuelve DRY_RUN_SUCCESS si se puede actualizar una tabla.

  • AS EXTERNAL Iniciar Databricks Runtime 13.2 y versiones posteriores, esta cláusula opcional se puede agregar para especificar que las tablas administradas en el metastore de Hive se actualizan como tablas externas en el catálogo de Unity. Cuando se usa con SYNC SCHEMA, se aplica a todas las tablas, incluidas las tablas administradas en el source_schema.

Devoluciones

Un informe con las columnas siguientes:

  • source_schema STRING

    El nombre del esquema de origen. El esquema es NULL si el origen es una vista temporal no admitida.

  • source_name STRING NOT NULL

    El nombre de la tabla de origen.

  • source_type STRING NOT NULL

    El tipo de la tabla: MANAGED o EXTERNAL

  • target_catalog STRING NOT NULL

    El catálogo de destino de Unity Catalog donde se sincroniza la tabla.

  • target_schema STRING NOT NULL

    El esquema de destino de Unity Catalog donde se sincroniza la tabla.

  • target_name STRING NOT NULL

    El nombre de la tabla de Unity Catalog con el que se sincroniza la tabla de origen. Este nombre coincide con el nombre de la tabla de origen.

  • status_code STRING NOT NULL

    Un código de estado para el resultado del comando SYNC para la tabla de origen.

  • description STRING

    Un mensaje descriptivo sobre el estado del comando sync para la tabla de origen.

Códigos de estado comunes devueltos por SYNC

El comando SYNC proporciona un campo status_code único en la salida para cada tabla que se va a actualizar a Unity Catalog, que representa el estado de la actualización. Algunos códigos de estado comunes junto con las recomendaciones para abordarlos son:

  • DRY_RUN_SUCCESS: simulacro correcto.

    La tabla se puede actualizar a Unity Catalog mediante el comando SYNC.

  • DBFS_ROOT_LOCATION: tabla ubicada en la raíz del sistema de archivos de Databricks.

    La tabla se encuentra en la ubicación raíz del sistema de archivos de Databricks. No se admite en Unity Catalog. Copie los datos de la tabla en la ubicación de Unity Catalog mediante un comando CREATE TABLE con la opción DEEP CLONE.

  • EXTERNAL_TABLE_IN_MANAGED_LOCATION: la ruta de acceso de la tabla externa no puede estar en el almacenamiento administrado.

    La ruta de acceso proporcionada para la tabla externa está en el almacenamiento administrado de Unity Catalog. Si la tabla debe estar en el almacenamiento administrado, actualice la tabla como tabla administrada mediante un comando CREATE TABLE con la opción DEEP CLONE o mueva la ubicación de la tabla fuera del almacenamiento administrado de Unity Catalog.

  • HIVE_SERDE: la tabla no es apta para una actualización desde el metastore de Hive a Unity Catalog. Motivo: tabla SerDe de Hive.

    Unity Catalog no admite tablas SerDe de Hive. Cambie las tablas al formato Delta y emita el comando SYNC para realizar la actualización.

  • INVALID_DATASOURCE_FORMAT: el formato del origen de datos no se especifica o no se admite.

    Use uno de los formatos del origen de datos admitidos: Delta, Parquet, CSV, JSON, ORC, TEXT

  • LOCATION_OVERLAP: la ruta de acceso de entrada se superpone con otras tablas externas.

    La ubicación de la tabla se superpone con otras tablas externas. Use otra ubicación para la tabla o quite las tablas externas superpuestas.

  • MULTIPLE_EXT_LOCATIONS: la ruta de acceso de entrada contiene otras ubicaciones externas.

    Hay más de una ubicación externa que son subdirectorios de la ruta de acceso de la tabla proporcionada. Compruebe si las ubicaciones externas dentro de la ubicación de la tabla son necesarias.

  • MULTIPLE_TARGET_TABLE: ya existe una tabla sincronizada diferente. Solo se permite una tabla de destino por tabla de origen.

    La tabla de origen ya se sincronizó con otra tabla de destino anteriormente que no está permitida. Para forzar SYNC con una tabla diferente, quite la propiedad de tabla upgraded_to de la tabla de origen o quite la tabla sincronizada previamente de Unity Catalog si ya no es necesaria.

  • NOT_EXTERNAL: la tabla no es apta para la actualización desde el metastore de Hive a Unity Catalog. Motivo: no es una tabla externa.

    El comando SYNC solo admite la migración de tablas externas a Unity Catalog. En el caso de las tablas administradas, cree una tabla administrada en Unity Catalog mediante un comando CREATE TABLE con la opción DEEP CLONE. Como alternativa, use la cláusula AS EXTERNAL con el comando SYNC para crear una tabla externa en el catálogo de Unity.

  • READ_ONLY_CATALOG: los datos dentro de un catálogo de Delta Sharing son de solo lectura y no se pueden modificar ni eliminar.

    El catálogo elegido es un catálogo de Delta Sharing que es de solo lectura. Las tablas de un catálogo de solo lectura no se pueden actualizar mediante el comando SYNC.

  • SUCCESS: la tabla se ha sincronizado correctamente.

  • TABLE_ALREADY_EXISTS: la tabla de destino ya existe.

    Una tabla con el mismo nombre que la tabla elegida ya existe en Unity Catalog. Cambie el nombre o quite la tabla existente en Unity Catalog y vuelva a ejecutar el comando SYNC.

  • TEMP_TABLE_NOT_SUPPORTED: no se admiten tablas ni vistas temporales.

    No se pueden actualizar tablas ni vistas temporales a Unity Catalog. Para usar tablas o vistas temporales, vuelva a crearlas en Unity Catalog mediante el comando SHOW CREATE TABLE en Unity Catalog.

  • TIMEOUT: se agotó el tiempo de espera de la tarea de sincronización.

    La tarea del comando sync tardó más de 300 segundos en completarse. Aumente spark.databricks.sync.command.task.timeout a un valor mayor en segundos. El valor predeterminado es 300. Si el error persiste, póngase en contacto con soporte técnico.

  • VIEWS_NOT_SUPPORTED: no se admiten las vistas.

    Vuelva a crear las vistas manualmente mediante el comando SHOW CREATE TABLE en Unity Catalog.

Ejemplos

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