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)[源代码][源代码]#

使用数据库风格的连接合并 DataFrame 或命名 Series 对象。

一个命名的 Series 对象被视为一个具有单个命名列的 DataFrame。

连接是在列或索引上完成的。如果在列上连接列，DataFrame 索引 将被忽略。否则，如果在索引上连接索引或索引在列上，索引将被传递。在进行交叉合并时，不允许指定要合并的列。

警告

如果两个键列都包含键为空值的行，这些行将相互匹配。这与通常的SQL连接行为不同，可能会导致意外的结果。

参数:

左DataFrame 或命名 Series

第一个要合并的 pandas 对象。

右DataFrame 或命名 Series

第二个要合并的 pandas 对象。

如何{‘left’, ‘right’, ‘outer’, ‘inner’, ‘cross’}，默认 ‘inner’

要执行的合并类型。

left: 仅使用左框架中的键，类似于SQL左外连接；保留键顺序。
right: 仅使用右帧中的键，类似于SQL的右外连接；保留键的顺序。
outer: 使用两个帧的键的并集，类似于SQL的全外连接；按字典顺序排序键。
inner: 使用两个帧键的交集，类似于SQL内连接；保留左边键的顺序。
cross: 从两个数据框创建笛卡尔积，保留左侧键的顺序。

开标签或列表

要连接的列或索引级别名称。这些必须同时存在于两个 DataFrame 中。如果 on 为 None 且不基于索引进行合并，则默认使用两个 DataFrame 列的交集。

left_on标签或列表，或类似数组

在左 DataFrame 中用于连接的列或索引级别名称。也可以是与左 DataFrame 长度相同的数组或数组列表。这些数组被视为列。

right_on标签或列表，或类似数组

在右 DataFrame 中用于连接的列或索引级别名称。也可以是长度与右 DataFrame 相同的数组或数组列表。这些数组被视为列。

left_index布尔值, 默认为 False

使用左侧DataFrame的索引作为连接键。如果是MultiIndex，另一个DataFrame中的键数（无论是索引还是若干列）必须与级别数匹配。

right_index布尔值, 默认为 False

使用右侧DataFrame的索引作为连接键。与left_index相同的注意事项。

排序布尔值, 默认为 False

在结果 DataFrame 中按字典顺序排序连接键。如果为 False，则连接键的顺序取决于连接类型（how 关键字）。

后缀类似列表，默认是 (“_x”, “_y”)

一个长度为2的序列，其中每个元素可以是一个字符串，分别指示在 left 和 right 中重叠列名后添加的后缀。传递一个值 None 而不是字符串，以指示应保留 left 或 right 的列名，不添加后缀。至少一个值不能为 None。

复制布尔值, 默认为 False

如果为 False，尽量避免复制。

备注

copy 关键字将在 pandas 3.0 中更改行为。写时复制将默认启用，这意味着所有带有 copy 关键字的方法将使用延迟复制机制来推迟复制并忽略 copy 关键字。copy 关键字将在 pandas 的未来版本中被移除。

通过启用写时复制 pd.options.mode.copy_on_write = True，您已经可以获得未来的行为和改进。

自 3.0.0 版本弃用.

指示器布尔值或字符串，默认 False

如果为真，则在输出 DataFrame 中添加一列名为 “_merge” 的列，该列提供每行来源的信息。可以通过提供一个字符串参数来给该列赋予不同的名称。该列将具有一个分类类型，其值为 “left_only” 表示合并键仅出现在左 DataFrame 中的观察值，”right_only” 表示合并键仅出现在右 DataFrame 中的观察值，如果观察值的合并键在两个 DataFrame 中都找到，则为 “both”。

验证str, 可选

如果指定，检查合并是否为指定类型。

“one_to_one” 或 “1:1”: 检查合并键在左右数据集中是否唯一。
“one_to_many” 或 “1:m”: 检查左数据集中的合并键是否唯一。
“many_to_one” 或 “m:1”: 检查右侧数据集中的合并键是否唯一。
“many_to_many” 或 “m:m”: 允许，但不会导致检查。

返回:

DataFrame: 两个合并对象的 DataFrame。

参见

merge_ordered: 带有可选填充/插值的合并。
merge_asof: 在最近的键上合并。
DataFrame.join: 使用索引的类似方法。

例子

>>> 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
>>> df2
    rkey value
0   foo      5
1   bar      6
2   baz      7
3   foo      8

合并 df1 和 df2 在 lkey 和 rkey 列上。值列附加了默认的后缀，_x 和 _y。

>>> df1.merge(df2, left_on="lkey", right_on="rkey")
  lkey  value_x rkey  value_y
foo        1  foo        5
foo        1  foo        8
bar        2  bar        6
baz        3  baz        7
foo        5  foo        5
foo        5  foo        8

合并 DataFrame df1 和 df2，并在任何重叠列上附加指定的左后缀和右后缀。

>>> df1.merge(df2, left_on="lkey", right_on="rkey", suffixes=("_left", "_right"))
  lkey  value_left rkey  value_right
foo           1  foo            5
foo           1  foo            8
bar           2  bar            6
baz           3  baz            7
foo           5  foo            5
foo           5  foo            8

合并 DataFrame df1 和 df2，但如果 DataFrame 有任何重叠的列，则引发异常。

>>> 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  b
0   foo  1
1   bar  2
>>> df2
      a  c
0   foo  3
1   baz  4

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

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

>>> df1 = pd.DataFrame({"left": ["foo", "bar"]})
>>> df2 = pd.DataFrame({"right": [7, 8]})
>>> df1
    left
0   foo
1   bar
>>> df2
    right
0   7
1   8

>>> df1.merge(df2, how="cross")
   left  right
0   foo      7
1   foo      8
2   bar      7
3   bar      8