Trabalhar com arquivos em volumes do Catálogo Unity

Esta página tem exemplos para gerenciar arquivos em volumes do Catálogo 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 em 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 build

Os volumes fornecem caminhos no estilo POSIX (Portable Operating System Interface) que funcionam com ferramentas e estruturas dependentes do sistema de arquivos no espaço do usuário (FUSE). Isso os torna ideais para estruturas de aprendizado de máquina e módulos Python de código aberto que exigem acesso no estilo POSIX. Para obter informações detalhadas sobre esquemas de URI, caminhos POSIX e como eles se relacionam com volumes, consulte 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 Unity.

Usar o Catálogo Explorer

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

Para interagir com arquivos em um volume, faça o seguinte:

1. No seu espaço de trabalho 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 Unity.

Carregar ficheiros para um volume

Você pode carregar arquivos de qualquer formato — estruturado, semiestruturado ou não estruturado — para um volume. Quando você carrega através da interface do usuário, há um limite de tamanho de arquivo de 5 GB. No entanto, os próprios volumes suportam ficheiros até ao tamanho máximo suportado pelo armazenamento na nuvem subjacente. Você pode escrever arquivos muito grandes usando o Spark e carregar arquivos grandes usando a API ou SDKs do Azure Databricks.

Requerimentos

Antes de subir para um volume, verifique se tem o seguinte:

• Um espaço de trabalho com o Unity Catalog ativado
• WRITE VOLUME sobre o volume-alvo
• USE SCHEMA no esquema pai
• USE CATALOG no catálogo pai

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

Etapas de upload

1. No Explorador de Catálogos, clique em Adicionar dados>Carregar ao volume.
2. Clique em Procurar ou solte arquivos na área de soltar.
3. Selecione um volume ou diretório ou cole um caminho de volume.
   • Se não existir nenhum volume 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 ficheiros para o volume
• De um bloco de notas: Ficheiro>Carregar ficheiros para o volume

Próximos passos

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

• Crie uma tabela gerenciada do Unity Catalog a partir dos arquivos. Consulte Criar uma tabela a partir de dados em um volume.
• Usar os ficheiros em tarefas de aprendizagem automática e ciência de dados
• Configurar bibliotecas de cluster, bibliotecas específicas para notebook ou dependências de tarefas usando os arquivos carregados.
• Ingerir dados para tubulações de engenharia usando Auto Loader 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 utilizar com AgentBricks (por exemplo, cenários de assistente de conhecimento)

Baixar arquivos de um volume

Para baixar arquivos de um volume, faça o seguinte:

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

Excluir arquivos de um volume

Para excluir arquivos de um volume, faça o seguinte:

1. Selecione um ou mais arquivos.
2. Clique em Eliminar.
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, faça o seguinte:

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

Baixar um diretório

Para descarregar um diretório num volume, faça o seguinte:

1. Clique no Menu Kebab à direita da diretoria.
2. Clique em Descarregar diretório.

O diretório é descarregado como um ficheiro ZIP.

Excluir diretórios de um volume

Para excluir diretórios de um volume, faça o seguinte:

1. Selecione um ou mais diretórios.
2. Clique em Eliminar.
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 ao lado de um nome de ficheiro para executar as seguintes ações:

• Caminho de cópia
• Descarregar ficheiro
• Eliminar ficheiro
• Criar tabela

Criar uma tabela a partir de dados em um volume

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

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

1. Selecione um ou mais arquivos ou um diretório. Os arquivos devem ter o mesmo layout de dados.

2. Clique Criar a 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:

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

   Observação

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

4. Clique em Criar tabela para criar a tabela com os atributos especificados. Após a conclusão, o Catalog Explorer exibe os detalhes da tabela.

Trabalhar programaticamente com arquivos em volumes

Ler e gravar arquivos em volumes de todos os idiomas suportados e editores de espaço de trabalho 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ê atualmente gerencia código que usa URIs na nuvem, caminhos de montagem DBFS ou caminhos raiz DBFS para interagir com dados ou arquivos, você pode atualizar seu código para usar volumes.

Ler e gravar dados em volumes

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

Os exemplos a seguir 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 dbutils.fs submódulo em Databricks Utilities. Consulte Utilitário do sistema de arquivos (dbutils.fs).
• A %fs magia, que é um pseudônimo para dbutils.fs.
• A %sh magia, que permite comando bash contra volumes.

Para obter um exemplo de como usar essas ferramentas para baixar arquivos da Internet, descompactar arquivos e mover arquivos do armazenamento de blocos efêmeros para volumes, consulte Baixar dados da Internet.

Você também pode usar pacotes OSS para comandos do utilitário de arquivos, como o módulo Python os , conforme mostrado no exemplo a seguir:

import os

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

Gerenciar arquivos em volumes a partir de ferramentas externas

O Databricks fornece um conjunto de ferramentas para gerenciar programaticamente arquivos em volumes de seu 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 blocos de anotações do Azure Databricks e no editor de consultas SQL, apenas o LIST comando é suportado. Os outros comandos SQL (PUT INTO, GET, e REMOVE) estão disponíveis através dos seguintes conectores e drivers Databricks SQL, que suportam o gerenciamento de arquivos em volumes:

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

Gerencie arquivos em volumes com a CLI do Databricks

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

Gerencie arquivos em volumes com SDKs

Os seguintes SDKs oferecem suporte ao gerenciamento de arquivos em volumes:

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

Gerencie arquivos em volumes com a API REST

Use a API 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 nomeada 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 nomeado 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 gravações diretas ou não sequenciais (aleatórias). Isso afeta operações como escrever arquivos Zip e Excel. Para estas cargas de trabalho:

  1. Execute 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')
  

• Arquivos esparsos não são suportados. 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