Compartir vía

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

En esta página se describe cómo convertir una tabla externa en una tabla administrada del catálogo de Unity en Azure Databricks mediante el comando o el ALTER TABLE ... SET MANAGED Explorador de catálogos.

SET MANAGED información general

Use SET MANAGED para convertir una tabla externa en una tabla administrada de Unity Catalog. Aunque también puede usar CREATE TABLE AS SELECT (CTAS) para la conversión, Databricks recomienda SET MANAGED debido a las siguientes ventajas:

  • Minimiza el tiempo de inactividad del lector y del escritor.
  • Controla las escrituras simultáneas durante la conversión.
  • Conserva el historial de tablas.
  • Mantiene las mismas configuraciones de tabla, incluidos el nombre, la configuración, los permisos y las vistas.
  • Admite revertir una tabla gestionada convertida a una tabla externa.

Prerequisites

  • 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 utilizar SET MANAGED o UNSET MANAGED.

  • Para convertir las tablas de Unity Catalog con lecturas de Iceberg (UniForm) ya habilitadas, debe usar Databricks Runtime 17.2 o posterior o computación sin servidor para usar 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

La conversión externa a tablas administradas mediante el Explorador de catálogos está en Beta.

Explorador de catálogos

Al convertir mediante el Explorador de catálogos, el acceso basado en nombres se usa automáticamente. Puede convertir una o varias tablas externas en un esquema a la vez.

  1. Vaya a la tabla o esquema que desea convertir en el Explorador de catálogos.

  2. En Acerca de esta tabla (página de detalles de tabla) o Acerca de este esquema (página de detalles del esquema), haga clic en Explorar optimizaciones.

  3. En el cuadro de diálogo ¿Por qué migrar a tablas administradas por el catálogo de Unity? , haga clic en Continuar.

    Cuadro de diálogo ¿Por qué migrar a tablas administradas del catálogo de Unity con el botón Continuar?

  4. Seleccione las tablas externas que desea convertir. Si abrió el cuadro de diálogo desde una página de detalles de tabla, la tabla está seleccionada previamente. Use la barra de búsqueda para buscar tablas adicionales. Las tablas administradas no se pueden seleccionar.

    Pantalla de selección de tabla que muestra una tabla externa seleccionada previamente y una tabla administrada no disponible

  5. Haga clic en Crear cuaderno de conversión.

  6. Opcionalmente, escriba un nombre para el cuaderno. De forma predeterminada, el cuaderno se guarda en la carpeta principal. Haga clic en Examinar para guardarlo en otra ubicación.

    El diálogo para crear un cuaderno de conversión que muestra el campo de nombre y la opción Examinar

  7. En el cuaderno, revise los procedimientos recomendados y compruebe que cumple todos los requisitos previos.

  8. Ejecute la celda de "Consultas ADMINISTRADAS".

Una vez que se ejecuta la celda, el tipo de tabla se muestra como ADMINISTRADO en lugar de EXTERNAL en el Explorador de catálogos. Actualice la página si el estado no se actualiza inmediatamente.

SQL

En función de si la tabla externa tiene habilitadas las lecturas de Apache Iceberg (UniForm), ejecute uno de los siguientes comandos. Consulte Comprobación de que las lecturas de Iceberg (UniForm) están habilitadas para comprobar si la tabla tiene habilitadas las lecturas de Apache Iceberg (UniForm).

  • 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 lecturas de Apache 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 de 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, reinícielo y continúa desde donde se dejó.

Warning

Databricks recomienda evitar 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) mediante la tabla externa para evitar la lectura o escritura en la ubicación anterior. Detenga el trabajo actual e inicie un nuevo trabajo con la misma configuración.
  • Compruebe que los lectores y escritores trabajan con la tabla administrada.

La optimización predictiva se habilita automáticamente después de la conversión a menos que la deshabilite 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, ejecute VACUUM (requiere Databricks Runtime 17.0 o posterior o 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 no se usa con frecuencia o es muy pequeña. En estos casos, ejecute VACUUM manualmente después de 14 días para quitar los datos anteriores.

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

Explorador de catálogos

Actualice la página. En la pestaña Detalles , en Acerca de esta tabla, el tipo de tabla se muestra como Administrado.

SQL

Ejecute el siguiente comando para confirmar que la tabla externa se ha convertido en una tabla administrada:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

La tabla Type se muestra como MANAGED.

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

Databricks recomienda actualizar todos los lectores y escritores a Databricks Runtime 15.4 LTS o versiones posteriores para aprovechar SET MANAGED, incluida la capacidad de conservar el historial de tablas.

Todavía puede usar SET MANAGED si tiene lectores o escritores en Databricks Runtime 14.3 o inferior. Sin embargo, después de convertir en una tabla administrada, no se puede viajar a confirmaciones históricas por marca de tiempo, solo por versión. Si retrocede a una tabla externa dentro de la ventana de 14 días, el viaje temporal a confirmaciones históricas realizadas antes se vuelve a habilitar.

En todos los casos, restablecer una tabla externa del Catálogo de Unity por fecha y hora no funciona para las confirmaciones realizadas en la tabla convertida administrada por el Catálogo de Unity entre la conversión y el restablecimiento.

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.

Desactivación 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, no es un estado de tabla 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, compruebe que puede ejecutar operaciones básicas en la tabla externa, como DESCRIBE DETAIL.

Error de validación de archivos

El SET MANAGED comando valida que todos los archivos de la instantánea más reciente de la tabla se copian en la nueva ubicación de la tabla administrada. Si faltan archivos, se produce un DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED error en el comando.

Para solucionar este problema:

  1. Compruebe los registros del controlador de Spark para identificar qué archivos no se pudieron migrar.
  2. Compruebe que estos archivos existen en la ubicación de la tabla externa de origen y que son accesibles.
  3. Vuelva a intentar el ALTER TABLE ... SET MANAGED comando.

Si el problema persiste, póngase en contacto con el soporte técnico de Databricks.

Revertir a una tabla externa

Important

El UNSET MANAGED comando requiere Databricks Runtime 17.0 o posterior o 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, 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, vuelva a ejecutarlo para volver a intentarlo.

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

Comprobación de la reversión

Ejecute el siguiente comando para confirmar que la conversión se ha revertido:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

La tabla Type se muestra como EXTERNAL.

Si está viendo 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 se muestra como EXTERNAL.

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 DEEP CLONE. El proceso de conversión usa un enfoque de dos pasos:

  1. Copia inicial de datos (sin tiempo de inactividad): Los datos de la 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 sin afectar a las operaciones en curso.
  2. Cambiar a la ubicación administrada (breve tiempo de inactividad): Las confirmaciones realizadas en la ubicación externa durante el primer paso se mueven a la ubicación administrada y los metadatos de la tabla se actualizan para registrar la nueva ubicación administrada. Durante este paso, todas las escrituras en la ubicación externa se bloquean temporalmente, resultando en tiempo de inactividad para el escritor. Los lectores de Databricks Runtime 16.1 o superior no experimentan tiempo de inactividad; Los lectores de Databricks Runtime 15.4 pueden experimentar tiempo de inactividad.

Tiempo de inactividad estimado:

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 Almacén SQL de 32 núcleos / X-Grande ~6 min o menos ~1-2 min o menos
1 TB (terabyte) 64 núcleos/ 2X-Large SQL Warehouse ~30 minutos ~1-2 min
10 TB 256 núcleos / almacén de datos SQL 4X-Large ~1,5 horas ~1-5 minutos

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

Note

El tiempo de inactividad puede variar en función de factores como el tamaño del archivo, el número de archivos y el número de confirmaciones.

Limitaciones conocidas

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

  • Restricciones del historial de tablas después de la reversión: Historial de tablas para confirmaciones realizadas después de la conversión, pero antes de la reversión es desplazable por versión, pero no por marca de tiempo.

  • Limitaciones de uso compartido delta: El SET MANAGED comando no es totalmente compatible con Delta Sharing. Open Delta Sharing funciona según lo previsto, pero compartir Databricks a Databricks no actualiza automáticamente la ubicación gestionada 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 de Unity Catalog se encuentra en una región de nube diferente de la ubicación de almacenamiento de la tabla externa, 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:

    DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;

DESC CATALOG EXTENDED <catalog_name>;

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