Pandas: Data Manipulation - merge() function

Last update on August 19 2022 21:50:52 (UTC/GMT +8 hours)

merge() function

The merge() function is used to merge DataFrame or named Series objects with a database-style join.

The join is done on columns or indexes. If joining columns on columns, the DataFrame indexes will be ignored. Otherwise if joining indexes on indexes or indexes on a column or columns, the index will be passed on.

Syntax:

pandas.merge(left, right, how='inner', on=None, left_on=None, right_on=None, left_index=False, right_index=False, sort=False, suffixes=('_x', '_y'), copy=True, indicator=False, validate=None)

Parameters:

Name	Description	Type	Default	Required / Optional
left	The given DataFrame.	DataFrame		Required
right	The given DataFrame or named Series..	DataFrame or named Series		Required
how	Type of merge to be performed. left: use only keys from left frame, similar to a SQL left outer join; preserve key order. right: use only keys from right frame, similar to a SQL right outer join; preserve key order. outer: use union of keys from both frames, similar to a SQL full outer join; sort keys lexicographically. inner: use intersection of keys from both frames, similar to a SQL inner join; preserve the order of the left keys.	{‘left’, ‘right’, ‘outer’, ‘inner’}	Default: ‘inner’	Required
on	Column or index level names to join on. These must be found in both DataFrames. If on is None and not merging on indexes then this defaults to the intersection of the columns in both DataFrames.	label or list		Optional
left_on	Column or index level names to join on. These must be found in both DataFrames. If on is None and not merging on indexes then this defaults to the intersection of the columns in both DataFrames.	label or list, or array-like		Optional
right_on	Column or index level names to join on in the right DataFrame. Can also be an array or list of arrays of the length of the right DataFrame. These arrays are treated as if they are columns.	label or list, or array-like		Optional
left_index	Use the index from the left DataFrame as the join key(s). If it is a MultiIndex, the number of keys in the other DataFrame (either the index or a number of columns) must match the number of levels.	bool	Default: False	Optional
right_index	Use the index from the right DataFrame as the join key. Same caveats as left_index.	bool	Default: False	Optional
sort	Sort the join keys lexicographically in the result DataFrame. If False, the order of the join keys depends on the join type (how keyword).	bool	Default: False	Optional
suffixes	Suffix to apply to overlapping column names in the left and right side, respectively. To raise an exception on overlapping columns use (False, False).	tuple of (str, str)	Default: (‘_x’, ‘_y’)	Optional
copy	If False, avoid copy if possible.	bool	Default: True	Optional
indicator	If True, adds a column to output DataFrame called "_merge" with information on the source of each row. If string, column with information on source of each row will be added to output DataFrame, and column will be named value of string.	bool or str	Default: False	Optional
validate	If specified, checks if merge is of specified type. “one_to_one” or “1:1”: check if merge keys are unique in both left and right datasets. “one_to_many” or “1:m”: check if merge keys are unique in left dataset. “many_to_one” or “m:1”: check if merge keys are unique in right dataset. “many_to_many” or “m:m”: allowed, but does not result in checks.	str		Optional

Returns: A DataFrame of the two merged objects.

Example:

Download the Pandas DataFrame Notebooks from here.

Previous: qcut() function
Next: merge_ordered() function