Trabalhar com arquivos em volumes do Catálogo do Unity

Esta página tem exemplos para gerenciar arquivos em volumes do Catálogo do Unity para várias interfaces de usuário, ferramentas, bibliotecas e idiomas.

O Databricks recomenda o uso de volumes para gerenciar todo o acesso a dados não tabulares no armazenamento de objetos de nuvem e para armazenar arquivos de suporte de carga de trabalho. Os exemplos incluem o seguinte:

• Arquivos de dados para ingestão, como CSV, JSON e Parquet
• Arquivos de texto, imagem e áudio para cargas de trabalho de ciência de dados, ML e IA
• Artefatos CSV ou JSON escritos pelo Azure Databricks para integração com sistemas externos
• Bibliotecas, scripts de inicialização e artefatos de compilação

Os volumes fornecem caminhos no estilo POSIX (Interface do Sistema Operacional Portátil) que funcionam com ferramentas e frameworks dependentes do FUSE (Sistema de Arquivos no Espaço do Usuário). Isso os torna ideais para estruturas de machine learning e módulos python de software livre que exigem acesso ao estilo POSIX. Para obter informações detalhadas sobre esquemas de URI, caminhos POSIX e como eles se relacionam com volumes, consulte Se preciso fornecer um esquema de URI para acessar dados?.

Métodos para gerenciar arquivos em volumes

Para obter exemplos rápidos de cada método, consulte Trabalhar com arquivos em volumes do Catálogo do Unity.

Usar o Explorador de Catálogos

O Gerenciador de Catálogos tem opções para tarefas comuns de gerenciamento de arquivos para arquivos armazenados com volumes do Catálogo do Unity.

Para interagir com arquivos em um volume, realize as seguintes ações:

1. No workspace do Azure Databricks, clique no Catálogo.
2. Pesquise ou procure o volume com o qual deseja trabalhar e selecione-o.

Para obter detalhes sobre como criar e gerenciar volumes, consulte Criar e gerenciar volumes do Catálogo do Unity.

Carregar arquivos para um volume

Você pode carregar arquivos de qualquer formato, estruturados, semiestruturados ou não estruturados, em um volume. Quando você carrega pela interface do usuário, há um limite de tamanho de arquivo de 5 GB. No entanto, os próprios volumes dão suporte a arquivos até o tamanho máximo suportado pelo armazenamento em nuvem subjacente. Você pode escrever arquivos muito grandes usando o Spark e carregar arquivos grandes usando a API ou os SDKs do Azure Databricks.

Requirements

Antes de carregar em um volume, verifique se você possui o seguinte:

• Um workspace com o Catálogo do Unity habilitado
• WRITE VOLUME no volume de destino
• USE SCHEMA no esquema pai
• USE CATALOG no catálogo pai

Para obter detalhes, consulte privilégios do Catálogo do Unity e objetos protegíveis.

Etapas de upload

1. No Explorador de Catálogos, clique em Adicionar dadosCarregar para o volume.
2. Clique Procurar ou solte arquivos na área de descarte.
3. Selecione um volume ou diretório ou cole um caminho de volume.
   • Se nenhum volume existir no esquema de destino, crie um.
   • Você também pode criar um novo diretório dentro do volume de destino.

Você também pode acessar a interface do usuário de upload das seguintes maneiras:

• Na barra lateral: Novo>Adicionar dados>Carregar arquivos para o volume
• De um notebook: Arquivo>Enviar arquivos para o volume

Próximas etapas

Depois de carregar em um volume, você pode fazer o seguinte:

• Crie uma tabela gerenciada do Catálogo do Unity com base nos arquivos. Consulte Criar uma tabela com base em dados em um volume.
• Usar os arquivos em cargas de trabalho de aprendizado de máquina e ciência de dados
• Configurar bibliotecas de cluster, bibliotecas com escopo de notebook ou dependências de trabalho usando os arquivos carregados
• Ingerir dados para pipelines de engenharia usando Carregador Automático ou COPY INTO
• Processar arquivos com funções de IA , como ai_parse_document
• Configurar gatilhos de chegada de arquivo em trabalhos

• Carregar documentos para uso com o AgentBricks (por exemplo, em cenários de assistente inteligente)

Baixar arquivos de um volume

Para baixar arquivos de um volume, realize as seguintes ações:

1. Selecione um ou mais arquivos.
2. Clique em Baixar para baixar esses arquivos.

Excluir arquivos de um volume

Para excluir arquivos de um volume, realize as seguintes ações:

1. Selecione um ou mais arquivos.
2. Clique em Excluir.
3. Clique em Excluir para confirmar na caixa de diálogo exibida.

Criar um diretório em branco

Para criar um novo diretório em um volume, realize as seguintes ações:

1. Na guia visão geral do volume, clique em Criar diretório.
2. Digite um nome de diretório.
3. Clique em Criar.

Baixar um diretório

Para baixar um diretório em um volume, faça o seguinte:

1. Clique no Menu kebab à direita do diretório.
2. Clique em Baixar diretório.

O diretório é baixado como um arquivo ZIP.

Excluir diretórios de um volume

Para excluir diretórios de um volume, realize as seguintes ações:

1. Selecione um ou mais diretórios.
2. Clique em Excluir.
3. Clique em Excluir para confirmar na caixa de diálogo exibida.

Tarefas de gerenciamento de arquivos da interface do usuário para volumes

Clique no menu kebab ao lado de um nome de arquivo para realizar as ações a seguir:

• Copiar caminho
• Baixar arquivo
• Excluir arquivo
• Criar tabela

Criar uma tabela com base em dados de um volume

O Azure Databricks fornece uma interface do usuário para criar uma tabela gerenciada do Catálogo do Unity com base em um arquivo, arquivos ou diretório de arquivos armazenado em um volume do Catálogo do Unity.

Você precisa ter permissões CREATE TABLE no esquema de destino e ter acesso a um SQL warehouse em execução.

1. Selecione um ou mais arquivos, ou um diretório. É necessário que os arquivos tenham o mesmo layout de dados.

2. Clique em Criar tabela. A caixa de diálogo Criar tabela a partir de volumes é exibida.

3. Use a caixa de diálogo fornecida para revisar uma visualização dos dados e concluir as seguintes configurações:

   • Escolher Criar uma nova tabela ou Substituir uma tabela existente
   • Selecione o Catálogo e o Esquema de destino.
   • Especifique o nome da tabela.
   • (Opcional) Substitua nomes e tipos de coluna padrão ou opte por excluir colunas.

   Observação

   Clique em Atributos avançados para exibir opções adicionais.

4. Clique em Criar tabela para criar a tabela com os atributos especificados. Após a conclusão, o Gerenciador de Catálogos mostra os detalhes da tabela.

Trabalhar programaticamente com arquivos em volumes

Ler e gravar arquivos em volumes de todos os idiomas e editores de espaços de trabalho com suporte usando o seguinte formato:

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

Você interage com arquivos em volumes da mesma forma que interage com arquivos em qualquer local de armazenamento de objetos na nuvem. Isso significa que, se você gerencia atualmente códigos que usam URIs de nuvem, caminhos de montagem DBFS ou caminhos raiz do DBFS para interagir com dados ou arquivos, é possível atualizar esses códigos para usar volumes.

Ler e gravar dados em volumes

Use o Apache Spark, pandas, Spark SQL e outras bibliotecas de OSS para ler e gravar arquivos de dados em volumes.

Os seguintes exemplos demonstram a leitura de um arquivo CSV armazenado em um volume:

Python

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 utilitários para arquivos em volumes

O Databricks fornece as seguintes ferramentas para gerenciar arquivos em volumes:

• O submódulo dbutils.fs nos Utilitários do Databricks. Confira Utilitário do sistema de arquivos (dbutils.fs).
• O magic %fs, que é um alias para dbutils.fs.
• O magic %sh, que permite o uso do comando bash em volumes.

Para obter um exemplo de uso dessas ferramentas para baixar arquivos da Internet, descompactá-los e movê-los do armazenamento de blocos temporário para volumes, confira Baixar dados da Internet.

Também é possível usar pacotes de software de código aberto para comandos de utilitário de arquivo, como o módulo Python os, conforme mostrado no seguinte exemplo:

import os

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

Gerenciar arquivos em volumes com ferramentas externas

O Databricks fornece um conjunto de ferramentas para gerenciar programaticamente arquivos em volumes de ambiente local ou sistemas integrados.

Comandos SQL para arquivos em volumes

O Azure Databricks dá suporte às seguintes palavras-chave SQL para interagir com arquivos em volumes:

• PUT INTO
• GET
• REMOVE
• LIST

Nos notebooks do Azure Databricks e no editor de consultas SQL, há suporte apenas para o LIST comando. Os outros comandos SQL (PUT INTOe GETREMOVE) estão disponíveis por meio dos seguintes conectores e drivers sql do Databricks, que dão suporte ao gerenciamento de arquivos em volumes:

• Conector do Databricks SQL para Python
• Driver do SQL do Databricks para Go
• Driver do SQL do Databricks para Node.js
• Driver JDBC do Databricks
• Driver ODBC do Databricks

Gerenciar arquivos em volumes com a CLI do Databricks

Use os subcomandos em databricks fs. Consulte fs o grupo de comandos.

Gerenciar arquivos em volumes com SDKs

Os seguintes SDKs dão suporte ao gerenciamento de arquivos em volumes:

• O SDK do Databricks para Python. Use os métodos disponíveis em WorkspaceClient.files. Por exemplo, consulte Gerenciar arquivos em volumes do Catálogo do Unity.
• O SDK do Databricks para Java. Use os métodos disponíveis em WorkspaceClient.files. Por exemplo, consulte Gerenciar arquivos em volumes do Catálogo do Unity.
• O SDK do Databricks para Go. Use os métodos disponíveis em WorkspaceClient.files. Por exemplo, consulte Gerenciar arquivos em volumes do Catálogo do Unity.

Gerenciar arquivos em volumes com a API REST

Use a API de Arquivos para gerenciar arquivos em volumes.

Exemplos de API REST para arquivos em volumes

Os exemplos a seguir usam curl e a API REST do Databricks para executar tarefas de gerenciamento de arquivos em volumes.

O exemplo a seguir cria uma pasta vazia chamada my-folder no volume especificado.

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

O exemplo a seguir cria um arquivo chamado data.csv com os dados especificados no caminho especificado no volume.

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!'

O exemplo a seguir lista o conteúdo de um volume no caminho especificado. Este exemplo usa jq para formatar o JSON do corpo da resposta para facilitar a leitura.

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

O exemplo a seguir lista o conteúdo de uma pasta em um volume no caminho especificado. Este exemplo usa jq para formatar o JSON do corpo da resposta para facilitar a leitura.

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

O exemplo a seguir imprime o conteúdo de um arquivo no caminho especificado em um volume.

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}"

O exemplo a seguir exclui um arquivo no caminho especificado de um volume.

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}"

O exemplo a seguir exclui uma pasta do volume especificado.

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

Limitações de trabalhar com arquivos em volumes

Antes de trabalhar com arquivos em volumes, considere as seguintes limitações:

• Não há suporte para acréscimos diretos ou gravações não sequenciais (aleatórias). Isso afeta operações como gravar arquivos Zip e Excel. Para estas cargas de trabalho:

  1. Executar as operações em um disco local primeiro
  2. Copiar os resultados para o volume

  Por exemplo:

  # 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')
  

• Não há suporte para arquivos esparsos. Para copiar arquivos esparsos, 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