Como juntar dois DataFrames com pandas em Python

Combinar dados de duas tabelas diferentes é uma das tarefas mais comuns na análise de dados. Com o merge do pandas consegues juntar dois DataFrames pela coluna que têm em comum — por exemplo, ligar uma tabela de pedidos à tabela de clientes. Aqui vais fazer isso passo a passo, com exemplos simples e os erros mais frequentes a evitar.

Pré-requisitos

• Python 3 instalado no teu computador.
• A biblioteca pandas instalada (pip install pandas).
• Saber o básico de um DataFrame: linhas, colunas e a função read_csv.

Passo 1: Criar os dois DataFrames

Para este exemplo vamos usar duas tabelas pequenas: uma com clientes e outra com pedidos. Repara que ambas têm a coluna cliente_id — é essa a coluna que liga as duas tabelas.

import pandas as pd

clientes = pd.DataFrame({
    "cliente_id": [1, 2, 3],
    "nome": ["Ana", "Bruno", "Carla"],
    "cidade": ["Lisboa", "Porto", "Braga"]
})

pedidos = pd.DataFrame({
    "pedido_id": [100, 101, 102, 103],
    "cliente_id": [1, 2, 1, 3],
    "valor": [50, 30, 20, 90]
})

Passo 2: Juntar as tabelas com merge

A função pd.merge recebe os dois DataFrames e o nome da coluna comum no parâmetro on. O resultado é uma nova tabela onde cada pedido fica ao lado dos dados do respetivo cliente.

resultado = pd.merge(pedidos, clientes, on="cliente_id")
print(resultado)

Para cada linha de pedidos, o pandas procura a linha correspondente em clientes com o mesmo cliente_id e junta as colunas das duas tabelas.

Dica: usa sempre on quando a coluna de ligação tem o mesmo nome nas duas tabelas. É a forma mais clara e evita confusões.

Passo 3: Escolher o tipo de junção com how

Por omissão, o merge faz um inner join: só mantém as linhas que existem nas duas tabelas. O parâmetro how permite mudar esse comportamento:

• how="inner" — só clientes com pedidos (o valor por omissão).
• how="left" — todos os pedidos, mesmo sem cliente correspondente.
• how="right" — todos os clientes, mesmo sem pedidos.
• how="outer" — tudo das duas tabelas.

todos = pd.merge(clientes, pedidos, on="cliente_id", how="left")
print(todos)

Com how="left" a partir de clientes, um cliente sem pedidos aparece na mesma, com valores em falta (NaN) nas colunas de pedidos.

Passo 4: Juntar por colunas com nomes diferentes

Às vezes a mesma informação tem nomes diferentes em cada tabela — por exemplo cliente_id numa e id na outra. Nesse caso usa left_on e right_on em vez de on.

resultado = pd.merge(
    pedidos, clientes,
    left_on="cliente_id",
    right_on="id"
)

Um erro comum é receber a mensagem KeyError: acontece quando o nome indicado em on não existe exatamente numa das tabelas. Confirma sempre os nomes com df.columns.

Passo 5: Evitar colunas repetidas com suffixes

Quando as duas tabelas têm colunas com o mesmo nome (além da coluna de ligação), o pandas acrescenta os sufixos _x e _y para as distinguir. Podes controlar esses sufixos com o parâmetro suffixes para o resultado ficar mais legível.

resultado = pd.merge(
    pedidos, clientes,
    on="cliente_id",
    suffixes=("_pedido", "_cliente")
)

Verificar o resultado

Para confirmar que a junção correu bem, vê o número de linhas e espreita as primeiras com head():

print(resultado.shape)
print(resultado.head())

Se o número de linhas for muito maior do que esperavas, é provável que a coluna de ligação tenha valores repetidos nas duas tabelas — vale a pena investigar com value_counts().

Conclusão

Já sabes juntar dois DataFrames com merge, escolher o tipo de junção com how e lidar com colunas de nomes diferentes. O próximo passo natural é explorar o groupby para resumir os dados juntos — por exemplo, o total gasto por cidade. Qual vai ser a primeira junção que vais testar nos teus próprios dados?