Databricks - Volumes

Volumes são objetos do Unity Catalog para armazenamento de arquivos não tabulares: CSVs brutos, JSONs, imagens, modelos ML, scripts, etc. Ficam dentro da hierarquia catalog.schema.volume e têm controle de acesso via UC.

Antes dos Volumes, arquivos eram acessados via /dbfs/ (Databricks File System), sem governança, sem ACL por arquivo, difícil de auditar. Volumes resolvem isso.

Tipos de Volume

Managed Volume

O UC gerencia a localização física do volume. Ao fazer DROP VOLUME, os dados são apagados.

CREATE VOLUME IF NOT EXISTS bronze.arquivos.uploads
  COMMENT 'Arquivos brutos recebidos via upload, landing zone';

Localização física: <metastore-storage-root>/<catalog>/<schema>/volumes/<volume>/

External Volume

Aponta para um path existente no object storage. DROP VOLUME não apaga os dados, apenas remove o registro do UC.

CREATE EXTERNAL VOLUME bronze.legacy.arquivos_historicos
  LOCATION 's3://meu-bucket/legacy/arquivos/'
  COMMENT 'Arquivos históricos migrados de sistema legado';

Exige uma External Location registrada no UC apontando para s3://meu-bucket/.

Acessando Volumes

O path de um volume no Databricks é sempre:

/Volumes/<catalog>/<schema>/<volume>/

Python / PySpark

# Listar arquivos
dbutils.fs.ls("/Volumes/bronze/arquivos/uploads/")
 
# Ler arquivo do volume com Pandas
import pandas as pd
df = pd.read_csv("/Volumes/bronze/arquivos/uploads/pedidos_2026.csv")
 
# Ler com Spark
df = spark.read.csv("/Volumes/bronze/arquivos/uploads/pedidos_2026.csv", header=True)
 
# Escrever arquivo no volume
df.toPandas().to_parquet("/Volumes/silver/processados/pedidos/pedidos_clean.parquet")
 
# Copiar arquivo
dbutils.fs.cp(
    "/Volumes/bronze/arquivos/uploads/pedidos_2026.csv",
    "/Volumes/bronze/arquivos/processados/pedidos_2026.csv"
)

SQL

-- Listar conteúdo do volume
LIST '/Volumes/bronze/arquivos/uploads/';
 
-- Ler CSV diretamente via SQL
SELECT * FROM read_files(
  '/Volumes/bronze/arquivos/uploads/pedidos_2026.csv',
  format => 'csv',
  header => 'true'
);
 
-- Criar tabela a partir de arquivo no volume
CREATE TABLE silver.pedidos.fato_pedidos
AS SELECT * FROM read_files('/Volumes/bronze/arquivos/uploads/', format => 'csv', header => 'true');

Databricks CLI e API

# Upload de arquivo local para volume via CLI
databricks fs cp ./pedidos.csv dbfs:/Volumes/bronze/arquivos/uploads/pedidos.csv
 
# Ou via REST API
curl -X POST "https://<workspace>/api/2.0/fs/files/Volumes/bronze/arquivos/uploads/pedidos.csv" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @pedidos.csv

Controle de Acesso

Volumes herdam a hierarquia de permissões do Unity Catalog:

-- Leitura
GRANT READ VOLUME ON VOLUME bronze.arquivos.uploads TO `time-analistas`;
 
-- Leitura e escrita
GRANT WRITE VOLUME ON VOLUME bronze.arquivos.uploads TO `engenharia-dados`;
 
-- Apenas administradores podem fazer DROP VOLUME (ALL PRIVILEGES)
GRANT ALL PRIVILEGES ON VOLUME bronze.arquivos.uploads TO `admins`;

Padrões de uso

Landing Zone (ingestão de arquivos)

Processo externo envia arquivo
    → /Volumes/bronze/landing/raw/pedidos_20260501.csv
    → Job lê, valida e escreve em /Volumes/bronze/landing/processados/
    → Pipeline Delta cria tabela bronze.pedidos.raw

Armazenamento de modelos ML

import mlflow
 
# Salvar artefato de modelo no volume
mlflow.sklearn.save_model(modelo, "/Volumes/gold/ml/modelos/churn_v3/")

Checkpoints de Streaming

# Streams precisam de um diretório de checkpoint estável
df.writeStream \
  .format("delta") \
  .option("checkpointLocation", "/Volumes/silver/checkpoints/pedidos_stream/") \
  .table("silver.pedidos.stream")

Volumes vs. DBFS vs. Cloud Storage direto

	DBFS (`/dbfs/`)	Volumes (`/Volumes/`)	Cloud Storage direto (`s3://`)
Governança UC	Não	Sim	Não
ACL por arquivo	Não	Sim (via UC)	Via IAM/RBAC do cloud
Portabilidade	Databricks only	Databricks only	Universal
Recomendação	Legado	Novo padrão	Integrações externas

Ver também: databricks | databricks-unity-catalog | databricks-delta-lake

Second Brain

Explorer