Explorar guías rápidas · Python

Tecnología: PythonCategoría: Análisis de datosNivel: IntermedioActualizado

Combinar DataFrames con merge y join

Combina DataFrames de pandas de forma segura validando claves, cardinalidad, comportamiento de los nulos, multiplicación por duplicados y cambios en el número de filas antes de confiar en el resultado.

En esta página
  1. Problema
  2. Respuesta rápida
  3. Código / comandos
  4. 1. Inner join
  5. 2. Left join
  6. 3. Right join
  7. 4. Full outer join
  8. 5. Valida la cardinalidad del join
  9. 6. Comprueba la unicidad de las claves antes del merge
  10. 7. Join sobre varias columnas
  11. 8. Join cuando los nombres de las claves son distintos
  12. 9. Inspecciona las filas sin correspondencia
  13. 10. Concilia los porcentajes de correspondencia
  14. 11. Detecta la multiplicación de filas
  15. 12. Entiende la expansión de muchos a muchos
  16. 13. Protege los totales posteriores frente a duplicaciones accidentales
  17. 14. Maneja los nombres de columna coincidentes
  18. 15. Selecciona solo las columnas necesarias antes del join
  19. 16. Join mediante índices
  20. 17. Semi join: conserva las filas izquierdas que tienen correspondencia
  21. 18. Anti join: conserva las filas izquierdas sin correspondencia
  22. 19. Join con claves nulas: entiende el comportamiento de pandas
  23. 20. Comprueba la compatibilidad de los dtypes de las claves del join
  24. 21. Normaliza las claves de texto con cuidado
  25. 22. Evita nombres de columna duplicados accidentales antes del merge
  26. 23. Merge con coincidencias temporales ordenadas mediante merge_asof
  27. 24. Cross join intencional
  28. Qué significa el resultado
  29. Qué revisar
  30. El left join aumenta el número de filas
  31. El inner join pierde más filas de lo esperado
  32. Los totales aumentan después del enriquecimiento
  33. Muchas filas sin correspondencia
  34. Aparecen columnas _x y _y por todas partes
  35. Las claves nulas coinciden de forma inesperada
  36. Notas de producción
  37. Valida siempre la cardinalidad esperada
  38. La conciliación del número de filas debería ser lo normal
  39. Concilia las medidas importantes
  40. Selecciona las columnas antes del join
  41. Los joins de muchos a muchos pueden disparar el uso de memoria
  42. Los joins de pandas se ejecutan en memoria
  43. No uses la salida del merge como sustituto de las comprobaciones de calidad de las claves
  44. Errores comunes
  45. 1. Hacer el merge sin comprobar la unicidad de las claves
  46. 2. Usar many_to_many para que la validación pase
  47. 3. Suponer que un left join preserva el número de filas
  48. 4. Eliminar duplicados después de un merge incorrecto
  49. 5. Hacer el join con claves de negocio incompletas
  50. 6. Ignorar las claves de join nulas
  51. 7. Depender de _x y _y
  52. 8. Hacer el join antes de filtrar o proyectar
  53. 9. Confiar en nombres de dtype coincidentes sin revisar los valores
  54. Siguiente paso
  55. Para profundizar

Problema

Necesitas combinar dos DataFrames de pandas usando una o varias claves de negocio.

Ejemplos comunes:

  • pedidos + clientes
  • transacciones + metadatos de comercios
  • hechos + dimensiones
  • eventos + tablas de consulta
  • datos actuales + datos de enriquecimiento

La sintaxis es sencilla.

El riesgo real es obtener un resultado que parece válido pero tiene un número de filas incorrecto o valores de negocio duplicados.

Antes de confiar en un join, necesitas responder:

  • ¿Las claves del join son únicas en alguno de los dos lados?
  • ¿La relación es de uno a uno, uno a muchos, muchos a uno o muchos a muchos?
  • ¿Cuántas filas debería contener el resultado?
  • ¿Las claves nulas se comportaron como esperabas?
  • ¿Las claves duplicadas multiplicaron filas?
  • ¿Alguna fila de origen se quedó sin correspondencia?
  • ¿Los nombres de columna coincidentes se manejaron de forma intencional?

Respuesta rápida

Usa pd.merge() y valida la cardinalidad esperada.

result = pd.merge(
    orders,
    customers,
    on="customer_id",
    how="left",
    validate="many_to_one",
)

Después, concilia el resultado:

print("orders:", len(orders))
print("result:", len(result))

assert len(result) == len(orders)

Si el lado derecho debe contener una fila por customer_id, valídalo antes del merge:

assert not customers["customer_id"].duplicated().any()

El hábito más importante en producción es:

Nunca tomes un merge que termina sin errores como prueba de que el merge es lógicamente correcto.

Código / comandos

1. Inner join

Conserva solo las claves presentes en ambos DataFrames.

result = pd.merge(
    left,
    right,
    on="customer_id",
    how="inner",
)

Úsalo cuando los registros sin correspondencia deban excluirse.

Ten cuidado: el número de filas puede disminuir.


2. Left join

Conserva todas las filas del DataFrame izquierdo.

result = pd.merge(
    orders,
    customers,
    on="customer_id",
    how="left",
)

Es habitual para enriquecer datos.

Si la clave del lado derecho es única, normalmente debería preservarse el número de filas del lado izquierdo.

Valídalo de forma explícita:

assert len(result) == len(orders)

Si el resultado tiene más filas que orders, la clave del lado derecho no era única para al menos algunos de los valores con correspondencia.


3. Right join

result = pd.merge(
    left,
    right,
    on="customer_id",
    how="right",
)

Úsalo cuando el DataFrame derecho define la población que debe preservarse.

En la mayoría del código de datos de negocio, un left join suele ser más fácil de razonar, porque el conjunto de datos principal se mantiene a la izquierda.


4. Full outer join

result = pd.merge(
    left,
    right,
    on="customer_id",
    how="outer",
)

Úsalo para conciliar cuando necesites:

  • filas con correspondencia
  • filas solo del lado izquierdo
  • filas solo del lado derecho

Agrega un indicador:

result = pd.merge(
    left,
    right,
    on="customer_id",
    how="outer",
    indicator=True,
)

Después, inspecciona:

print(result["_merge"].value_counts())

Valores posibles:

both
left_only
right_only

Este es uno de los mejores patrones para controlar la calidad de un join.


5. Valida la cardinalidad del join

pandas puede fallar de inmediato cuando la forma de las claves no es la que esperas.

Uno a uno:

result = pd.merge(
    left,
    right,
    on="customer_id",
    how="inner",
    validate="one_to_one",
)

Muchos a uno:

result = pd.merge(
    orders,
    customers,
    on="customer_id",
    how="left",
    validate="many_to_one",
)

Uno a muchos:

result = pd.merge(
    customers,
    orders,
    on="customer_id",
    how="left",
    validate="one_to_many",
)

Muchos a muchos:

result = pd.merge(
    left,
    right,
    on="key",
    how="inner",
    validate="many_to_many",
)

No uses many_to_many solo para silenciar un error.

Si una relación de muchos a muchos es inesperada, detente e investiga.


6. Comprueba la unicidad de las claves antes del merge

Lado izquierdo:

print(left["customer_id"].is_unique)

Lado derecho:

print(right["customer_id"].is_unique)

Inspecciona los duplicados:

duplicate_right_keys = right.loc[
    right["customer_id"].duplicated(keep=False)
].sort_values("customer_id")

print(duplicate_right_keys.head(50))

Para claves compuestas:

key_cols = ["merchant_id", "site_id"]

duplicate_keys = right.loc[
    right.duplicated(subset=key_cols, keep=False)
].sort_values(key_cols)

Haz esto antes de decidir qué valor debe tener validate=.


7. Join sobre varias columnas

result = pd.merge(
    sales,
    merchant_map,
    on=["merchant_id", "site_id"],
    how="left",
    validate="many_to_one",
)

Usa claves compuestas cuando una sola columna no baste para identificar de forma única la entidad de negocio.

No simplifiques una clave de negocio compuesta real solo para acortar la sintaxis del merge.


8. Join cuando los nombres de las claves son distintos

result = pd.merge(
    left,
    right,
    left_on="customer_id",
    right_on="client_id",
    how="left",
    validate="many_to_one",
)

Después de validar el resultado, considera eliminar la clave redundante del lado derecho:

result = result.drop(columns=["client_id"])

Hazlo solo cuando ambas columnas representen realmente la misma clave de negocio.


9. Inspecciona las filas sin correspondencia

Para un left join:

result = pd.merge(
    orders,
    customers,
    on="customer_id",
    how="left",
    indicator=True,
    validate="many_to_one",
)

unmatched = result.loc[
    result["_merge"] == "left_only"
]

print(unmatched.head(50))

Esto es mejor que buscar una columna de enriquecimiento nula, porque los valores legítimos del lado derecho también pueden ser nulos.


10. Concilia los porcentajes de correspondencia

merge_counts = result["_merge"].value_counts()

match_rate = (
    result["_merge"].eq("both").mean() * 100
)

print(merge_counts)
print(f"Match rate: {match_rate:.2f}%")

No inventes un umbral universal de tasa de correspondencia aceptable.

La tasa esperada depende del proceso de negocio.


11. Detecta la multiplicación de filas

Antes:

before = len(left)

Merge:

result = pd.merge(
    left,
    right,
    on="customer_id",
    how="left",
)

Después:

after = len(result)

print("Before:", before)
print("After:", after)
print("Added rows:", after - before)

Si un left join de enriquecimiento aumenta el número de filas de forma inesperada, inspecciona las claves duplicadas del lado derecho.


12. Entiende la expansión de muchos a muchos

Ejemplo:

left = pd.DataFrame(
    {
        "key": [1, 1],
        "left_value": ["A", "B"],
    }
)

right = pd.DataFrame(
    {
        "key": [1, 1, 1],
        "right_value": ["X", "Y", "Z"],
    }
)

Este merge:

result = left.merge(
    right,
    on="key",
    how="inner",
)

produce:

2 filas izquierdas × 3 filas derechas = 6 filas de resultado

Ese es el comportamiento relacional correcto.

También es una fuente habitual de doble conteo accidental.


13. Protege los totales posteriores frente a duplicaciones accidentales

Supón que este es el total original de los pedidos:

source_total = orders["amount"].sum()

Después de combinar los datos de clientes:

result = orders.merge(
    customers,
    on="customer_id",
    how="left",
    validate="many_to_one",
)

Concilia:

result_total = result["amount"].sum()

assert source_total == result_total

Para valores monetarios en coma flotante, la igualdad exacta puede no ser adecuada según su representación.

Prefiere un modelado seguro con decimales para los cálculos financieros.


14. Maneja los nombres de columna coincidentes

De forma predeterminada, pandas agrega sufijos como _x y _y.

Usa sufijos explícitos:

result = pd.merge(
    left,
    right,
    on="customer_id",
    how="left",
    suffixes=("_order", "_customer"),
)

Esto es mucho más claro que dejar columnas ambiguas como:

status_x
status_y

15. Selecciona solo las columnas necesarias antes del join

En lugar de:

result = orders.merge(
    customers,
    on="customer_id",
    how="left",
)

usa:

customer_lookup = customers[
    ["customer_id", "country", "segment"]
]

result = orders.merge(
    customer_lookup,
    on="customer_id",
    how="left",
    validate="many_to_one",
)

Esto reduce:

  • el uso de memoria
  • las colisiones de nombres de columna
  • las dependencias accidentales
  • el movimiento innecesario de datos

16. Join mediante índices

Si ambos DataFrames están indexados intencionalmente por la misma clave:

result = left.join(
    right,
    how="left",
)

O bien:

result = left.join(
    right,
    how="left",
    validate="many_to_one",
)

Usa .join() cuando el join basado en el índice forme parte real del diseño del DataFrame.

No definas índices solo para imitar la sintaxis de join de SQL.


17. Semi join: conserva las filas izquierdas que tienen correspondencia

Pertenencia simple de claves:

valid_customer_ids = customers["customer_id"]

matched_orders = orders.loc[
    orders["customer_id"].isin(valid_customer_ids)
]

Para varias columnas o una lógica relacional más rica, usa un merge en su lugar.


18. Anti join: conserva las filas izquierdas sin correspondencia

Usa indicator=True:

check = orders.merge(
    customers[["customer_id"]],
    on="customer_id",
    how="left",
    indicator=True,
)

unmatched_orders = check.loc[
    check["_merge"] == "left_only"
].drop(columns="_merge")

Es un patrón útil para la calidad de los datos y la conciliación.


19. Join con claves nulas: entiende el comportamiento de pandas

El comportamiento del merge de pandas difiere de SQL en un aspecto importante:

Los valores de clave nulos pueden coincidir con otros valores de clave nulos.

Ejemplo:

left = pd.DataFrame(
    {
        "id": [1, None],
        "left_value": ["A", "B"],
    }
)

right = pd.DataFrame(
    {
        "id": [1, None],
        "right_value": ["X", "Y"],
    }
)

result = left.merge(
    right,
    on="id",
    how="inner",
)

Las filas con claves de join nulas pueden coincidir entre sí.

Si tus reglas de negocio deben comportarse según la semántica de nulos de SQL, maneja explícitamente las claves nulas antes del merge.

Ejemplo:

left_valid = left.loc[left["id"].notna()]
right_valid = right.loc[right["id"].notna()]

Después, haz el merge de los subconjuntos con claves válidas según la lógica que buscas.


20. Comprueba la compatibilidad de los dtypes de las claves del join

Antes del merge:

print(left["customer_id"].dtype)
print(right["customer_id"].dtype)

Normaliza de forma deliberada cuando sea necesario.

Ejemplo:

left_key = left["customer_id"].astype("string")
right_key = right["customer_id"].astype("string")

Durante la investigación, prefiere validar Series convertidas antes de modificar las columnas de origen.

Problemas de claves comunes:

  • entero frente a cadena
  • cadenas con relleno
  • ID mixtos numéricos y de texto
  • diferencias de zona horaria
  • ceros a la izquierda

21. Normaliza las claves de texto con cuidado

left_key = (
    left["customer_code"]
    .astype("string")
    .str.strip()
)

right_key = (
    right["customer_code"]
    .astype("string")
    .str.strip()
)

Si las mayúsculas y minúsculas no son significativas:

left_key = left_key.str.casefold()
right_key = right_key.str.casefold()

No normalices identificadores a ciegas.

En algunos sistemas:

ABC123
abc123

pueden ser claves distintas.


22. Evita nombres de columna duplicados accidentales antes del merge

Comprueba:

overlap = (
    set(left.columns)
    & set(right.columns)
    - {"customer_id"}
)

print(overlap)

Si la coincidencia es inesperada, resuélvela antes del merge.

Así el esquema del resultado es más fácil de razonar.


23. Merge con coincidencias temporales ordenadas mediante merge_asof

Para casos de series temporales en los que necesitas el registro anterior o siguiente más cercano en lugar de una igualdad exacta de marcas de tiempo:

events = events.sort_values("event_time")
prices = prices.sort_values("effective_time")

result = pd.merge_asof(
    events,
    prices,
    left_on="event_time",
    right_on="effective_time",
    direction="backward",
)

Úsalo en casos como:

  • datos de referencia con fecha de vigencia
  • precio vigente en el momento del evento
  • muestra de telemetría anterior más cercana

Ambas entradas deben estar ordenadas por la clave del merge.

Agrega by= cuando la coincidencia también deba mantenerse dentro de una misma entidad:

result = pd.merge_asof(
    events.sort_values(["merchant_id", "event_time"]),
    prices.sort_values(["merchant_id", "effective_time"]),
    left_on="event_time",
    right_on="effective_time",
    by="merchant_id",
    direction="backward",
)

24. Cross join intencional

result = left.merge(
    right,
    how="cross",
)

Un cross join produce:

len(left) × len(right)

filas.

Úsalo solo cuando la expansión cartesiana sea explícitamente intencional.

Nunca uses un cross join para sortear la falta de claves de join.

Qué significa el resultado

Concepto Significado
inner Conserva solo las claves con correspondencia.
left Conserva todas las filas izquierdas y adjunta las coincidencias del lado derecho.
right Conserva todas las filas derechas y adjunta las coincidencias del lado izquierdo.
outer Conserva todas las claves de ambos lados.
indicator=True Agrega _merge, que muestra left_only, right_only o both.
validate="one_to_one" Ambos conjuntos de claves del join deben ser únicos.
validate="one_to_many" Claves izquierdas únicas; las derechas pueden repetirse.
validate="many_to_one" Claves derechas únicas; las izquierdas pueden repetirse.
validate="many_to_many" Se permiten duplicados en ambos lados.
suffixes= Controla los nombres de las columnas no clave coincidentes.
merge_asof() Hace coincidir por la clave ordenada más cercana, normalmente marcas de tiempo.

Qué revisar

El left join aumenta el número de filas

Es una de las señales de alerta más importantes.

Si esperabas un enriquecimiento de muchos a uno, la clave del join del lado derecho probablemente contiene duplicados.

Inspecciona:

right.loc[
    right["customer_id"].duplicated(keep=False)
]

El inner join pierde más filas de lo esperado

Usa un outer join o un left join con indicator=True para identificar las claves que faltan.

Causas posibles:

  • datos de referencia faltantes
  • espacios en blanco
  • incompatibilidades de tipos
  • pérdida de ceros a la izquierda
  • normalización inconsistente
  • clave de join incorrecta

Los totales aumentan después del enriquecimiento

Causas probables:

  • join de uno a muchos
  • claves de dimensión duplicadas
  • granularidad de negocio incorrecta

No corrijas totales inflados volviendo a agruparlos hasta entender por qué se multiplicaron.

Muchas filas sin correspondencia

Investiga la calidad de las claves antes de suponer que la tabla de referencia está incompleta.

Compara:

  • dtypes
  • nulos
  • espacios en blanco
  • mayúsculas y minúsculas
  • formato
  • definición de la clave de negocio

Aparecen columnas _x y _y por todas partes

Esto suele significar que la coincidencia de esquemas no se manejó de forma deliberada.

Usa la selección de columnas y sufijos explícitos.

Las claves nulas coinciden de forma inesperada

Recuerda que pandas puede hacer coincidir claves nulas con claves nulas durante un merge.

Si eso no es válido para tu lógica de negocio, excluye las filas con clave nula o manéjalas por separado.

Notas de producción

Valida siempre la cardinalidad esperada

validate= es una de las funciones de seguridad más valiosas de los joins de pandas.

Úsalo siempre que conozcas la relación.

Ejemplo:

validate="many_to_one"

convierte un problema silencioso de calidad de datos en una excepción explícita.

La conciliación del número de filas debería ser lo normal

En los joins de enriquecimiento, registra:

before_rows = len(left)
after_rows = len(result)

Después, compáralos.

No dejes sin explicar los cambios en el número de filas.

Concilia las medidas importantes

Para datos de tipo hechos, compara los totales importantes antes y después del merge.

Ejemplos:

  • ingresos
  • número de transacciones
  • número de pedidos
  • número de eventos únicos

Un merge estructuralmente válido puede seguir violando invariantes de negocio.

Selecciona las columnas antes del join

Los DataFrames grandes pueden duplicar una cantidad considerable de memoria durante los merges.

Reduce ambos lados a las columnas realmente necesarias.

Los joins de muchos a muchos pueden disparar el uso de memoria

Si ambos lados contienen claves duplicadas, el número de filas puede crecer rápidamente.

Estima la relación antes de combinar conjuntos de datos grandes.

Los joins de pandas se ejecutan en memoria

Para conjuntos de datos grandes:

  • filtra pronto
  • proyecta las columnas necesarias
  • usa dtypes adecuados
  • evita relaciones de muchos a muchos accidentales
  • considera llevar el join a SQL, Spark, DuckDB u otro motor cuando los datos ya no quepan cómodamente en memoria

No uses la salida del merge como sustituto de las comprobaciones de calidad de las claves

Un merge puede terminar sin errores incluso con:

  • claves sucias
  • duplicados inesperados
  • filas sin correspondencia
  • coincidencias de nulos

La validación debe ser explícita.

Errores comunes

1. Hacer el merge sin comprobar la unicidad de las claves

Es la causa principal de la multiplicación accidental de filas.

Conoce primero la relación.

2. Usar many_to_many para que la validación pase

Eso desactiva una comprobación de seguridad valiosa.

Úsalo solo cuando la relación de muchos a muchos sea realmente intencional.

3. Suponer que un left join preserva el número de filas

Un left join preserva las filas izquierdas a nivel conceptual, pero una fila izquierda puede convertirse en varias filas si el lado derecho tiene varias coincidencias.

4. Eliminar duplicados después de un merge incorrecto

Esto puede ocultar el problema real del join y descartar filas válidas.

Corrige en su lugar el problema de claves o de cardinalidad.

5. Hacer el join con claves de negocio incompletas

Si la clave real es:

merchant_id + site_id

hacer el join solo con:

merchant_id

puede crear coincidencias incorrectas.

6. Ignorar las claves de join nulas

La coincidencia de nulos en pandas puede diferir de lo que se espera en SQL.

Maneja de forma deliberada la semántica de las claves nulas.

7. Depender de _x y _y

Una salida ambigua hace que el código posterior sea propenso a errores.

Usa sufijos explícitos o preselecciona las columnas.

8. Hacer el join antes de filtrar o proyectar

Esto puede hacer que un merge grande sea mucho más costoso de lo necesario.

Reduce primero las entradas cuando sea posible.

9. Confiar en nombres de dtype coincidentes sin revisar los valores

Dos columnas de texto pueden seguir siendo diferentes por:

  • espacios
  • mayúsculas y minúsculas
  • formato
  • ceros a la izquierda
  • caracteres ocultos

Inspecciona las claves sin correspondencia.

Siguiente paso

Usa el resultado del merge para decidir qué hacer a continuación.

  • El número de filas aumentó de forma inesperada → inspecciona las claves duplicadas y la cardinalidad del join.
  • Demasiadas filas sin correspondencia → compara los dtypes de las claves, el formato, los nulos y la definición de la clave de negocio.
  • Los totales cambiaron de forma inesperada → detente y concilia antes de cualquier agregación.
  • El lado derecho debería ser único → agrega validate="many_to_one" y corrige las infracciones.
  • Necesitas conciliar filas con y sin correspondencia → usa indicator=True.
  • Necesitas el registro vigente más cercano por fecha → usa merge_asof().
  • El join consume mucha memoria → selecciona menos columnas, filtra antes o lleva el join a un motor más potente.
  • El merge es correcto → continúa con la agregación, el filtrado o la validación posterior.

← Todas las guías rápidas