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 Unity
  • Arquivos de espaço de trabalho
  • Armazenamento de objetos na nuvem
  • Montagens DBFS e raiz DBFS
  • Armazenamento efémero ligado ao nó de controlo do cluster

Este 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 Databricks (dbutils.fs ou %fs)
  • Databricks CLI
  • Databricks REST API
  • Comandos shell Bash (%sh)
  • Instalações de bibliotecas com escopo de notebook 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 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 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. Na computação configurada com o modo de acesso de usuário único e o Databricks Runtime 14.3 e superior, o Scala suporta volumes e arquivos de espaço de trabalho do FUSE for Unity Catalog, exceto para subprocessos originários do Scala, como o comando Scala "cat /Volumes/path/to/file".!!.

O Spark e outros processos da JVM só podem acessar volumes ou arquivos de espaço de trabalho do Unity Catalog usando os leitores e gravadores que suportam o Unity Catalog. Por exemplo, não é possível especificar um arquivo JAR como uma dependência em uma configuração do Spark e não é possível usar fontes de dados personalizadas do PySpark. Se você tiver uma carga de trabalho JVM de bibliotecas que precisam acessar arquivos em volumes ou em arquivos de espaço de trabalho, copie os arquivos para o armazenamento local de computação usando Python ou comandos shell, como %sh mv.. Não use %fs ou dbutils.fs que utiliza a JVM. Se um arquivo precisar estar presente durante o início do cluster, use um script init para mover o arquivo primeiro. Consulte O que são scripts init?.

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 diretamente os dados no armazenamento de objetos na 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 controlador (/). 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.

    diagrama de caminhos 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 O que são volumes do Catálogo 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/
Databricks CLI 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 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 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 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

Databricks arquivos de espaço de trabalho são os arquivos no espaço de trabalho. Você pode usar arquivos de espaço de trabalho para armazenar e acessar arquivos como blocos de anotações, arquivos de código-fonte, arquivos de dados 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>/
Databricks CLI databricks workspace list
Databricks REST API 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 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 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 ver as limitações ao trabalhar com ficheiros de espaço de trabalho, consulte Limitações.

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. Você deve configurar permissões se optar por acessar diretamente os dados no armazenamento de objetos na 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/
Databricks CLI Não suportado
Databricks REST API Não suportado
Comandos shell Bash Não suportado
Instalações de biblioteca %pip install abfss://container-name@storage-account-name.dfs.core.windows.net/path/to/library.whl
Pandas Não suportado
Python de código aberto Não suportado

Observação

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. 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 Databricks dbutils.fs.ls("/mnt/path")
%fs ls /mnt/path
Databricks CLI 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 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 os.listdir('/dbfs/mnt/path/to/directory')

Observação

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

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

O armazenamento efémero anexado ao nó do driver é um armazenamento em bloco com acesso a caminho baseado em POSIX integrado. 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
Databricks CLI Não suportado
Databricks REST API Não suportado
Comandos shell Bash %sh curl http://<address>/text.zip > /tmp/text.zip
Instalações de biblioteca Não suportado
Pandas df = pd.read_csv('/path/to/data.csv')
Python de código aberto os.listdir('/path/to/directory')

Observação

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

Mova 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. Suponha que seja necessário mover dados do sistema de ficheiros do driver para volumes do Unity Catalog. 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 ficheiros locais ou transferir ficheiros da Internet para o Azure Databricks, consulte Carregar ficheiros para o Azure Databricks.