Compartir vía

Conversión de una tabla externa en una tabla de catálogo de Unity administrada

En esta página se describe el uso del ALTER TABLE ... SET MANAGED comando para convertir una tabla externa en una tabla administrada de Unity Catalog en Azure Databricks.

Información general de SET MANAGED

Use la SET MANAGED característica para convertir una tabla externa en una tabla administrada de Unity Catalog en Azure Databricks. SET MANAGED ofrece las ventajas siguientes:

  • Minimizar el tiempo de inactividad del lector y del escritor.
  • Control de escrituras simultáneas durante la conversión.
  • Conservar el historial de tablas.
  • Mantener las mismas configuraciones de tabla, incluidos el mismo nombre, configuración, permisos y vistas.
  • Capacidad de revertir una tabla administrada convertida a una tabla externa.

Prerequisites

Para usar la característica de conversión de tablas, debe cumplir los siguientes requisitos previos:

  • Todos los lectores y escritores de las tablas externas deben usar el acceso basado en nombres. Por ejemplo:

    SELECT * FROM catalog_name.schema_name.table_name;

    No se admite el acceso basado en rutas y puede fallar después de convertir la tabla.

  • Debe usar Databricks Runtime 17.0 o superior o computación sin servidor para usar SET MANAGED o UNSET MANAGED.

  • Para convertir las tablas de Catálogo de Unity con lecturas de Iceberg (UniForm) ya habilitadas, debe usar Databricks Runtime 17.2 o superior, o un proceso sin servidor, para poder utilizar TRUNCATE UNIFORM HISTORY.

  • Los lectores y escritores de Azure Databricks deben usar Databricks Runtime 15.4 LTS o superior. Si los lectores o escritores usan 14.3 LTS o versiones posteriores, consulte Opción alternativa para lectores y escritores en Databricks Runtime 14.3 LTS o versiones posteriores.

  • El SET MANAGED comando produce un DELTA_TRUNCATED_TRANSACTION_LOG error si la tabla tiene minReaderVersion=2, minWriterVersion=7y tableFeatures={..., columnMapping}. Puede comprobar si la tabla tiene estas propiedades mediante DESCRIBE DETAIL.

  • Los clientes externos (que no son de Databricks) deben admitir lecturas en tablas administradas de Unity Catalog. Véase Lectura de tablas con clientes Delta.

    • Use el panel de Access Insights para ver si los lectores y escritores que acceden a las tablas son Databricks Runtime o externos que no son de Databricks.

Important

Para evitar conflictos, cancele los trabajos de comando existentes OPTIMIZE (agrupación en clústeres líquidos, compactación, ZORDER) que funcionen en la tabla y no programe ningún trabajo mientras convierte las tablas externas en tablas administradas.

Conversión de una tabla externa a administrada

Important

El SET MANAGED comando está disponible en Databricks Runtime 17.0 o superior y proceso sin servidor.

El TRUNCATE UNIFORM HISTORY comando está disponible en Databricks Runtime 17.2 o superior y proceso sin servidor.

Ejecute uno de los siguientes comandos para convertir la tabla externa del Unity Catalog en una tabla administrada del Unity Catalog.

  • En el caso de las tablas externas del catálogo de Unity sin lecturas de Apache Iceberg habilitadas.

    ALTER TABLE catalog.schema.my_external_table SET MANAGED;

    Después de la conversión, puede habilitar las lecturas de Iceberg en la tabla administrada sin problemas de compatibilidad.

  • En el caso de las tablas externas del catálogo de Unity con las lecturas de Iceberg (UniForm) ya habilitadas:

    ALTER TABLE catalog.schema.my_external_table SET MANAGED TRUNCATE UNIFORM HISTORY;

    En este caso, incluya TRUNCATE UNIFORM HISTORY para mantener un rendimiento y compatibilidad óptimos de las tablas. TRUNCATE UNIFORM HISTORY trunca solo el historial de UniForm Iceberg y no quita el historial Delta. Este comando resulta en un breve período de inactividad de lectura y escritura para Iceberg después de truncar.

Si el comando se interrumpe durante la copia de datos, puede reiniciarlo y continuará desde donde dejó.

Warning

Databricks recomienda no ejecutar varios SET MANAGED comandos simultáneamente en la misma tabla, lo que puede provocar un estado de tabla incoherente.

Después de la conversión de tablas, deberá:

  • Reinicie los trabajos de streaming (lectura o escritura) usando la tabla externa.
  • Asegúrese de que los lectores y escritores trabajen con la tabla administrada.

La optimización predictiva se habilita automáticamente, excepto si la deshabilita manualmente. Consulte Comprobación de si la optimización predictiva está habilitada.

Con la optimización predictiva habilitada, Azure Databricks elimina automáticamente los datos en la ubicación externa del catálogo de Unity después de 14 días. Si la optimización predictiva está deshabilitada, puede ejecutarse VACUUM (requiere Databricks Runtime 17.0 o posterior o un proceso sin servidor) en la tabla administrada recién convertida después de 14 días.

VACUUM my_converted_table

Note

En algunos casos, es posible que los datos de la ubicación externa del catálogo de Unity no se eliminen después de 14 días, incluso con la optimización predictiva habilitada. Por ejemplo, si la tabla administrada del catálogo de Unity no se usa con frecuencia o es muy pequeña, es posible que no se produzca la eliminación automática. En estos casos, después de 14 días, ejecute VACUUM manualmente (requiere Databricks Runtime 17.0 o posterior o un proceso sin servidor) en la tabla administrada recién convertida para quitar los datos antiguos.

Azure Databricks elimina solo los datos de la ubicación externa. El registro de transacciones delta y la referencia a la tabla del catálogo de Unity se conservan.

Comprobación de la conversión

Puede confirmar que la tabla externa se ha convertido en una tabla administrada:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Compruebe la salida de este comando para confirmar que la tabla se ha convertido. La tabla Type debe mostrarse como MANAGED.

Si está viendo la información de la tabla en el Explorador de catálogos, actualice la página. En la pestaña Detalles , en Acerca de esta tabla, el tipo de tabla debe mostrarse como MANAGED.

Opción alternativa para lectores y escritores en Databricks Runtime 14.3 LTS o inferior

Databricks recomienda actualizar todos los drivers de lectura y escritura a Databricks Runtime 15.4 LTS o versiones posteriores para aprovechar el comando `SET MANAGED`, incluida la capacidad de conservar el historial de tablas.

Todavía puede usar el SET MANAGED comando si tiene lectores o escritores con Databricks Runtime 14.3 o versiones inferiores. Sin embargo, después de convertir una tabla en una tabla administrada, no se puede retroceder a confirmaciones históricas por marca de tiempo. Solo puedes hacerlo por versión. Si se revierte a una tabla externa en la ventana de 14 días, se reactivará la capacidad de retroceder en el tiempo hacia confirmaciones históricas realizadas antes de la conversión.

En todos los casos (independientemente de la versión de DBR), la reversión a UC externa por marca de tiempo no funciona para las confirmaciones realizadas en la tabla administrada de UC convertida, entre cuando había terminado de convertir y antes de intentar revertir.

Escribir en una tabla después de la conversión con Databricks Runtime 15.4 LTS o inferior requiere eliminar la funcionalidad inCommitTimestamp:

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Solución de problemas de errores de conversión

En esta sección se describen problemas comunes al convertir tablas externas en tablas administradas por el catálogo de Unity y cómo resolverlas.

Coherencia de la versión de DBR

Evite ejecutar o reintentar la conversión de la misma tabla mediante diferentes versiones de Databricks Runtime. Los metadatos se pueden serializar de forma diferente entre versiones, lo que provoca un VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED error. Si se produce un error en la conversión, vuelva a intentarlo siempre con la misma versión de Databricks Runtime.

Apagado del clúster durante la conversión

Si el clúster se cierra durante la conversión, es posible que se produzca un error en el comando con DELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERROR. Vuelva a intentar el comando para reanudar la conversión.

Tabla externa dañada

Si la tabla externa ya está dañada (por ejemplo, el estado de tabla no válido), la conversión podría producir errores como DELTA_TRUNCATED_TRANSACTION_LOG, DELTA_TXN_LOG_FAILED_INTEGRITYo DELTA_STATE_RECOVER_ERRORS. Antes de intentar la conversión, asegúrese de que puede ejecutar operaciones básicas en la tabla externa, como DESCRIBE DETAIL.

Revertir a una tabla externa

Important

El UNSET MANAGED comando está disponible en Databricks Runtime 17.0 o superior y proceso sin servidor.

Después de convertir una tabla externa en una tabla administrada, puede revertirla en un plazo de 14 días.

Si revierte, las confirmaciones realizadas en la ubicación externa entre la conversión y la reversión son desplazables por versión, pero no por marca de tiempo. Siete días después de la reversión, se eliminarán los datos de la ubicación administrada.

Para revertir a una tabla externa, ejecute el siguiente comando:

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED

Si se interrumpe el comando de reversión, puede volver a ejecutarlo para volver a intentarlo, similar al SET comando MANAGED.

Comprobación de la reversión

Puede confirmar que la conversión se ha revertido:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Compruebe la salida de este comando para confirmar que la tabla se ha revertido. La tabla Type debe mostrarse como EXTERNAL.

Si está viendo la información de la tabla en el Explorador de catálogos, actualice la página. En la pestaña Detalles , en Acerca de esta tabla, el tipo de tabla debe mostrarse como EXTERNAL.

También debe reiniciar los trabajos de streaming después de revertir a una tabla externa, de forma similar a la conversión.

Tiempos de inactividad y copia de datos

El tiempo de inactividad puede ocurrir cuando quienes leen o escriben acceden a una tabla durante la conversión. Sin embargo, en comparación con el comando "DEEP CLONE", el SET MANAGED comando minimiza o elimina el tiempo de inactividad de los lectores y escritores. Los lectores de Databricks Runtime 16.1 o versiones posteriores no experimentan tiempo de inactividad. Los lectores y escritores no se ven afectados durante el primer paso, cuando se copian los datos de la tabla y el registro delta.

Durante el segundo paso, las operaciones de escritura en la ubicación externa del Catálogo de Unity se bloquean, y los commits realizados en la ubicación externa durante la primera copia de datos se trasladarán. Este segundo paso de copia de datos incurrirá en tiempo de inactividad para escritores y lectores en Databricks Runtime 15.4 LTS o versiones posteriores.

Después de esto, los lectores y escritores se trasladan a la ubicación administrada del Catálogo de Unity, y la nueva ubicación de la tabla administrada se registra en el Catálogo de Unity. Los lectores con Databricks Runtime 16.1 o versiones posteriores experimentarán un equivalente de ningún tiempo de inactividad.

El tiempo de inactividad estimado es:

Tamaño de la tabla Tamaño de clúster recomendado Hora de copia de datos Tiempo de inactividad del lector y del escritor
100 GB o menos 32 núcleos/ DBSQL pequeño ~6 minutos o menos ~1-2min o menos
1 TB (terabyte) Medio de 64 núcleos o DBSQL ~30 minutos ~1-2min
10 TB 256 núcleos/ DBSQL x-large ~1,5 horas ~1-5min

Las estimaciones suponen una velocidad de rendimiento de 0,5-2 GB/núcleo de CPU/minuto.

Note

El tiempo de inactividad puede variar. El rendimiento de la conversión depende de factores como el tamaño del archivo, el número de archivos y el número de confirmaciones.

Limitaciones conocidas

La conversión externa a tablas administradas tiene las siguientes limitaciones:

  • Clientes de streaming: debe reiniciar los trabajos de streaming después de la conversión.

  • Restricciones de historial de tablas después de la reversión: para lectores o escritores en Databricks Runtime 15.4 LTS o posterior, el historial de tablas para confirmaciones realizadas después de la conversión, pero antes de la reversión será desplazable por versión, pero no por marca de tiempo.

  • Limitaciones de uso compartido de Delta: el SET MANAGED comando no es totalmente compatible con Delta Sharing. Aunque Delta Sharing abierto funciona según lo previsto, el uso compartido de Databricks a Databricks no actualiza automáticamente la ubicación administrada de la tabla de destinatarios. El destinatario continúa leyendo desde la ubicación antigua hasta que se vuelva a compartir la tabla. Para volver a compartir la tabla:

    ALTER SHARE <share_name> REMOVE TABLE <table_name>;
ALTER SHARE <share_name> ADD TABLE <table_name> AS <table_share_name> WITH HISTORY;

  • Varias regiones de nube: si la ubicación administrada predeterminada del metastore, el catálogo o el esquema del catálogo de Unity se encuentra en una región de nube diferente de la ubicación de almacenamiento de la tabla externa que se está convirtiendo, puede incurrir en costos adicionales de transferencia de datos entre regiones. El proveedor de nube impone estos cargos fuera del control de Databricks.

    Para comprobar las ubicaciones del esquema, el catálogo y el metastore, puede usar los siguientes comandos:

    DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;

DESC CATALOG EXTENDED <catalog_name>;

SELECT * FROM system.information_schema.metastores;
  • Last updated on