Compartilhar via

Trabalhar com arquivos no Azure Databricks

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

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

Este artigo tem exemplos para interagir com arquivos nesses locais para as seguintes ferramentas:

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

Importante

Algumas operações no Databricks, especialmente aquelas que usam bibliotecas Java ou Scala, são executadas como processos JVM, por exemplo:

  • Especificando uma dependência de arquivo JAR usando --jars nas configurações do Spark
  • Chamando cat ou java.io.File em notebooks Scala
  • Fontes de dados personalizadas, como spark.read.format("com.mycompany.datasource")
  • Bibliotecas que carregam arquivos usando Java FileInputStream ou Paths.get()

Essas operações não oferecem suporte à leitura ou gravação em volumes do Catálogo do Unity ou em arquivos no espaço de trabalho usando caminhos de arquivo padrão, como /Volumes/my-catalog/my-schema/my-volume/my-file.csv. Se você precisar acessar arquivos de volume ou arquivos de espaço de trabalho de dependências JAR ou bibliotecas baseadas em JVM, copie os arquivos primeiro para armazenamento local de computação usando comandos Python ou %sh, como %sh mv.. Não use %fs e dbutils.fs que usam a JVM. Para acessar arquivos já copiados localmente, use comandos específicos de linguagem, como Python shutil ou use %sh comandos. Se um arquivo precisar estar presente durante o início do cluster, use um script de inicialização para mover o arquivo primeiro. Consulte O que são scripts de inicialização?.

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 URI. Para soluções de acesso a dados nativos do Databricks, os esquemas de URI são opcionais para a maioria dos casos de uso. Ao acessar dados diretamente no armazenamento de objetos de nuvem, você deve fornecer o esquema de URI correto para o tipo de armazenamento.

    diagrama de caminhos de URI

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

    diagrama de caminhos POSIX

Nota

As operações de arquivo que exigem acesso a dados FUSE não podem acessar diretamente o armazenamento de objetos de nuvem usando URIs. A Databricks recomenda usar volumes do Unity Catalog para configurar o acesso a essas localizações para o FUSE.

Em sistemas configurados com o modo de acesso dedicado (anteriormente modo de acesso para usuário único) e Databricks Runtime 14.3 e versões superiores, Scala dá suporte ao FUSE para volumes do Unity Catalog e arquivos de área de trabalho, exceto para subprocessos originários de Scala, como o comando "cat /Volumes/path/to/file".!!.

Trabalhar com arquivos em volumes do Catálogo do Unity

O Databricks recomenda o uso de volumes do Catálogo do Unity para configurar o acesso a arquivos de dados não tabulares armazenados no armazenamento de objetos de nuvem. Veja O que são volumes do Catálogo do Unity?.

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 do 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/
Databricks REST API POST https://<databricks-instance>/api/2.1/jobs/create
{"name": "A multitask job", "tasks": [{..."libraries": [{"jar": "/Volumes/dev/environment/libraries/logging/Logging.jar"}],},...]}
Comandos do shell Bash %sh curl http://<address>/text.zip -o /Volumes/my_catalog/my_schema/my_volume/tmp/text.zip
Instalações de 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')
Python de Código Aberto (OSS) os.listdir('/Volumes/my_catalog/my_schema/my_volume/path/to/directory')

Nota

O esquema de dbfs:/ é 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 com anexação direta ou não sequenciais (aleatórias), como a gravação de arquivos Zip e Excel. Para cargas de trabalho de acréscimo direto ou de gravação aleatória, execute as operações primeiro em um disco local e, em seguida, copie os resultados para volumes do Unity Catalog. 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

Trabalhar com arquivos do espaço de trabalho

Os arquivos de workspace do Databricks são os arquivos em um workspace, armazenados na conta de armazenamento do workspace. Você pode usar arquivos de workspace para armazenar e acessar arquivos como notebooks, arquivos de código-fonte, arquivos de dados e outros ativos do workspace. Como os arquivos de workspace têm restrições de tamanho, o Databricks recomenda armazenar apenas arquivos de dados pequenos 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 do Databricks dbutils.fs.ls("file:/Workspace/Users/<user-folder>/")
%fs ls file:/Workspace/Users/<user-folder>/
CLI do Databricks databricks workspace list
Databricks REST API POST https://<databricks-instance>/api/2.0/workspace/delete
{"path": "/Workspace/Shared/code.py", "recursive": "false"}
Comandos do shell Bash %sh curl http://<address>/text.zip -o /Workspace/Users/<user-folder>/text.zip
Instalações de biblioteca %pip install /Workspace/Users/<user-folder>/my_library.whl
Pandas df = pd.read_csv('/Workspace/Users/<user-folder>/data.csv')
Python de Código Aberto (OSS) os.listdir('/Workspace/Users/<user-folder>/path/to/directory')

Nota

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

Para ver as limitações para trabalhar com arquivos de espaço de trabalho, consulte Limitações.

Para onde vão os arquivos de workspace excluídos?

Excluir um arquivo da área 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 arquivos no armazenamento de objetos na nuvem

O Databricks recomenda usar volumes do Catálogo do Unity para configurar o acesso seguro a arquivos no armazenamento de objetos de nuvem. Você deve configurar permissões se optar por acessar dados diretamente no armazenamento de objetos de nuvem usando URIs. Consulte Volumes gerenciados e 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 do 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 Sem suporte
Databricks REST API Sem suporte
Comandos do shell Bash Sem suporte
Instalações de biblioteca %pip install abfss://container-name@storage-account-name.dfs.core.windows.net/path/to/library.whl
Pandas Sem suporte
Python de Código Aberto (OSS) Sem suporte

Trabalhar com arquivos em montagens DBFS e na raiz do DBFS

As montagens DBFS não são protegíveis usando o Catálogo do Unity 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 workspace. A Databricks recomenda não armazenar códigos ou dados confidenciais ou de produção na raiz do DBFS. Veja O que é 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 do 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
Databricks REST API POST https://<host>/api/2.0/dbfs/delete --data '{ "path": "/tmp/HelloWorld.txt" }'
Comandos do shell Bash %sh curl http://<address>/text.zip > /dbfs/mnt/tmp/text.zip
Instalações de biblioteca %pip install /dbfs/mnt/path/to/my_library.whl
Pandas df = pd.read_csv('/dbfs/mnt/path/to/data.csv')
Python de Código Aberto (OSS) os.listdir('/dbfs/mnt/path/to/directory')

Nota

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

Trabalhar com arquivos no armazenamento efêmero anexado ao nó de driver

O armazenamento efêmero anexado ao nó do driver é um armazenamento em bloco com acesso de caminho integrado baseado em POSIX. Todos os dados armazenados nesse local desaparecem quando um cluster é encerrado ou reiniciado.

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

Nota

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

Mover dados do armazenamento efêmero para volumes

Talvez você queira acessar os dados baixados ou salvos no armazenamento efêmero usando o Apache Spark. Como o armazenamento efêmero está anexado ao driver e o Spark é um mecanismo de processamento distribuído, nem todas as operações podem acessar diretamente os dados aqui. Suponha que você deve mover dados do sistema de arquivos de driver para volumes do Catálogo do Unity. Nesse caso, você pode copiar arquivos usando comandos mágicos ou os utilitários Databricks, como nos seguintes exemplos:

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>

Recursos adicionais

Para obter informações sobre como carregar arquivos locais ou baixar arquivos da Internet no Azure Databricks, consulte Carregar arquivos no Azure Databricks.