Trabajo con archivos en los volúmenes del Catálogo de Unity

En esta página se incluyen ejemplos para administrar archivos en volúmenes de Catálogo de Unity para varias interfaces de usuario, herramientas, bibliotecas e idiomas.

Databricks recomienda usar volúmenes para administrar todo el acceso a datos no tabulares en el almacenamiento de objetos en la nube y para almacenar archivos de compatibilidad con cargas de trabajo. Entre los ejemplos se incluyen los siguientes:

• Archivos de datos para la ingesta, como CSV, JSON y Parquet
• Archivos de texto, imagen y audio para cargas de trabajo de ciencia de datos, aprendizaje automático e inteligencia artificial
• Artefactos CSV o JSON escritos por Azure Databricks para la integración con sistemas externos
• Bibliotecas, scripts de inicialización y artefactos de compilación

Los volúmenes proporcionan rutas de acceso al estilo de la Interfaz de Sistema Operativo Portable (POSIX) que funcionan con herramientas y marcos dependientes de FUSE (sistema de archivos en espacio de usuario). Esto hace que sean ideales para marcos de aprendizaje automático y módulos de Python de código abierto que requieren acceso de estilo POSIX. Para obtener información detallada sobre los esquemas de URI, las rutas de acceso POSIX y cómo se relacionan con los volúmenes, consulte ¿Necesito proporcionar un esquema de URI para acceder a los datos?.

Métodos para administrar archivos en volúmenes

Para obtener ejemplos rápidos de cada método, consulte Trabajar con archivos en volúmenes del catálogo de Unity.

Usar el Explorador de catálogos

El Explorador de catálogos tiene opciones para tareas comunes de administración de archivos para los archivos almacenados con volúmenes de catálogo de Unity.

Para interactuar con archivos de un volumen, haga lo siguiente:

1. En el área de trabajo de Azure Databricks, haga clic en Catálogo.
2. Busque o examine el volumen con el que desea trabajar y selecciónelo.

Para más información sobre cómo crear y administrar volúmenes, consulte Creación y administración de volúmenes del catálogo de Unity.

Carga de archivos en un volumen

Puede cargar archivos de cualquier formato (estructurado, semiestructurado o no estructurado) en un volumen. Al cargar a través de la interfaz de usuario, hay un límite de tamaño de archivo de 5 GB. Sin embargo, los volúmenes admiten archivos de hasta el tamaño máximo admitido por el almacenamiento en la nube subyacente. Puede escribir archivos muy grandes mediante Spark y cargar archivos grandes mediante la API o los SDK de Azure Databricks.

Requisitos

Antes de cargar en un volumen, asegúrese de contar con lo siguiente:

• Un área de trabajo con el catálogo de Unity habilitado
• WRITE VOLUME en el volumen de destino
• USE SCHEMA en el esquema primario
• USE CATALOG en el catálogo primario

Para obtener más información, consulte Privilegios del catálogo de Unity y objetos protegibles.

Pasos para subir archivos

1. En el Explorador de catálogos, haga clic en Agregar datos>Cargar al volumen.
2. Haga clic en Examinar o colocar archivos en la zona de colocación.
3. Seleccione un volumen o directorio, o pegue una ruta de acceso de volumen.
   • Si no existe ningún volumen en el esquema de destino, cree uno.
   • También puede crear un directorio dentro del volumen de destino.

También puede acceder a la interfaz de usuario de carga de las maneras siguientes:

• En la barra lateral: Nuevo>Agregar datos>Subir archivos al volumen
• Desde un cuaderno: Archivo>Subir archivos al volumen

Pasos siguientes

Después de subir a un volumen, puede hacer lo siguiente:

• Cree una tabla administrada del catálogo de Unity a partir de los archivos. Consulte Creación de una tabla a partir de datos en un volumen.
• Uso de los archivos en las cargas de trabajo de aprendizaje automático y ciencia de datos
• Configuración de bibliotecas de clústeres, bibliotecas con ámbito de cuaderno o dependencias de trabajo mediante los archivos cargados
• Ingesta de datos para canalizaciones de ingeniería mediante Auto Loader o COPY INTO
• Procesamiento de archivos con funciones de IA , como ai_parse_document
• Configurar desencadenadores de llegada de archivos en trabajos

• Carga de documentos para su uso con AgentBricks (por ejemplo, escenarios de Knowledge Assistant)

Descargar archivos de un volumen

Para descargar archivos de un volumen, haga lo siguiente:

1. Seleccione uno o varios archivos.
2. Haga clic en Descargar para descargar estos archivos.

Eliminar los archivos de un volumen

Para eliminar archivos de un volumen, haga lo siguiente:

1. Seleccione uno o varios archivos.
2. Haga clic en Eliminar.
3. Haga clic en Eliminar para confirmar en el cuadro de diálogo que aparece.

Crear un directorio en blanco

Para crear un directorio nuevo en un volumen, haga lo siguiente:

1. En la pestaña de vista general del volumen, haga clic en Crear directorio.
2. Escriba un nombre de directorio.
3. Haga clic en Crear.

Descargar un directorio

Para descargar un directorio en un volumen, haga lo siguiente:

1. Haga clic en el Menú kebab situado a la derecha del directorio.
2. Haga clic en Descargar directorio.

El directorio se descarga como un archivo ZIP.

Eliminar directorios de un volumen

Para eliminar directorios de un volumen, haga lo siguiente:

1. Seleccione uno o varios directorios.
2. Haga clic en Eliminar.
3. Haga clic en Eliminar para confirmar en el cuadro de diálogo que aparece.

Tareas de administración de archivos de interfaz de usuario para volúmenes

Haga clic en el menú kebab junto a un nombre de archivo para realizar las siguientes acciones:

• Copiar ruta
• Descargar archivo
• Eliminar archivo
• Crear tabla

Crear una tabla a partir de datos de un volumen

Azure Databricks proporciona una IU para crear una tabla administrada de Unity Catalog a partir de un archivo, archivos o un directorio de archivos almacenados en un volumen de Unity Catalog.

Debe disponer de los permisos de CREATE TABLE en el esquema de destino y tener acceso a un almacén SQL en ejecución.

1. Seleccione uno o varios archivos o un directorio. Los archivos deben tener la misma distribución de datos.

2. Haga clic en Crear tabla. Aparece el cuadro de diálogo Crear tabla a partir de volúmenes.

3. Use el cuadro de diálogo proporcionado para revisar una vista previa de los datos y realizar las siguientes configuraciones:

   • Elija entre Crear nueva tabla o Sobrescribir tabla existente.
   • Seleccione el catálogo de destino y el esquema.
   • Especifique el nombre de la tabla.
   • (Opcional) Invalide los nombres y tipos de columnas predeterminados o u opte por excluir columnas.

   Nota:

   Haga clic en Atributos avanzados para ver opciones adicionales.

4. Haga clic en Crear tabla para crear la tabla con los atributos especificados. Al finalizar, el Explorador de catálogos muestra los detalles de la tabla.

Trabajar mediante programación con archivos en volúmenes

Leer y escribir archivos en volúmenes de todos los lenguajes y editores de áreas de trabajo admitidos con el formato siguiente:

/Volumes/catalog_name/schema_name/volume_name/path/to/files

Interactúa con archivos en volúmenes de la misma manera que interactúa con archivos en cualquier ubicación de almacenamiento de objetos en la nube. Esto significa que si actualmente administra código que usa URI en la nube, rutas de montaje de DBFS o rutas de acceso raíz de DBFS para interactuar con datos o archivos, puede actualizar el código para usar volúmenes en su lugar.

Lectura y escritura de datos en volúmenes

Use Apache Spark, pandas, Spark SQL y otras bibliotecas del sistema operativo para leer y escribir archivos de datos en volúmenes.

En los ejemplos siguientes se muestra cómo leer un archivo CSV almacenado en un volumen:

Pitón

df = spark.read.format("csv").load("/Volumes/catalog_name/schema_name/volume_name/data.csv")

display(df)

Pandas

import pandas as pd

df = pd.read_csv('/Volumes/catalog_name/schema_name/volume_name/data.csv')

display(df)

SQL

SELECT * FROM csv.`/Volumes/catalog_name/schema_name/volume_name/data.csv`

Comandos de utilidad para archivos en volúmenes

Databricks proporciona las siguientes herramientas para administrar archivos en volúmenes:

• El dbutils.fs submódulo en utilidades de Databricks. Consulte Utilidad de sistema de archivos (dbutils.fs).
• La %fs magic, que es un alias para dbutils.fs.
• La %sh magic, que permite el comando bash en volúmenes.

Para obtener un ejemplo de cómo usar estas herramientas para descargar archivos desde Internet, descomprimir archivos y mover archivos de almacenamiento en bloques efímeros a volúmenes, vea Descargar datos de Internet.

También puede usar paquetes de OSS para comandos de utilidad de archivos, como el módulo Python os, como se muestra en el ejemplo siguiente:

import os

os.mkdir('/Volumes/catalog_name/schema_name/volume_name/directory_name')

Administración de archivos en volúmenes desde herramientas externas

Databricks proporciona un conjunto de herramientas para administrar archivos en volúmenes mediante programación desde su entorno local o sistemas integrados.

Comandos SQL para archivos en volúmenes

Azure Databricks admite las siguientes palabras clave SQL para interactuar con archivos en volúmenes:

• PUT INTO
• GET
• REMOVE
• LIST

En los cuadernos de Azure Databricks y en el editor de consultas SQL, solo se admite el LIST comando . Los demás comandos SQL (PUT INTO, GETy REMOVE) están disponibles a través de los siguientes conectores y controladores de SQL de Databricks, que admiten la administración de archivos en volúmenes:

• Databricks SQL Connector para Python
• Controlador sql de Databricks para Go
• Controlador SQL de Databricks para Node.js
• Controlador JDBC de Databricks
• Controlador ODBC de Databricks

Administración de archivos en volúmenes con la CLI de Databricks

Use los subcomandos en databricks fs. Consulte el grupo de comandosfs.

Administración de archivos en volúmenes con SDK

Los siguientes SDK admiten la administración de archivos en volúmenes:

• SDK de Databricks para Python. Use los métodos disponibles en WorkspaceClient.files. Para obtener ejemplos, vea Administrar archivos en volúmenes de Unity Catalog.
• SDK de Databricks para Java. Use los métodos disponibles en WorkspaceClient.files. Para obtener ejemplos, vea Administrar archivos en volúmenes de Unity Catalog.
• SDK de Databricks para Go. Use los métodos disponibles en WorkspaceClient.files. Para obtener ejemplos, vea Administrar archivos en volúmenes de Unity Catalog.

Administración de archivos en volúmenes con la API de REST

Use la API de archivos para administrar archivos en volúmenes.

Ejemplos de la API de REST para archivos en volúmenes

En los ejemplos siguientes se usan curl y la API de REST de Databricks para realizar tareas de administración de archivos en volúmenes.

En el ejemplo siguiente se crea una carpeta vacía denominada my-folder en el volumen especificado.

curl --request PUT "https://${DATABRICKS_HOST}/api/2.0/fs/directories/Volumes/main/default/my-volume/my-folder/" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

En el ejemplo siguiente se crea un archivo denominado data.csv con los datos especificados en la ruta de acceso especificada del volumen.

curl --request PUT "https://${DATABRICKS_HOST}/api/2.0/fs/files/Volumes/main/default/my-volume/my-folder/data.csv?overwrite=true" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/octet-stream" \
--data-binary $'id,Text\n1,Hello World!'

En el ejemplo siguiente se muestra el contenido de un volumen en la ruta de acceso especificada. En este ejemplo se usa jq para dar formato al JSON del cuerpo de respuesta para facilitar la lectura.

curl --request GET "https://${DATABRICKS_HOST}/api/2.0/fs/directories/Volumes/main/default/my-volume/" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq .

En el ejemplo siguiente se muestra el contenido de una carpeta en un volumen de la ruta de acceso especificada. En este ejemplo se usa jq para dar formato al JSON del cuerpo de respuesta para facilitar la lectura.

curl --request GET "https://${DATABRICKS_HOST}/api/2.0/fs/directories/Volumes/main/default/my-volume/my-folder" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq .

En el ejemplo siguiente se imprime el contenido de un archivo en la ruta de acceso especificada de un volumen.

curl --request GET "https://${DATABRICKS_HOST}/api/2.0/fs/files/Volumes/main/default/my-volume/my-folder/data.csv" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

En el ejemplo siguiente se elimina un archivo de la ruta de acceso especificada de un volumen.

curl --request DELETE "https://${DATABRICKS_HOST}/api/2.0/fs/files/Volumes/main/default/my-volume/my-folder/data.csv" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

En el ejemplo siguiente se elimina una carpeta del volumen especificado.

curl --request DELETE "https://${DATABRICKS_HOST}/api/2.0/fs/directories/Volumes/main/default/my-volume/my-folder/" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

Limitaciones de trabajar con archivos en volúmenes

Antes de trabajar con archivos en volúmenes, tenga en cuenta las siguientes limitaciones:

• No se admiten escrituras de anexión directa o no secuenciales (aleatorias). Esto afecta a las operaciones como escribir archivos Zip y Excel. Para estas cargas de trabajo:

  1. Realizar primero las operaciones en un disco local
  2. Copia los resultados en el volumen

  Por ejemplo:

  # python
  import xlsxwriter
  from shutil import copyfile
  
  workbook = xlsxwriter.Workbook('/local_disk0/tmp/excel.xlsx')
  worksheet = workbook.add_worksheet()
  worksheet.write(0, 0, "Key")
  worksheet.write(0, 1, "Value")
  workbook.close()
  
  copyfile('/local_disk0/tmp/excel.xlsx', '/Volumes/my_catalog/my_schema/my_volume/excel.xlsx')
  

• No se admiten archivos dispersos. Para copiar archivos dispersos, use cp --sparse=never:

  $ cp sparse.file /Volumes/my_catalog/my_schema/my_volume/sparse.file
  error writing '/dbfs/sparse.file': Operation not supported
  $ cp --sparse=never sparse.file /Volumes/my_catalog/my_schema/my_volume/sparse.file