Explorar guías rápidas · Python
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
- Problema
- Respuesta rápida
- Código / comandos
- 1. Inner join
- 2. Left join
- 3. Right join
- 4. Full outer join
- 5. Valida la cardinalidad del join
- 6. Comprueba la unicidad de las claves antes del merge
- 7. Join sobre varias columnas
- 8. Join cuando los nombres de las claves son distintos
- 9. Inspecciona las filas sin correspondencia
- 10. Concilia los porcentajes de correspondencia
- 11. Detecta la multiplicación de filas
- 12. Entiende la expansión de muchos a muchos
- 13. Protege los totales posteriores frente a duplicaciones accidentales
- 14. Maneja los nombres de columna coincidentes
- 15. Selecciona solo las columnas necesarias antes del join
- 16. Join mediante índices
- 17. Semi join: conserva las filas izquierdas que tienen correspondencia
- 18. Anti join: conserva las filas izquierdas sin correspondencia
- 19. Join con claves nulas: entiende el comportamiento de pandas
- 20. Comprueba la compatibilidad de los dtypes de las claves del join
- 21. Normaliza las claves de texto con cuidado
- 22. Evita nombres de columna duplicados accidentales antes del merge
- 23. Merge con coincidencias temporales ordenadas mediante merge_asof
- 24. Cross join intencional
- Qué significa el resultado
- Qué revisar
- El left join aumenta el número de filas
- El inner join pierde más filas de lo esperado
- Los totales aumentan después del enriquecimiento
- Muchas filas sin correspondencia
- Aparecen columnas _x y _y por todas partes
- Las claves nulas coinciden de forma inesperada
- Notas de producción
- Valida siempre la cardinalidad esperada
- La conciliación del número de filas debería ser lo normal
- Concilia las medidas importantes
- Selecciona las columnas antes del join
- Los joins de muchos a muchos pueden disparar el uso de memoria
- Los joins de pandas se ejecutan en memoria
- No uses la salida del merge como sustituto de las comprobaciones de calidad de las claves
- Errores comunes
- 1. Hacer el merge sin comprobar la unicidad de las claves
- 2. Usar many_to_many para que la validación pase
- 3. Suponer que un left join preserva el número de filas
- 4. Eliminar duplicados después de un merge incorrecto
- 5. Hacer el join con claves de negocio incompletas
- 6. Ignorar las claves de join nulas
- 7. Depender de _x y _y
- 8. Hacer el join antes de filtrar o proyectar
- 9. Confiar en nombres de dtype coincidentes sin revisar los valores
- Siguiente paso
- 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.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.