pandas.merge() combina DataFrames como um join de banco de dados. O risco principal não é a sintaxe, mas a cardinalidade: chaves duplicadas podem multiplicar linhas e alterar totais sem erro aparente.

import pandas as pd

pedidos = pd.DataFrame({"cliente_id": [1, 2, 3], "total": [80, 120, 45]})
clientes = pd.DataFrame({"cliente_id": [1, 2], "nome": ["Ana", "Beto"]})

resultado = pedidos.merge(
    clientes,
    on="cliente_id",
    how="left",
    validate="many_to_one",
    indicator=True,
)

print(resultado)

how="left" preserva todos os pedidos. validate="many_to_one" exige que a chave seja única no lado de clientes. indicator=True adiciona _merge, permitindo localizar registros sem correspondência antes de publicar uma análise.

Boas práticas

Normalize tipos e espaços nas chaves sem destruir zeros à esquerda. Meça linhas e unicidade antes e depois do merge. Atenção: chaves nulas em ambos os lados podem corresponder no pandas, diferentemente do comportamento SQL usual. Use sufixos claros quando colunas compartilham nomes.

Aprofunde o fluxo no guia de pandas e valide contratos de DataFrame com Pandera.

A referência oficial de pandas.merge, consultada em 22 de julho de 2026, detalha a API e seus limites.