How To Use Pandas Merge() with DataFrame Objects

Graphic of engineers configuring pandas merge at a server terminal to enhance data management

Combining datasets is essential for data analysis tasks at IOFLOOD, and the pandas merge function in Python simplifies this process significantly. Using our experience, we have created this article on the capabilities of Pandas Merge, so that developers and our customers can enhance data integration workflows on their dedicated cloud services.

This article serves as your comprehensive guide on how to use the Pandas Merge function. Whether you’re a novice just getting started or a seasoned data scientist honing your skills, this guide will help you master dataframe merging with pandas.

So, let’s set sail and explore the power of pandas merge!

TL;DR: What is Pandas Merge in Python?

Pandas Merge is a function in the Pandas library that allows you to combine two dataframes based on a common key. It is used with the basic syntax, dataframe1.merge(dataframe2, on='key'). This powerful feature simplifies data analysis by organizing data from different sources into a single, structured dataframe. For a more in-depth understanding and advanced methods, continue reading the article.

Here’s an example:

import pandas as pd

# Define two dataframes
df1 = pd.DataFrame({'key': ['A', 'B', 'C', 'D'],
                    'value': range(1, 5)})

df2 = pd.DataFrame({'key': ['B', 'D', 'D', 'E'],
                    'value': range(5, 9)})

# Merge dataframes on the 'key'
df_merged = df1.merge(df2, on='key')


# Output:
#  key  value_x  value_y
# 0   B        2        5
# 1   D        4        6
# 2   D        4        7

In this example, two data frames (df1 and df2) are merged based on their common key. The resulting data frame includes rows with keys that are common to both data frames. The '_x' and '_y' suffixes indicate which dataframe the values came from.

This merge used an inner join, which only includes common keys. Other types of pandas joins (like outer, left, or right) can include keys not commonly found in either or both data frames.

Basics of the Merge() Function

At its core, Pandas merge is a function that fuses two dataframes based on a shared key. To put it simply, consider it as a process of joining two tables in a database.

The fundamental syntax is as follows:

df_merged = df1.merge(df2, on='common_key')

In this snippet, df1 and df2 are the dataframes you intend to merge, and ‘common_key’ is the column they both share. The outcome, df_merged, is a newly formed dataframe that comprises all the rows from df1 and df2 where the ‘common_key’ matches.

Let’s illustrate this with another example. Assume you possess two dataframes, df1 and df2, which encapsulate information about products and their respective prices. You can merge these dataframes to obtain a comprehensive view of each product along with its price:

df1 = pd.DataFrame({'Product': ['A', 'B', 'C'], 'Category': ['Electronics', 'Clothing', 'Groceries']})
df2 = pd.DataFrame({'Product': ['A', 'B', 'C'], 'Price': [100, 200, 300]})
df_merged = df1.merge(df2, on='Product')


The expected outputs for the three print commands would be as follows:


# Output
  Product     Category
0       A  Electronics
1       B     Clothing
2       C    Groceries


# Output
  Product  Price
0       A    100
1       B    200
2       C    300


# Output
  Product     Category  Price
0       A  Electronics    100
1       B     Clothing    200
2       C    Groceries    300

In this example, each product is associated with a category in df1 and a price in df2. The merged dataframe, df_merged, provides a combined view, linking each product with both its category and price. The df_merged dataframe now consolidates the product, its category, and its price, all under one roof.

While this demonstrates a simple application, pandas merge is capable of much more. It supports a variety of merges, including inner, outer, left, and right, each of which can yield different outcomes. An inner merge, for instance, only includes rows where the key is present in both dataframes, whereas an outer merge encompasses all rows from both dataframes, substituting missing values with NaN.

Beyond Basics: Merge Parameters

While the fundamental usage of pandas merge is simple, the function provides a plethora of parameters that enable more intricate and flexible merges.

One such parameter is how, which dictates the type of merge to be performed. It can take values ‘left’, ‘right’, ‘outer’, and ‘inner’, each resulting in a distinct output. Another pivotal parameter is on, which designates the column or columns to join on. If you need to merge on multiple columns, you can pass a list of column names to this parameter.

Left Merge

The ‘left’ merge gives you all the rows from the first (left) dataframe, along with any matching rows from the second (right) dataframe. If there is no match from df2, you will get NaN.

import pandas as pd

# Define the dataframes
df1 = pd.DataFrame({'key': ['A', 'B', 'C', 'D'], 'value1': list(range(4))})
df2 = pd.DataFrame({'key': ['B', 'D', 'E', 'F'], 'value2': list(range(4,8))})

# Perform and print the merge
left_merge = df1.merge(df2, on='key', how='left')


  key  value1  value2
0   A       0     NaN
1   B       1     4.0
2   C       2     NaN
3   D       3     5.0

In this example, we can see that keys ‘E’ and ‘F’ from df2 aren’t included in the result since they don’t exist in df1 (left dataframe).

Right Merge

The ‘right’ merge gives you all the rows from the second (right) dataframe, along with any matching rows from the first (left) dataframe.

# Perform and print the merge
right_merge = df1.merge(df2, on='key', how='right')


  key  value1  value2
0   B     1.0       4
1   D     3.0       5
2   E     NaN       6
3   F     NaN       7

Here, any keys from df1 which don’t exist in df2 (e.g. ‘A’ and ‘C’) aren’t returned in the result.

Outer Merge

The ‘outer’ merge combines all rows from both dataframes, and fills in NaN for missing matches on either side.

# Perform and print the merge
outer_merge = df1.merge(df2, on='key', how='outer')


  key  value1  value2
0   A     0.0     NaN
1   B     1.0     4.0
2   C     2.0     NaN
3   D     3.0     5.0
4   E     NaN     6.0
5   F     NaN     7.0

Here, you can see that all keys are included in the result. Where there’s no match from either the left or right dataframe, NaN is filled in.

Inner Merge

The ‘inner’ merge gives only the rows where there is a match in both dataframes.

# Perform and print the merge
inner_merge = df1.merge(df2, on='key', how='inner')


  key  value1  value2
0   B       1       4
1   D       3       5

In this type of merge, only keys ‘B’ and ‘D’ which are common in both dataframes are returned in the output.

Multi index dataframes

Let’s dive into an example of a more complex merge, involving multi-index dataframes. Suppose we have the following two dataframes:

df1 = pd.DataFrame({'key1': ['A', 'B', 'C'], 'key2': ['W', 'X', 'Y'], 'value': [1, 2, 3]})
df1.set_index(['key1', 'key2'], inplace=True)

df2 = pd.DataFrame({'key1': ['B', 'C', 'D'], 'key2': ['X', 'Y', 'Z'], 'value': [4, 5, 6]})
df2.set_index(['key1', 'key2'], inplace=True)

We can fuse these dataframes using the multi-index as follows:

df_merged = pd.merge(df1, df2, left_index=True, right_index=True)


The print commands for the given Python code will generate the following output:


# Output
key1 key2
A    W         1
B    X         2
C    Y         3


# Output
key1 key2
B    X         4
C    Y         5
D    Z         6


# Output
           value_x  value_y
key1 key2
B    X           2        4
C    Y           3        5

The merged dataframe, df_merged, takes the intersection of the two dataframes, df1 and df2, based on their multi-index (key1 and key2). The suffixes '_x' and '_y' identify which dataframe the value columns originated from.

This results in a dataframe that includes rows where the multi-index matches in both dataframes.

Best Practices of Pandas.merge()

While merging dataframes is typically a smooth process, it’s not uncommon to encounter merge conflicts, particularly when dealing with large and complex dataframes. As well, performance can be a concern when dealing with very large data structures.

In this section we go over some of the more common problems and some possible solutions:


A KeyError usually surfaces when you’re trying to execute a merge where the key specified isn’t found in one or both of the dataframes involved in the operation. This could occur due to misspelling a key or by mistakenly offering a key that isn’t present in the dataframe.

To avoid this issue, ensure you double-check the column names before performing the merge operation. In case the keys in both dataframes don’t have the same but correspond to each other, you can specify separate keys for each dataframe using left_on and right_on parameters.

    # Attempt to merge on key
    merged_df = df1.merge(df2, on='key')
except KeyError:
    # Handle the error
    print('Key not found in one or both dataframes')

In the code provided above, the merge operation attempts to merge df1 and df2 on a column named ‘key’. If such a column doesn’t exist in one of the dataframes, a KeyError will be triggered.

Upon catching the error, we print out an error message. To prevent this error, you should always ensure that the specified key exists in both dataframes. If the column exists but bears different names in each dataframe, you can use the left_on and right_on parameters of the merge function to specify each one independently.

For instance, if the keys are named ‘key1’ in df1 and ‘key2’ in df2, you can accomplish the merge like this:

# Correct attempt to merge on different keys
merged_df = df1.merge(df2, left_on='key1', right_on='key2')

By ensuring your keys align or specifying them independently, you can bypass the KeyError issue when merging dataframes.

Missing Values

Merging on keys that have missing values might lead to unexpected results. When a key value is missing in one dataframe, the corresponding rows in the other dataframe might not be included in the merge.

You can address this problem by changing the merge type. Using the how parameter in the merge function allows you to pick a merge strategy that suits your needs.

For example, using a ‘left’ merge ensures all rows from the left dataframe are included, even if there’s no matching key value in the right dataframe.

# Attempt a left merge to include all rows from df1
merged_df = df1.merge(df2, on='key', how='left')

In the code snippet above, even if some values of ‘key’ exist in df1 but not in df2, the result merged_df will still have those rows from df1. The columns of df2 in these rows will have ‘NaN’ values, indicating that no matching data was found in df2.

In essence, using ‘left’ in the how parameter protects the rows of df1 from being excluded due to missing values. Keep this in mind when shaping your merge strategy to avoid lost data.

Using other types for how, such as ‘right’, ‘outer’, or ‘inner’, will provide different results and should be chosen based on your specific data requirements. ‘right’ behaves similarly to ‘left’, but protects df2 instead, ‘outer’ includes all rows from both dataframes, and ‘inner’ includes only rows with keys in both dataframes.

Data Type Discrepancies

When you’re merging two dataframes on a particular key, differences in data types between the key columns can cause problems. If the keys in your dataframes have different data types, pandas might not match the values correctly, leading to inaccurate merges.

One way to address this problem is to ensure the key columns have the same data type in both dataframes prior to merging.

# Convert the data type of key columns in both dataframes to string
df1['key'] = df1['key'].astype(str)
df2['key'] = df2['key'].astype(str)

# Attempt to merge the dataframes on the key
merged_df = df1.merge(df2, on='key')

In the example above, the key column in both dataframes is converted to the str type using the astype method. After this conversion, when the dataframes are merged, pandas can accurately match rows based on the key, even if the original data types were different.

A variety of data type conversions may be necessary depending on the specific attributes of your dataframes, and this string conversion is just one common example.

Cross-Validation of Merged Data

Once a merge operation is successfully completed, it’s necessary to validate that the merged dataframe meets your expectations. One way to do this is by cross-validating the resulting merged data.

One simple verification method involves checking the shape of the merged dataframe, specifically its row count. The result should match your understanding based on the merge type and the number of matching keys in the original dataframes.

Here’s how you perform this check:

# Check the shape of the merged dataframe
print("Number of rows and columns in the merged dataframe: ", merged_df.shape)

In the code above, the shape attribute of the dataframe gives us a tuple with the number of rows and columns. If the merge was done correctly, the number of rows should match our expectations based on the inputs and chosen merge type.

Moreover, spot-checking some rows in the merged dataframe can help verify that the data is combined correctly. This involves randomly selecting some rows and manually verifying that the values across both original dataframes were correctly merged.

# Spot-check some rows
print("Random sample of rows from the merged dataframe:n", merged_df.sample(5))

In the code snippet above, sample(5) is used to randomly select 5 rows from the merged dataframe. You can manually trace these records back to their original dataframes to confirm they’ve been combined correctly. Adjust the number in sample() to check more or fewer rows as needed.

By running these checks, you can catch any inconsistencies or errors after the merge operation, ensuring the quality and reliability of your data manipulation.

Ensuring Data Integrity After Merging

Once your dataframes have been successfully merged, it’s essential to carry out data integrity checks. This step ensures the merge operation didn’t introduce any errors, and that the prepared data accurately reflects the intended analysis.

Checking for Duplicate Rows

One check is to identify any duplicate rows. These could unintentionally inflate your data or cause skewed analyses.

# Checking for duplicate rows in the merged dataframe
duplicate_rows = merged_df.duplicated().sum()
print(f'There are {duplicate_rows} duplicated rows in the merged dataframe.')

In the code snippet above, the duplicated() function is used to create a Boolean series that’s True for every duplicated row and False otherwise, with the sum() function then tallying the True values. If the result is greater than 0, you might need to further investigate why the duplicates arose and if they should be dropped.

Inspecting Merge Results

Another means of validation is cross-checking the merged information against known or expected values.

# Checking the number of occurrences for each value in a specific column
value_counts = merged_df['column'].value_counts()

In the above snippet, the value_counts() function gives us the frequency of each unique value in the specified column of the merged dataframe. It’s a method of basic sanity checking—ensuring that the data in the column aligns with expectations.

Avoiding Unnecessary Sorts

When working with large dataframes, the computational cost of merge operations can be substantial. By default, pandas will try to sort the data while merging, which can be very time-consuming for large dataframes. You can avoid unnecessary computational effort by setting the sort parameter to False.

Here’s an example showcasing this:

# Create large dataframes
df1 = pd.DataFrame({'key': range(1000000), 'value': range(1000000)})
df2 = pd.DataFrame({'key': range(999999, -1, -1), 'value': range(1000000)})

# Merge dataframes without sorting
merged_df = pd.merge(df1, df2, on='key', sort=False)

In the code snippet above, we created two large dataframes df1 and df2 each with a million entries. df1 is sorted in ascending order while df2 is sorted in descending order on ‘key’. By setting sort=False while merging, we’re telling pandas not to sort the final dataframe on the ‘key’ column. Please note that the rows of merged_df will appear in the order they appear in df1 (i.e., sorted on ‘key’ in ascending order) as pandas preserves the order of the left dataframe rows.

This practice can significantly improve performance during merge operations, facilitating faster and more efficient data manipulation, especially with large-scale data.

Alternative Methods and Techniques

There are additional pandas functions that work well for combining dataframes, with varying utility depending on your specific needs. Below, we’ll discuss the join and concat functions.

Each of these functions – merge, join, and concat – has a unique use case in pandas, and understanding when and how to use each can significantly enhance your data manipulation capabilities in Python.

The Join Function

Pandas join is a convenient method to combine two dataframes based on their indexes or columns. It’s essentially a way to join on indexes rather than columns.

# Create two dataframes
df1 = pd.DataFrame({'A': ['A0', 'A1', 'A2']},
                   index=['K0', 'K1', 'K2'])

df2 = pd.DataFrame({'B': ['B0', 'B1', 'B2']},
                   index=['K0', 'K2', 'K3'])

# Join the dataframes
joined_df = df1.join(df2, how='outer')



     A    B
K0  A0   B0
K1  A1  NaN
K2  A2   B1
K3 NaN   B2

In this code, we’ve created two dataframes, df1 and df2, both with three entries but with different indexes. We’ve then used the join function to combine them.

Because we used how='outer', all keys from both dataframes are included in the output, with NaN filling in for missing data. If we were to use how='inner', only the common keys, ‘K0’ and ‘K2’, would be included.

The Concat Function

The concat function in pandas is used to append dataframes along a particular axis (either rows or columns). This can be handy when you have dataframes of similar structures and need to combine them.

# Create two dataframes
df1 = pd.DataFrame({'A': ['A0', 'A1', 'A2'],
                    'B': ['B0', 'B1', 'B2']},
                   index=['K0', 'K1', 'K2'])

df2 = pd.DataFrame({'A': ['A3', 'A4', 'A5'],
                    'B': ['B3', 'B4', 'B5']},
                   index=['K3', 'K4', 'K5'])

# Concatenate the dataframes
concat_df = pd.concat([df1, df2])



    A   B
K0  A0  B0
K1  A1  B1
K2  A2  B2
K3  A3  B3
K4  A4  B4
K5  A5  B5

In the code above, we’ve defined 2 dataframes, df1 and df2, each with similar structure. Using pd.concat([df1, df2]), we appended df2 below df1 along the row axis (axis=0), yielding a single dataframe that maintains the structure of the original dataframes.

Remember that when concatenating along the column axis (axis=1), the dataframes must have the same row index. Otherwise, NaN values would be filled for non-overlapping indexes.

Pandas Functions and Data Analysis

While merging is a pivotal aspect of data manipulation in pandas, it’s merely a single facet of the multifaceted gem that is pandas. This Python library offers an array of other functions that are instrumental for data manipulation and analysis.

Functions like groupby, pivot, melt, and apply hold equal importance and when combined with merge, can facilitate more advanced data analysis.

For instance, post merging two dataframes, you might require to group the data based on certain parameters to execute aggregated calculations.

Here, the groupby function proves to be a valuable tool. Similarly, the pivot function can be utilized to reshape the data, simplifying the analysis process.

groupbyGroup the data based on certain parameters to execute aggregated calculations.
pivotReshape the data, simplifying the analysis process.
meltTransform or reshape data.
applyApply a function along an axis of the DataFrame. | When these functions are used in tandem with merge, they can significantly enhance your data analysis capabilities.

Pandas plays a central role in data analysis in Python. It offers a flexible and efficient data structure (the DataFrame) along with an extensive range of functions for data manipulation and analysis. Whether your task involves cleaning data, transforming data, visualizing data, or building models, pandas is a reliable ally.

Other Data Handling Libraries

While pandas is a formidable library for data manipulation in Python, it’s not the only tool available. Other libraries like NumPy, SciPy, and Dask offer different functionalities for data manipulation and analysis.

  • NumPy, for instance, provides support for large multi-dimensional arrays and matrices, along with a collection of mathematical functions to operate on these arrays.

  • SciPy builds on the capabilities of NumPy and provides additional functionalities for scientific computing, such as modules for optimization, linear algebra, integration, interpolation, and more.

  • Dask, on the other hand, is useful for parallel computing, enabling you to work with larger datasets that don’t fit into memory.

  • Beyond Python, SQL is another potent tool for data merging. SQL’s JOIN operation is similar to pandas merge, but it operates directly on database tables.

While pandas performs operations in-memory, SQL operations are performed in the database, making it more suitable for large datasets that don’t fit into memory. However, pandas offers more flexibility in data manipulation and is more convenient for complex data analysis tasks.

  • Tools like Apache Hadoop and Apache Spark can handle large datasets distributed across clusters of computers.
NumPyProvides support for large multi-dimensional arrays and matrices.
SciPyProvides additional functionalities for scientific computing.
DaskUseful for parallel computing, enabling you to work with larger datasets that don’t fit into memory.
SQLOperates directly on database tables, more suitable for large datasets that don’t fit into memory.
Apache HadoopCan handle large datasets distributed across clusters of computers.
Apache SparkCan handle large datasets distributed across clusters of computers, provides functions for data merging. | These tools provide their own functions for data merging, designed to operate efficiently on distributed data. While pandas merge is efficient for in-memory computations on single machines, big data technologies are designed to handle much larger datasets.

In the era of big data, efficient data manipulation is more important than ever. As datasets grow in size and complexity, the ability to quickly and efficiently manipulate data is crucial. Tools like pandas merge, along with other data manipulation functions in pandas and other libraries, are key to handling this challenge.

Further Resources for Pandas Library

If you’re interested in learning more ways to utilize the Pandas library, here are a few resources that you might find helpful:

Wrapping Up: Merge() Function Guide

In the world of data analysis, pandas merge stands as a potent ally. It allows the combination of dataframes based on a common key, simplifying the process of data manipulation and enhancing our capacity to extract meaningful insights. From straightforward merges to intricate multi-index merges, this function equips us with the flexibility and power needed to handle a diverse range of data analysis tasks.

However, pandas merge is just a single component of a much larger framework. It’s a vital element in the pandas library, a library that boasts a plethora of other functions for data manipulation and analysis. When used in conjunction with functions like groupby, pivot, melt, and apply, pandas merge transforms into an even more formidable tool, enabling us to perform advanced and complex data analysis.

Beyond pandas, there are other libraries in Python, as well as tools like SQL and big data technologies, that offer different functionalities for data manipulation. By exploring these tools and understanding their strengths and weaknesses, we can expand our data manipulation skills and become more effective data analysts or data scientists.

As data continues to grow in importance and complexity, the tools we use to manipulate and analyze this data will become even more essential. By mastering pandas merge and other data manipulation functions, we’re not just enhancing our skills for today, but we’re preparing ourselves for the future of data analysis. So keep exploring, keep learning, and stay ahead of the curve!