pandas.merge#

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=<no_default>,indicator=False,validate=None)[source]#

Merge DataFrame or named Series objects with a database-style join.

A named Series object is treated as a DataFrame with a single named column.

The join is done on columns or indexes. If joining columns oncolumns, the DataFrame indexeswill be ignored. Otherwise if joining indexeson indexes or indexes on a column or columns, the index will be passed on.When performing a cross merge, no column specifications to merge on areallowed.

Warning

If both key columns contain rows where the key is a null value, thoserows will be matched against each other. This is different from usual SQLjoin behaviour and can lead to unexpected results.

Parameters:

leftDataFrame or named Series

First pandas object to merge.

rightDataFrame or named Series

Second pandas object to merge.

how{‘left’, ‘right’, ‘outer’, ‘inner’, ‘cross’, ‘left_anti’, ‘right_anti},

default ‘inner’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 outerjoin; sort keys lexicographically.

• inner: use intersection of keys from both frames, similar to a SQL innerjoin; preserve the order of the left keys.

• cross: creates the cartesian product from both frames, preserves the orderof the left keys.

• left_anti: use only keys from left frame that are not in right frame, similarto SQL left anti join; preserve key order.

• right_anti: use only keys from right frame that are not in left frame, similarto SQL right anti join; preserve key order.

onHashable or a sequence of the previous

Column or index level names to join on. These must be found in bothDataFrames. Ifon is None and not merging on indexes then this defaultsto the intersection of the columns in both DataFrames.

left_onHashable or a sequence of the previous, or array-like

Column or index level names to join on in the left DataFrame. Can alsobe an array or list of arrays of the length of the left DataFrame.These arrays are treated as if they are columns.

right_onHashable or a sequence of the previous, or array-like

Column or index level names to join on in the right DataFrame. Can alsobe an array or list of arrays of the length of the right DataFrame.These arrays are treated as if they are columns.

left_indexbool, default False

Use the index from the left DataFrame as the join key(s). If it is aMultiIndex, the number of keys in the other DataFrame (either the indexor a number of columns) must match the number of levels.

right_indexbool, default False

Use the index from the right DataFrame as the join key. Same caveats asleft_index.

sortbool, default False

Sort the join keys lexicographically in the result DataFrame. If False,the order of the join keys depends on the join type (how keyword).

suffixeslist-like, default is (“_x”, “_y”)

A length-2 sequence where each element is optionally a stringindicating the suffix to add to overlapping column names inleft andright respectively. Pass a value ofNone insteadof a string to indicate that the column name fromleft orright should be left as-is, with no suffix. At least one of thevalues must not be None.

copybool, default False

This keyword is now ignored; changing its value will have noimpact on the method.

Deprecated since version 3.0.0:This keyword is ignored and will be removed in pandas 4.0. Sincepandas 3.0, this method always returns a new object using a lazycopy mechanism that defers copies until necessary(Copy-on-Write). See theuser guide on Copy-on-Writefor more details.

indicatorbool or str, default False

If True, adds a column to the output DataFrame called “_merge” withinformation on the source of each row. The column can be given a differentname by providing a string argument. The column will have a Categoricaltype with the value of “left_only” for observations whose merge key onlyappears in the left DataFrame, “right_only” for observationswhose merge key only appears in the right DataFrame, and “both”if the observation’s merge key is found in both DataFrames.

validatestr, optional

If specified, checks if merge is of specified type.

• “one_to_one” or “1:1”: check if merge keys are unique in bothleft and right datasets.

• “one_to_many” or “1:m”: check if merge keys are unique in leftdataset.

• “many_to_one” or “m:1”: check if merge keys are unique in rightdataset.

• “many_to_many” or “m:m”: allowed, but does not result in checks.

Returns:

DataFrame

A DataFrame of the two merged objects.

See also

merge_ordered

Merge with optional filling/interpolation.

merge_asof

Merge on nearest keys.

DataFrame.join

Similar method using indices.

Examples

>>>df1=pd.DataFrame(...{"lkey":["foo","bar","baz","foo"],"value":[1,2,3,5]}...)>>>df2=pd.DataFrame(...{"rkey":["foo","bar","baz","foo"],"value":[5,6,7,8]}...)>>>df1    lkey value0   foo      11   bar      22   baz      33   foo      5>>>df2    rkey value0   foo      51   bar      62   baz      73   foo      8

Merge df1 and df2 on the lkey and rkey columns. The value columns havethe default suffixes, _x and _y, appended.

>>>df1.merge(df2,left_on="lkey",right_on="rkey")  lkey  value_x rkey  value_y0  foo        1  foo        51  foo        1  foo        82  bar        2  bar        63  baz        3  baz        74  foo        5  foo        55  foo        5  foo        8

Merge DataFrames df1 and df2 with specified left and right suffixesappended to any overlapping columns.

>>>df1.merge(df2,left_on="lkey",right_on="rkey",suffixes=("_left","_right"))  lkey  value_left rkey  value_right0  foo           1  foo            51  foo           1  foo            82  bar           2  bar            63  baz           3  baz            74  foo           5  foo            55  foo           5  foo            8

Merge DataFrames df1 and df2, but raise an exception if the DataFrames haveany overlapping columns.

>>>df1.merge(df2,left_on="lkey",right_on="rkey",suffixes=(False,False))Traceback (most recent call last):...ValueError:columns overlap but no suffix specified:    Index(['value'], dtype='object')

>>>df1=pd.DataFrame({"a":["foo","bar"],"b":[1,2]})>>>df2=pd.DataFrame({"a":["foo","baz"],"c":[3,4]})>>>df1      a  b0   foo  11   bar  2>>>df2      a  c0   foo  31   baz  4

>>>df1.merge(df2,how="inner",on="a")      a  b  c0   foo  1  3

>>>df1.merge(df2,how="left",on="a")      a  b  c0   foo  1  3.01   bar  2  NaN

>>>df1=pd.DataFrame({"left":["foo","bar"]})>>>df2=pd.DataFrame({"right":[7,8]})>>>df1    left0   foo1   bar>>>df2    right0   71   8

>>>df1.merge(df2,how="cross")   left  right0   foo      71   foo      82   bar      73   bar      8