pandas 1.4.2

NotesParametersReturns
merge(left: 'DataFrame | Series', right: 'DataFrame | Series', how: 'str' = 'inner', on: 'IndexLabel | None' = None, left_on: 'IndexLabel | None' = None, right_on: 'IndexLabel | None' = None, left_index: 'bool' = False, right_index: 'bool' = False, sort: 'bool' = False, suffixes: 'Suffixes' = ('_x', '_y'), copy: 'bool' = True, indicator: 'bool' = False, validate: 'str | None' = None) -> 'DataFrame'

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 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. When performing a cross merge, no column specifications to merge on are allowed.

warning

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

Notes

Support for specifying index levels as the :None:None:`on`, :None:None:`left_on`, and :None:None:`right_on` parameters was added in version 0.23.0 Support for merging named Series objects was added in version 0.24.0

Parameters

left : DataFrame
right : DataFrame or named Series

Object to merge with.

how : {'left', 'right', 'outer', 'inner', 'cross'}, 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 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.

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

    versionadded
on : label or list

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

left_on : label or list, or array-like

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

right_on : label or list, or array-like

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.

left_index : bool, default False

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.

right_index : bool, default False

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

sort : bool, 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).

suffixes : list-like, default is ("_x", "_y")

A length-2 sequence where each element is optionally a string indicating the suffix to add to overlapping column names in :None:None:`left` and :None:None:`right` respectively. Pass a value of :None:None:`None` instead of a string to indicate that the column name from :None:None:`left` or :None:None:`right` should be left as-is, with no suffix. At least one of the values must not be None.

copy : bool, default True

If False, avoid copy if possible.

indicator : bool or str, default False

If True, adds a column to the output DataFrame called "_merge" with information on the source of each row. The column can be given a different name by providing a string argument. The column will have a Categorical type with the value of "left_only" for observations whose merge key only appears in the left DataFrame, "right_only" for observations whose merge key only appears in the right DataFrame, and "both" if the observation's merge key is found in both DataFrames.

validate : str, optional

If specified, checks if merge is of specified type.

  • "one_to_one" or "11": check if merge keys are unique in both left and right datasets.

  • "one_to_many" or "1m": check if merge keys are unique in left dataset.

  • "many_to_one" or "m1": check if merge keys are unique in right dataset.

  • "many_to_many" or "mm": allowed, but does not result in checks.

Returns

DataFrame

A DataFrame of the two merged objects.

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

See Also

DataFrame.join

Similar method using indices.

merge_asof

Merge on nearest keys.

merge_ordered

Merge with optional filling/interpolation.

Examples

This example is valid syntax, but we were not able to check execution
>>> 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 value 0 foo 1 1 bar 2 2 baz 3 3 foo 5
This example is valid syntax, but we were not able to check execution
>>> df2
    rkey value
0   foo      5
1   bar      6
2   baz      7
3   foo      8

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

This example is valid syntax, but we were not able to check execution
>>> df1.merge(df2, left_on='lkey', right_on='rkey')
  lkey  value_x rkey  value_y
0  foo        1  foo        5
1  foo        1  foo        8
2  foo        5  foo        5
3  foo        5  foo        8
4  bar        2  bar        6
5  baz        3  baz        7

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

This example is valid syntax, but we were not able to check execution
>>> df1.merge(df2, left_on='lkey', right_on='rkey',
...  suffixes=('_left', '_right')) lkey value_left rkey value_right 0 foo 1 foo 5 1 foo 1 foo 8 2 foo 5 foo 5 3 foo 5 foo 8 4 bar 2 bar 6 5 baz 3 baz 7

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

This example is valid syntax, but we were not able to check execution
>>> 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')
This example is valid syntax, but we were not able to check execution
>>> df1 = pd.DataFrame({'a': ['foo', 'bar'], 'b': [1, 2]})
... df2 = pd.DataFrame({'a': ['foo', 'baz'], 'c': [3, 4]})
... df1 a b 0 foo 1 1 bar 2
This example is valid syntax, but we were not able to check execution
>>> df2
      a  c
0   foo  3
1   baz  4
This example is valid syntax, but we were not able to check execution
>>> df1.merge(df2, how='inner', on='a')
      a  b  c
0   foo  1  3
This example is valid syntax, but we were not able to check execution
>>> df1.merge(df2, how='left', on='a')
      a  b  c
0   foo  1  3.0
1   bar  2  NaN
This example is valid syntax, but we were not able to check execution
>>> df1 = pd.DataFrame({'left': ['foo', 'bar']})
... df2 = pd.DataFrame({'right': [7, 8]})
... df1 left 0 foo 1 bar
This example is valid syntax, but we were not able to check execution
>>> df2
    right
0   7
1   8
This example is valid syntax, but we were not able to check execution
>>> df1.merge(df2, how='cross')
   left  right
0   foo      7
1   foo      8
2   bar      7
3   bar      8
See :

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them


File: /pandas/core/reshape/merge.py#90
type: <class 'function'>
Commit: