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. Aunque también puede usar CREATE TABLE AS SELECT (CTAS) para la conversión, Databricks recomienda usar SET MANAGED para las siguientes ventajas:

  • 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. Para comprobar si la tabla tiene habilitadas las lecturas de Apache Iceberg (UniForm), consulte Comprobación de que las lecturas de Iceberg (UniForm) están habilitadas.

  • 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;

    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. Esto garantiza que el trabajo evite leer o escribir en la ubicación antigua. Para reiniciar, detenga el trabajo actual e inicie un nuevo trabajo con la misma configuración.
  • Compruebe que los lectores y escritores funcionan con la tabla administrada. Todos los lectores y escritores deben usar el acceso basado en nombres para trabajar automáticamente con la tabla administrada recién convertida. No se admite el acceso basado en rutas de acceso y puede provocar errores o daños en los datos.

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 Databricks Runtime), 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 haya 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 Databricks Runtime

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.

Al revertir una tabla convertida, los metadatos de la tabla se actualizan para que apunten a la ubicación externa original. Todas las operaciones de escritura realizadas en la localización gestionada después de la conversión se conservan. Las confirmaciones realizadas en la ubicación administrada entre la conversión y la reversión permanecen consultables en el tiempo por versión, aunque no por marca de tiempo.

Siete días después de la reversión, Azure Databricks elimina automáticamente los datos en 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 SET MANAGED comando minimiza o elimina el tiempo de inactividad en comparación con los enfoques alternativos, como el uso de DEEP CLONE. El proceso de conversión usa un enfoque de dos pasos para minimizar el tiempo de inactividad:

  1. Copia inicial de datos (sin tiempo de inactividad): durante este primer paso, los datos de tabla y el registro de transacciones delta se copian de la ubicación externa a la ubicación administrada. Los lectores y escritores siguen funcionando normalmente con la ubicación externa, sin afectar a las operaciones en curso.
  2. Cambiar a la ubicación administrada (breve tiempo de inactividad): durante este segundo paso, las confirmaciones realizadas en la ubicación externa durante el primer paso se mueven a la ubicación administrada. Además, los metadatos de la tabla se actualizan para registrar la nueva ubicación de la tabla administrada. Durante este paso, todas las operaciones de escritura en las ubicaciones externas se bloquean temporalmente (sin que sean puestas en cola ni reintentadas), lo que resulta en una interrupción para el escritor. Los lectores de Databricks Runtime 16.1 o superior incurren en un tiempo de inactividad cero, pero los lectores de Databricks Runtime 15.4 pueden experimentar 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