Trabalhar com ficheiros no Azure Databricks

O Azure Databricks fornece vários utilitários e APIs para interagir com arquivos nos seguintes locais:

• Volumes do catálogo Unity
• Arquivos de espaço de trabalho
• Armazenamento de objetos na cloud
• Montagens DBFS e raiz DBFS
• Armazenamento efêmero conectado ao nó do driver do cluster

Este artigo fornece exemplos de interação com arquivos nesses locais para as seguintes ferramentas:

• Apache Spark
• Spark SQL e Databricks SQL
• Utitlities do sistema de arquivos Databricks (dbutils.fs ou %fs)
• CLI do Databricks
• API REST do Databricks
• Comandos shell Bash (%sh)
• A biblioteca com escopo de bloco de anotações é instalada usando %pip
• Pandas
• Utilitários de processamento e gerenciamento de arquivos OSS Python

Importante

As operações de arquivo que exigem acesso FUSE aos dados não podem acessar diretamente o armazenamento de objetos na nuvem usando URIs. O Databricks recomenda o uso de volumes do Unity Catalog para configurar o acesso a esses locais para o FUSE.

O Scala não suporta FUSE para volumes do Catálogo Unity ou arquivos de espaço de trabalho em computação configurada com modo de acesso de usuário único ou clusters sem Catálogo Unity. O Scala suporta volumes FUSE for Unity Catalog e arquivos de espaço de trabalho em computação configurada com Unity Catalog e modo de acesso compartilhado.

Preciso fornecer um esquema de URI para acessar dados?

Os caminhos de acesso a dados no Azure Databricks seguem um dos seguintes padrões:

• Os caminhos no estilo URI incluem um esquema de URI. Para soluções de acesso a dados nativas do Databricks, os esquemas de URI são opcionais para a maioria dos casos de uso. Ao acessar diretamente os dados no armazenamento de objetos na nuvem, você deve fornecer o esquema de URI correto para o tipo de armazenamento.

  

• Os caminhos no estilo POSIX fornecem acesso a dados relativos à raiz do driver (/). Os caminhos no estilo POSIX nunca exigem um esquema. Você pode usar volumes do Unity Catalog ou montagens DBFS para fornecer acesso no estilo POSIX aos dados no armazenamento de objetos na nuvem. Muitas estruturas de ML e outros módulos OSS Python requerem FUSE e só podem usar caminhos no estilo POSIX.

  

Trabalhar com arquivos em volumes do Catálogo Unity

O Databricks recomenda o uso de volumes do Catálogo Unity para configurar o acesso a arquivos de dados não tabulares armazenados no armazenamento de objetos na nuvem. Consulte Criar e trabalhar com volumes.

Ferramenta	Exemplo
Apache Spark	spark.read.format("json").load("/Volumes/my_catalog/my_schema/my_volume/data.json").show()
Spark SQL e Databricks SQL	SELECT * FROM csv.`/Volumes/my_catalog/my_schema/my_volume/data.csv`; LIST '/Volumes/my_catalog/my_schema/my_volume/';
Utilitários do sistema de arquivos Databricks	dbutils.fs.ls("/Volumes/my_catalog/my_schema/my_volume/") %fs ls /Volumes/my_catalog/my_schema/my_volume/
CLI do Databricks	databricks fs cp /path/to/local/file dbfs:/Volumes/my_catalog/my_schema/my_volume/
API REST do Databricks	POST https://<databricks-instance>/api/2.1/jobs/create {"name": "A multitask job", "tasks": [{..."libraries": [{"jar": "/Volumes/dev/environment/libraries/logging/Logging.jar"}],},...]}
Comandos shell Bash	%sh curl http://<address>/text.zip -o /Volumes/my_catalog/my_schema/my_volume/tmp/text.zip
Instalações da biblioteca	%pip install /Volumes/my_catalog/my_schema/my_volume/my_library.whl
Pandas	df = pd.read_csv('/Volumes/my_catalog/my_schema/my_volume/data.csv')
OSS Python	os.listdir('/Volumes/my_catalog/my_schema/my_volume/path/to/directory')

Nota

O dbfs:/ esquema é necessário ao trabalhar com a CLI do Databricks.

Limitações de volumes

Os volumes têm as seguintes limitações:

• Não há suporte para gravações diretas ou não sequenciais (aleatórias), como a gravação de arquivos Zip e Excel. Para cargas de trabalho de acréscimo direto ou gravação aleatória, execute as operações em um disco local primeiro e, em seguida, copie os resultados para os volumes do Catálogo Unity. 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
  

Trabalhar com arquivos de espaço de trabalho

Os arquivos de espaço de trabalho Databricks são o conjunto de arquivos em um espaço de trabalho que não são blocos de anotações. Você pode usar arquivos de espaço de trabalho para armazenar e acessar dados e outros arquivos salvos ao lado de blocos de anotações e outros ativos de espaço de trabalho. Como os arquivos de espaço de trabalho têm restrições de tamanho, o Databricks recomenda armazenar apenas pequenos arquivos de dados aqui, principalmente para desenvolvimento e teste.

Ferramenta	Exemplo
Apache Spark	spark.read.format("json").load("file:/Workspace/Users/<user-folder>/data.json").show()
Spark SQL e Databricks SQL	SELECT * FROM json.`file:/Workspace/Users/<user-folder>/file.json`;
Utilitários do sistema de arquivos Databricks	dbutils.fs.ls("file:/Workspace/Users/<user-folder>/") %fs ls file:/Workspace/Users/<user-folder>/
CLI do Databricks	databricks workspace list
API REST do Databricks	POST https://<databricks-instance>/api/2.0/workspace/delete {"path": "/Workspace/Shared/code.py", "recursive": "false"}
Comandos shell Bash	%sh curl http://<address>/text.zip -o /Workspace/Users/<user-folder>/text.zip
Instalações da biblioteca	%pip install /Workspace/Users/<user-folder>/my_library.whl
Pandas	df = pd.read_csv('/Workspace/Users/<user-folder>/data.csv')
OSS Python	os.listdir('/Workspace/Users/<user-folder>/path/to/directory')

Nota

O file:/ esquema é necessário ao trabalhar com Databricks Utilities, Apache Spark ou SQL.

Limitações dos arquivos do espaço de trabalho

Os arquivos de espaço de trabalho têm as seguintes limitações:

• O tamanho do arquivo de espaço de trabalho é limitado a 500 MB da interface do usuário. O tamanho máximo de ficheiro permitido ao escrever a partir de um cluster é de 256 MB.

• Se seu fluxo de trabalho usa código-fonte localizado em um repositório Git remoto, você não pode gravar no diretório atual ou gravar usando um caminho relativo. Grave dados em outras opções de local.

• Não é possível usar git comandos quando você salva em arquivos de espaço de trabalho. A criação de diretórios não é permitida em arquivos de espaço de .git trabalho.

• Há suporte limitado para operações de arquivo de espaço de trabalho da computação sem servidor.

• Os executores não podem gravar em arquivos de espaço de trabalho.

• não há suporte para links simbólicos.

• Os arquivos de espaço de trabalho não podem ser acessados a partir de funções definidas pelo usuário (UDFs) em clusters com modo de acesso compartilhado.

Para onde vão os arquivos de espaço de trabalho excluídos?

A exclusão de um arquivo de espaço de trabalho o envia para a lixeira. Você pode recuperar ou excluir permanentemente arquivos da lixeira usando a interface do usuário.

Consulte Excluir um objeto.

Trabalhar com ficheiros no armazenamento de objetos na nuvem

A Databricks recomenda o uso de volumes do Unity Catalog para configurar o acesso seguro a arquivos no armazenamento de objetos na nuvem. Se você optar por acessar diretamente os dados no armazenamento de objetos na nuvem usando URIs, deverá configurar permissões. Consulte Gerenciar locais externos, tabelas externas e volumes externos.

Os exemplos a seguir usam URIs para acessar dados no armazenamento de objetos na nuvem:

Ferramenta	Exemplo
Apache Spark	spark.read.format("json").load("abfss://container-name@storage-account-name.dfs.core.windows.net/path/file.json").show()
Spark SQL e Databricks SQL	SELECT * FROM csv.`abfss://container-name@storage-account-name.dfs.core.windows.net/path/file.json`; LIST 'abfss://container-name@storage-account-name.dfs.core.windows.net/path';
Utilitários do sistema de arquivos Databricks	dbutils.fs.ls("abfss://container-name@storage-account-name.dfs.core.windows.net/path/") %fs ls abfss://container-name@storage-account-name.dfs.core.windows.net/path/
CLI do Databricks	Não suportado
API REST do Databricks	Não suportado
Comandos shell Bash	Não suportado
Instalações da biblioteca	%pip install abfss://container-name@storage-account-name.dfs.core.windows.net/path/to/library.whl
Pandas	Não suportado
OSS Python	Não suportado

Nota

O armazenamento de objetos na nuvem não suporta passagem de credenciais.

Trabalhar com arquivos em montagens DBFS e raiz DBFS

As montagens DBFS não são protegíveis usando o Unity Catalog e não são mais recomendadas pelo Databricks. Os dados armazenados na raiz DBFS são acessíveis por todos os usuários no espaço de trabalho. O Databricks recomenda não armazenar qualquer código ou dados confidenciais ou de produção na raiz do DBFS. Consulte O que é o sistema de arquivos Databricks (DBFS)?.

Ferramenta	Exemplo
Apache Spark	spark.read.format("json").load("/mnt/path/to/data.json").show()
Spark SQL e Databricks SQL	SELECT * FROM json.`/mnt/path/to/data.json`;
Utilitários do sistema de arquivos Databricks	dbutils.fs.ls("/mnt/path") %fs ls /mnt/path
CLI do Databricks	databricks fs cp dbfs:/mnt/path/to/remote/file /path/to/local/file
API REST do Databricks	POST https://<host>/api/2.0/dbfs/delete --data '{ "path": "/tmp/HelloWorld.txt" }'
Comandos shell Bash	%sh curl http://<address>/text.zip > /dbfs/mnt/tmp/text.zip
Instalações da biblioteca	%pip install /dbfs/mnt/path/to/my_library.whl
Pandas	df = pd.read_csv('/dbfs/mnt/path/to/data.csv')
OSS Python	os.listdir('/dbfs/mnt/path/to/directory')

Nota

O dbfs:/ esquema é necessário ao trabalhar com a CLI do Databricks.

Trabalhar com arquivos em armazenamento efêmero anexados ao nó do driver

O armazenamento ephermal anexado ao nó do driver é o armazenamento em bloco com acesso de caminho nativo baseado em POSIX. Todos os dados armazenados neste local desaparecem quando um cluster é encerrado ou reiniciado.

Ferramenta	Exemplo
Apache Spark	Não suportado
Spark SQL e Databricks SQL	Não suportado
Utilitários do sistema de arquivos Databricks	dbutils.fs.ls("file:/path") %fs ls file:/path
CLI do Databricks	Não suportado
API REST do Databricks	Não suportado
Comandos shell Bash	%sh curl http://<address>/text.zip > /tmp/text.zip
Instalações da biblioteca	Não suportado
Pandas	df = pd.read_csv('/path/to/data.csv')
OSS Python	os.listdir('/path/to/directory')

Nota

O file:/ esquema é necessário ao trabalhar com utilitários Databricks.

Mover dados do armazenamento efêmero para volumes

Você pode querer acessar dados baixados ou salvos em armazenamento efêmero usando o Apache Spark. Como o armazenamento efêmero é anexado ao driver e o Spark é um mecanismo de processamento distribuído, nem todas as operações podem acessar dados diretamente aqui. Se você precisar mover dados do sistema de arquivos do driver para volumes do Catálogo Unity, poderá copiar arquivos usando comandos mágicos ou os utilitários Databricks, como nos exemplos a seguir:

dbutils.fs.cp ("file:/<path>", "/Volumes/<catalog>/<schema>/<volume>/<path>")

%sh cp /<path> /Volumes/<catalog>/<schema>/<volume>/<path>

%fs cp file:/<path> /Volumes/<catalog>/<schema>/<volume>/<path>