pandas.merge() combines DataFrames like a database join. The main risk is not syntax but cardinality: duplicate keys may multiply rows and change totals without an obvious error.

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" preserves all orders. validate="many_to_one" requires unique keys on the customer side. indicator=True adds _merge, which exposes unmatched records before an analysis is published.

Practical guidance

Normalize key types and whitespace without destroying meaningful leading zeros. Measure row counts and uniqueness before and after merging. Note that pandas may match null keys on both sides, unlike typical SQL behavior. Use meaningful suffixes when columns share names.

Continue with the pandas guide and enforce DataFrame contracts using Pandera.

The official pandas.merge reference, accessed July 22, 2026, documents the API and its constraints.