Trabalhar com arquivos no Azure Databricks

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

  • Volume do Unity Catalog
  • Arquivos de workspace
  • Armazenamento de objetos de nuvem
  • Montagens DBFS e raiz DBFS
  • Armazenamento efêmero conectado ao nó do driver do cluster

Esse artigo tem exemplos de interação 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
  • API REST do Databricks
  • Comandos do shell Bash (%sh)
  • A biblioteca com escopo de notebook é instalada usando %pip
  • pandas
  • Utilitários de processamento e gerenciamento de arquivos OSS Python

Importante

As operações de arquivo que exigem acesso a dados FUSE não podem acessar diretamente o armazenamento de objetos em nuvem usando URIs. A Databricks recomenda o uso de volumes do Catálogo do Unity para configurar o acesso a esses locais para o FUSE.

O Scala suporta FUSE para volumes do Catálogo do Unity e arquivos de espaço de trabalho em computação configurada com o Catálogo do Unity e o modo de acesso compartilhado. Na computação configurada com o modo de acesso de usuário único e o Databricks Runtime 14.3 e superiores, o Scala dá suporte ao FUSE para volumes do Catálogo do Unity e arquivos de workspace, exceto para subprocessos originários do Scala, como o comando "cat /Volumes/path/to/file".!! do Scala.

Preciso fornecer um esquema de URI para acessar dados?

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

  • 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 dados diretamente no armazenamento de objetos em nuvem, você deve fornecer o esquema de URI correto para o tipo de armazenamento.

    Diagrama dos caminhos de URI

  • 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 Catálogo do Unity 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 Python OSS exigem FUSE e só podem usar caminhos no estilo POSIX.

    Diagrama dos caminhos POSIX

Trabalhar com arquivos em volumes do Unity Catalog

A 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 na nuvem. Confira O que são os 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 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 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')
OSS Python os.listdir('/Volumes/my_catalog/my_schema/my_volume/path/to/directory')

Observação

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

Databricks arquivos de espaço de trabalho são os arquivos em um espaço de trabalho que não são notebooks. Você pode usar arquivos de espaço de trabalho para armazenar e acessar dados e outros arquivos salvos junto com 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 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')
OSS Python os.listdir('/Workspace/Users/<user-folder>/path/to/directory')

Observação

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

Para obter as limitações no trabalho com arquivos de espaço de trabalho, consulte Limitações.

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

Excluir um arquivo de workspace o envia para a lixeira. Você pode recuperar ou excluir permanentemente arquivos da lixeira usando a IU.

Confira Excluir um objeto.

Trabalhar com arquivos no armazenamento de objetos na nuvem

A Databricks recomenda o uso de volumes do Catálogo do Unity para configurar o acesso seguro a arquivos no armazenamento de objetos na nuvem. Você deverá configurar permissões se optar por acessar dados diretamente no armazenamento de objetos em nuvem usando URIs. 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 Sem suporte
API REST do Databricks 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
OSS Python Sem suporte

Observação

O armazenamento de objetos de nuvem não dá suporte à passagem de credencial.

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 podem ser acessados por todos os usuários no espaço de trabalho. O Databricks não recomenda o armazenamento de qualquer código ou dados confidenciais ou de produção na raiz DBFS. Confira 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 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 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')
OSS Python os.listdir('/dbfs/mnt/path/to/directory')

Observação

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

Trabalhar com arquivos no armazenamento efêmero anexados ao nó do 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 Databricks dbutils.fs.ls("file:/path")
%fs ls file:/path
CLI do Databricks Sem suporte
API REST do Databricks 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')
OSS Python os.listdir('/path/to/directory')

Observação

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

Mover dados do armazenamento efêmero para volumes

Talvez você queira 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 diretamente os dados aqui. Suponha que você deva mover dados do sistema de arquivos do driver para volumes do Unity Catalog. Nesse caso, você pode 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>

Recursos adicionais

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