Tipo de archivo y datos no estructurados

Importante

Esta característica se encuentra en su versión beta. Los administradores del área de trabajo pueden controlar el acceso a esta característica desde la página Vistas previas . Consulte Administrar versiones preliminares de Azure Databricks.

El FILE tipo almacena una referencia gobernada a un archivo no estructurado, con metadatos como ruta y tamaño. Utiliza FILE columnas en el Catálogo de Unity para almacenar documentos, imágenes y audio junto con datos estructurados.

Con FILE MANAGED las columnas, Unity Catalog almacena copias de los archivos y las gestiona con la tabla: eliminar filas hace que los archivos referenciados sean elegibles para la recogida de basura, de modo que la tabla y sus archivos permanezcan sincronizados.

Para la referencia tipográfica, véase FILE tipo.

El siguiente diagrama muestra una FILE columna llamada video que hace referencia a los clips de conducción junto a columnas estructuradas como ruta, descripción de escena y etiqueta de peligro:

Metadatos y almacenamiento de FILE

Para cada fila, el FILE tipo almacena metadatos y un enlace regulado al archivo almacenado. Un FILE valor incluye uri, size, content_type, y checksum campos de metadatos. Las consultas de metadatos no requieren lecturas completas de archivos, lo que mejora el rendimiento de las consultas.

Puedes pasar FILE valores a funciones de IA, como ai_parse_document la función, y a funciones definidas por el usuario (UDFs).

El siguiente diagrama muestra un ejemplo de columna gestionada FILE , que contiene metadatos de ruta y tamaño y referencias a los archivos almacenados:

Acceso a metadatos y contenido

Un valor tiene dos partes, y el FILE acceso a cada una se rige de forma diferente:

• Los metadatos de archivo (uri, size, content_type, y checksum) se almacenan en los propios archivos de datos de la tabla. Cualquiera que tenga SELECT sobre la mesa puede leerlo.
• El contenido del archivo permanece almacenado. Leerlos requiere acceso al archivo: READ VOLUME sobre el volumen subyacente para FILE EXTERNAL, o acceso tanto a la tabla como al volumen que respalda el FileSpace para FILE MANAGED.

Convertir un valor FILE a BINARY o STRING, pasarlo a una función de IA o UDF y previsualizarlo en la tabla de resultados provocan la lectura del contenido de los archivos. Como los metadatos forman parte de la tabla, la ruta y el tamaño de un archivo son visibles para cualquiera que pueda consultar la tabla, incluso sin acceso al contenido.

Para previsualizar archivos en los resultados de la consulta, consulte Archivos de vista previa en columnas de ARCHIVO.

¿Por qué usar FILE en lugar de BINARY o STRING?

La siguiente tabla detalla los desafíos al manejar archivos no estructurados grandes con BINARY o STRING tipos:

Tipo de columna	Descripción	Diagrama
BINARY	Materializa el objeto completo en cada lectura, incluso cuando solo necesitas metadatos como el tamaño o la ruta del archivo. Esto resulta en cálculos innecesarios y consultas lentas.
STRING	Almacena una ruta de archivo sin metadatos, como información de tamaño o versión, y sin enlace regulado entre la tabla y el archivo. Si otra carga de trabajo elimina el archivo, la tabla tiene información obsoleta. Si eliminas una fila de tabla, el archivo referenciado permanece almacenado hasta que lo eliminas manualmente.

Sumas de comprobación

El checksum campo es un token de integridad para los bytes del archivo, de la forma <prefix>:<digest>. Úsala para comparar archivos o verificar que no haya cambiado. Los lectores ignoran una suma de comprobación con un prefijo no reconocido.

No siempre hay una suma de comprobación disponible. to_file función, create_file función y copy_file función rellenan la suma de verificación cuando el almacén de objetos devuelve un ETAG. list_files La función con valores de tabla y read_files la función con valores en tabla no completan la suma de comprobación.

El checksum campo utiliza uno de los siguientes prefijos:

Prefijo	Codificación de hash	Descripción
ETAG	Opaque	eTag de store de objetos para todo el archivo. Suministrado literalmente por la tienda, usado solo para comparación de igualdad, y no recomputable.
MD5	Hexadecimal en minúsculas	Un resumen MD5 (RFC 1321), 32 caracteres hexadecimales.
CRC32	hexadecimal en minúsculas	Suma de comprobación CRC32 (RFC 2083), 8 caracteres hexadecimales.
CRC32C	hexadecimal en minúsculas	Una suma de comprobación CRC32C (RFC 3385), 8 caracteres hexadecimales.
SHA-256	hexadecimal en minúsculas	Un resumen SHA-256 (RFC 6234), 64 caracteres hexadecimales.

Por ejemplo, una suma de comprobación MD5 tiene este aspecto: MD5:d41d8cd98f00b204e9800998ecf8427e, y un eTag de un almacén de objetos tiene este aspecto: ETAG:"686897696a7c876b7e", incluidas las comillas dobles que devuelve el almacén de objetos.

Seleccione entre FILE y BINARY

La siguiente tabla compara las opciones para trabajar con archivos no estructurados:

Tipo de columna	Values	Caso de uso
FILE	Una referencia gobernada a un archivo, más metadatos (uri, size, content_type, checksum).	Úsalos para gestionar y procesar archivos no estructurados junto con datos estructurados, y para pasar archivos a funciones integradas y de IA.
BINARY	Los bytes en bruto de un archivo, en línea en una columna.	Úsalo para objetos pequeños (hasta 64 KB por defecto) almacenados directamente en el archivo de datos. Esto es útil cuando necesitas una baja sobrecarga de metadatos y una gestión de archivos simplificada. Por ejemplo, úsalo para almacenar miniaturas en línea con los datos de fila.

ARCHIVO GESTIONADO y ARCHIVO EXTERNO

El FILE tipo soporta dos enfoques para gestionar los archivos:

• FILE MANAGED las columnas copian archivos a almacenamiento gestionado. Los permisos se simplifican y gestionan mediante la tabla. Cuando eliminas filas o las actualizas para referenciar diferentes archivos, los archivos sin referencias se vuelven elegibles para recogida de basura, por lo que la tabla y sus archivos permanecen sincronizados. Utiliza este enfoque para cargas de trabajo que acceden a archivos a través de una tabla, como entrenamiento de ML o generación aumentada por recuperación (RAG), y para archivos ingeridos de fuentes externas. Para los patrones de ingesta, véase Ingerir archivos como el tipo FILE.
• FILE EXTERNAL las columnas hacen referencia a archivos existentes en un volumen del Catálogo de Unity. Los archivos están protegidos por permisos de volumen del Catálogo de Unity, pero su ciclo de vida no es gestionado por el Catálogo de Unity y no se copian. Utiliza este enfoque cuando necesites referenciar archivos sin mover datos ni interrumpir herramientas que leen desde un volumen existente.

Azure Databricks recomienda FILE MANAGED para cargas de trabajo que se benefician de permisos a nivel de archivo y cumplimiento incorporado: el acceso a cada archivo se rige a través de la tabla que lo referencia, y eliminar filas hace que los archivos referenciados sean elegibles para la recogida de basura. Utilice FILE EXTERNAL cuando los archivos deban permanecer en sus rutas actuales del volumen para las herramientas que los leen fuera de la tabla.

Para consultas, no hay diferencia entre archivos gestionados y externos.

El siguiente diagrama muestra cómo el FILE tipo conecta tu código con archivos en almacenamiento de objetos en la nube:

FILE MANAGED

FILE MANAGED las columnas almacenan copias de archivos en un FileSpace, un volumen de Unity Catalog que declaras para que la tabla lo use como almacenamiento gestionado. Su ciclo de vida está ligado a las tablas que los referencian: eliminar filas hace que los archivos referenciados sean elegibles para recogida de basura, de modo que la tabla y sus archivos permanecen sincronizados.

Los siguientes comportamientos se aplican a FILE MANAGED:

• Declarar el FileSpace requiere la databricks.filespace-preview propiedad de la tabla.
• Leer o escribir un archivo gestionado requiere acceso tanto a la tabla como al volumen que sustenta el FileSpace.
• La recogida automática de archivos sin referencias no es compatible en la Beta.

Los archivos no estructurados almacenados en fuentes externas como SharePoint, Google Drive, OneDrive y SFTP deben importarse como archivos gestionados antes de poder utilizarlos con funciones como ai_parse_document function y funciones definidas por el usuario (UDFs). Para los patrones de ingesta, consulte Ingerir archivos como tipo FILE.

Para usar archivos gestionados, crea una tabla con una FILE MANAGED columna y declara un volumen como el FileSpace estableciendo la databricks.filespace-preview propiedad de la tabla como una ruta de volumen:

'databricks.filespace-preview' = '/Volumes/<catalog>/<schema>/<volume_name>/<optional_path>'

Para ejemplos completos, véanse los siguientes FILE MANAGED ejemplos.

ejemplos de FILE MANAGED

Para crear una tabla con una FILE MANAGED columna:

CREATE TABLE reports (id BIGINT, file FILE MANAGED)
  TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

Para añadir una FILE MANAGED columna a una tabla existente, establece la propiedad de tabla databricks.filespace-preview antes de añadir la columna, como en el siguiente código:

ALTER TABLE reports SET TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

ALTER TABLE reports ADD COLUMN attachment FILE MANAGED;

Añadir una columna FILE MANAGED a una tabla que no tiene FileSpace falla.

Eliminar archivos gestionados sin referencias

Como no se soporta la recogida automática de basura, elimina tú mismo los archivos sin referencia. El siguiente notebook encuentra los archivos en un FileSpace a los que no hace referencia ninguna versión de la tabla y, si se desea, los elimina:

Cuaderno de recolección de basura FileType

Obtención del cuaderno

FILE EXTERNAL

FILE EXTERNAL las columnas son referencias a archivos que ya existen en un volumen del Catálogo de Unity.

Si tienes los privilegios necesarios sobre el volumen, puedes actualizar o eliminar estos archivos. Databricks recomienda usar archivos inmutables. Un permiso sobre una tabla da acceso a los metadatos del archivo, pero para leer también los bytes del archivo se requiere el privilegio READ VOLUME en el volumen subyacente.

Un archivo externo asigna cada fila de tabla a un archivo en su ruta existente en un volumen del Catálogo de Unity:

ejemplos de FILE EXTERNAL

Para crear una tabla con una FILE EXTERNAL columna:

CREATE TABLE documents (id BIGINT, file FILE EXTERNAL);

Para añadir una FILE EXTERNAL columna a una tabla existente:

ALTER TABLE documents ADD COLUMN file FILE EXTERNAL;

Para crear y rellenar una tabla desde un volumen, asignando IDs únicos a cada archivo:

CREATE TABLE documents AS
  SELECT monotonically_increasing_id() AS id, file
  FROM list_files('/Volumes/samples/sec/contracts/');

Gobernanza y comparación del ciclo de vida

La siguiente tabla compara cómo FILE MANAGED y FILE EXTERNAL gobiernan el acceso a archivos y gestionan el ciclo de vida del archivo:

Tipo de columna	FILE MANAGED	FILE EXTERNAL
Control de acceso a archivos	Determinado por los permisos de la tabla y del volumen, como SELECT en la tabla y READ VOLUME en el volumen.	Regido por permisos de volumen, como READ VOLUME.
Ciclo de vida y recolección de elementos no utilizados	Los archivos están vinculados a las filas que los referencian. Eliminar esas filas hace que los archivos sean elegibles para la recogida de basura. No se soporta la recogida automática de basura.	Tú gestionas los archivos. Eliminar una fila de tabla no afecta al archivo subyacente en el volumen.

Casos de uso del tipo FILE

Tanto los tipos gestionados como externos FILE abordan los siguientes retos para casos de uso que utilizan datos no estructurados:

Desafío	Tipo soportado FILE	Benefits
Archivos demasiado grandes para almacenarlos en línea como BINARY	FILE MANAGED o FILE EXTERNAL	Una FILE columna almacena una referencia, por lo que un archivo solo se lee cuando una función de IA o un UDF lo procesa. Esto evita que los objetos grandes se materialifiquen en línea en la mesa.
Ciclo de vida y gobernanza desconectados entre el sistema de archivos y la tabla	FILE MANAGED	Azure Databricks vincula el ciclo de vida de cada archivo a la tabla, así que eliminar filas hace que los archivos sean elegibles para limpieza en lugar de dejar archivos huérfanos en almacenamiento.
Cargas de trabajo concurrentes que requieren que los archivos permanezcan en la misma ubicación	FILE EXTERNAL	Los archivos permanecen en sus rutas de volumen existentes, sin verse afectadas por el ciclo de vida de la tabla, por lo que otras herramientas que leen los mismos archivos no se ven interrumpidas.

Pasos siguientes

• FILE tipo
• Importa archivos como tipo FILE
• Tutorial: Construye una cadena de procesamiento de archivos con el tipo ARCHIVO
• ai_parse_document Función