pandas.merge() combina DataFrames como un join de base de datos. El riesgo principal no es la sintaxis, sino la cardinalidad: claves duplicadas pueden multiplicar filas y alterar totales sin un error visible.

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" conserva todos los pedidos. validate="many_to_one" exige claves únicas en clientes. indicator=True añade _merge, que permite localizar registros sin correspondencia antes de publicar el análisis.

Buenas prácticas

Normaliza tipos y espacios de las claves sin destruir ceros iniciales significativos. Mide filas y unicidad antes y después. Ten en cuenta que pandas puede emparejar claves nulas de ambos lados, a diferencia del SQL habitual. Usa sufijos claros para columnas repetidas.

Continúa con la guía de pandas y valida contratos con Pandera.

La referencia oficial de pandas.merge, consultada el 22 de julio de 2026, detalla la API y sus límites.