Como fazer join de DataFrames no PySpark: passo a passo

Combinar informação de várias tabelas é uma das tarefas mais comuns na engenharia de dados. No PySpark, o método join permite cruzar dois DataFrames por uma coluna em comum — por exemplo, associar cada venda ao nome do respetivo cliente. Um join é, na prática, o equivalente ao JOIN do SQL, mas aplicado a DataFrames distribuídos. Neste guia vai aprender, passo a passo, como fazer um join de DataFrames no PySpark, escolher o tipo certo e evitar os erros mais frequentes.

Pré-requisitos

• Um ambiente com PySpark disponível (Databricks, Microsoft Fabric ou uma instalação local do Spark).
• Uma SparkSession ativa — nos notebooks do Databricks e do Fabric já existe com o nome spark.
• Noções básicas de DataFrames: como os criar e como ver dados com show().

Passo 1: Criar dois DataFrames de exemplo

Vamos usar dois DataFrames pequenos: um com clientes e outro com vendas. Cada venda tem um cliente_id que corresponde ao id de um cliente. É essa coluna em comum que liga as duas tabelas — sem uma chave partilhada não há join possível.

from pyspark.sql import SparkSession

spark = SparkSession.builder.getOrCreate()

clientes = spark.createDataFrame(
    [(1, "Ana"), (2, "Bruno"), (3, "Carla")],
    ["id", "nome"],
)

vendas = spark.createDataFrame(
    [(101, 1, 250.0), (102, 1, 90.0), (103, 2, 400.0)],
    ["venda_id", "cliente_id", "valor"],
)

Passo 2: Fazer o join dos DataFrames

O método join recebe três argumentos: o segundo DataFrame, a condição de junção e o tipo de join. Para associar cada venda ao seu cliente, comparamos vendas.cliente_id com clientes.id. O tipo inner — o valor por defeito — mantém apenas as linhas com correspondência nas duas tabelas.

resultado = vendas.join(
    clientes,
    vendas.cliente_id == clientes.id,
    "inner",
)

resultado.show()

O resultado combina as colunas das duas tabelas: cada linha de venda passa a incluir também o nome do cliente. Com os dados do exemplo, obtém três linhas — as duas compras da Ana e a compra do Bruno — cada uma já com o nome correspondente. A Carla não aparece porque não tem vendas.

Passo 3: Escolher o tipo de join certo

Nem sempre queremos apenas as correspondências. Um left join mantém todas as linhas da tabela da esquerda, mesmo quando não há par à direita — nesses casos, as colunas em falta ficam a null. Basta mudar o terceiro argumento:

vendas.join(clientes, vendas.cliente_id == clientes.id, "left").show()

Os tipos mais comuns são inner, left, right e outer. A escolha depende da pergunta que quer responder: "apenas o que tem par" (inner) ou "tudo de um dos lados, com ou sem par" (left ou right).

Passo 4: Evitar nomes de colunas duplicados

Um erro clássico acontece quando as colunas de junção têm o mesmo nome nas duas tabelas: o resultado fica com duas colunas com o mesmo nome e qualquer tentativa de as selecionar dá erro de ambiguidade. A forma mais limpa de o evitar é dar o mesmo nome à chave nas duas tabelas e passar apenas esse nome como texto — assim o PySpark funde-as numa única coluna:

clientes2 = clientes.withColumnRenamed("id", "cliente_id")

vendas.join(clientes2, "cliente_id", "inner").show()

Agora a condição é apenas "cliente_id" e o resultado tem uma só coluna com esse nome, sem duplicados.

Dica: quando uma das tabelas é muito mais pequena (como uma tabela de referência), envolva-a em broadcast para acelerar o join e reduzir a troca de dados entre nós — from pyspark.sql.functions import broadcast e depois vendas.join(broadcast(clientes2), "cliente_id").

Verificar o resultado

Para confirmar que o join correu bem, compare o número de linhas antes e depois. Um inner join nunca devolve mais correspondências do que as que existem; se o total disparar de forma inesperada, é sinal de que a chave tem valores repetidos e criou uma relação muitos-para-muitos.

print("Vendas:", vendas.count())
print("Resultado:", resultado.count())
resultado.printSchema()

O printSchema() lista todas as colunas finais — deve ver as colunas das vendas mais as colunas dos clientes (id e nome). Se as colunas e a contagem baterem certo, o join está correto.

Conclusão

Já consegue cruzar dois DataFrames no PySpark, escolher o tipo de join adequado e evitar o problema das colunas duplicadas — a base de praticamente todos os pipelines de dados. O passo seguinte é combinar o join com groupBy para agregar os dados cruzados, como calcular o total de vendas por cliente. Qual vai ser a primeira tabela que vai juntar no seu projeto?