Da Planilha ao Spark: Quando seus dados não cabem mais no Excel

Workshop prático de introdução ao PySpark, partindo do problema real de escalar análises que já não cabem em planilhas ou no Pandas.

Assista ao workshop: YouTube Live

---

O problema

Você já tentou abrir um CSV de milhões de linhas no Excel ou Google Sheets e levou um erro ou travamento? Este workshop começa exatamente daqui.

---

O que você vai aprender

O notebook guia os participantes por uma jornada progressiva:

#	Tema	Conceito-chave
1	Benchmark de escala	Google Sheets vs Pandas vs Spark com 50k, 500k e 50M linhas
2	API do Spark DataFrame	Leitura, exploração, filtros, agregações e transformações
3	Joins (star schema)	Consultas unindo 4 tabelas (vendas, produtos, clientes, lojas)
4	Lazy Evaluation	Como o Spark adia e otimiza a execução
5	SQL no Spark	Mesmas consultas escritas em SQL via spark.sql()
6	Narrow vs Wide transformations	Entendendo shuffles e partições
7	Otimização	Filtrar antes de juntar, cache e armadilhas comuns em produção

---

Modelo de dados

O dataset simula um sistema de vendas com schema estrela (star schema):

Ver diagrama simplificado

Datasets gerados

O script gerar_dados.py cria datasets sintéticos em português brasileiro, reproduzíveis (seed=42):

Arquivo	Linhas	Tamanho aprox.	Descrição
vendas_50k.csv	50.000	~5 MB	Tabela fato — escala planilha
vendas_500k.csv	500.000	~50 MB	Tabela fato — escala benchmark
vendas_50m.csv	50.000.000	~5 GB	Tabela fato — escala Spark
clientes.csv	1.000	< 1 MB	Dimensão clientes
produtos.csv	50	< 1 MB	Dimensão produtos
lojas.csv	20	< 1 MB	Dimensão lojas

Nota: os CSVs são gerados automaticamente ao subir o Dev Container. O arquivo vendas_50m.csv (~5 GB) é gerado em chunks para não estourar a RAM.

---

Como rodar

O ambiente completo roda via Dev Containers — sem precisar instalar Python, Java ou Spark na sua máquina.

Pré-requisitos

Ferramenta	Versão mínima	Link
Docker Desktop	qualquer recente	download
VS Code	qualquer recente	download
Extensão Dev Containers	—	marketplace

Recursos recomendados: 8 GB de RAM livres para o Docker e ~10 GB de espaço em disco (container + CSVs gerados).

Passo a passo

1. Clone o repositório

git clone https://github.com/<seu-usuario>/workshop-spark-intro.git
cd workshop-spark-intro

2. Abra no VS Code

code .

3. Reabra no Dev Container

O VS Code vai detectar a configuração e exibir um aviso no canto inferior direito:

"Reopen in Container" → clique nele.

Ou use a Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Dev Containers: Reopen in Container

4. Aguarde o build

Na primeira execução, o container irá:

• Instalar Python 3.11, Java 17 e Spark 3.5.0
• Instalar as dependências Python (pyspark, pandas, polars, jupyter)
• Gerar automaticamente todos os CSVs via gerar_dados.py
• Iniciar o cluster Spark standalone (master + worker)

5. Execute o notebook

Abra workshop_notebook.ipynb e execute as células sequencialmente.

---

Stack e portas

Stack

Componente	Versão
Python	3.11
Apache Spark	3.5.0 (standalone cluster)
Java	17 (OpenJDK)
Pandas	última compatível
Polars	última compatível
Jupyter	última compatível

Portas expostas

Porta	Interface
4040	Spark Application UI (jobs, stages, tasks)
7077	Spark Master (conexão de workers)
8080	Spark Master Web UI
8081	Spark Worker Web UI
8888	Jupyter Notebook

Acesse o Spark UI em http://localhost:4040 enquanto uma célula do notebook estiver rodando.

---

Estrutura do repositório

workshop-spark-intro/
├── .devcontainer/
│   ├── Dockerfile            # Imagem com Python, Java e Spark
│   ├── devcontainer.json     # Configuração do Dev Container
│   └── start-spark.sh        # Script de inicialização do cluster Spark
├── media/                    # Imagens usadas no notebook e README
├── workspace/                # CSVs gerados (criados automaticamente)
├── gerar_dados.py            # Gerador de dados sintéticos
├── workshop_notebook.ipynb   # Notebook principal do workshop
└── README.md

---

Troubleshooting

O container demora muito para buildar na primeira vez

Normal — ele baixa e instala Spark (~300 MB). As próximas inicializações são rápidas.

O arquivo vendas_50m.csv não foi gerado

Execute manualmente no terminal do container: python gerar_dados.py

Porta já em uso

Pare outros serviços que usam as portas 4040, 8080 ou 8888 antes de subir o container.

Erro de memória ao processar 50M linhas

Aumente a memória disponível para o Docker em Docker Desktop → Settings → Resources.

Erro no build: COPY failed: spark-3.5.0-bin-hadoop3.tgz not found

O binário do Spark não é versionado no repositório por ser muito grande (~300 MB). Baixe manualmente antes de buildar o container:

1. Acesse https://archive.apache.org/dist/spark/spark-3.5.0/
2. Baixe spark-3.5.0-bin-hadoop3.tgz
3. Mova o arquivo para a pasta .devcontainer/