14.3 join()

说明

DataFrame.join() 是 merge() 基于索引的便捷接口，用于按索引（或列）连接两个数据集，代码更简洁。

语法

DataFrame.join(
    other,               # 要连接的 DataFrame / Series / 可迭代对象列表
    on=None,             # 左侧用于连接的列（默认使用索引）
    how='left',          # 连接方式
    lsuffix='',          # 左侧重叠列后缀
    rsuffix='',          # 右侧重叠列后缀
    sort=False,          # 是否按键排序
    validate=None,       # 关系校验
)

参数说明

参数	说明
other	右侧对象，可为 DataFrame、带 name 的 Series，或二者组成的列表
on	左侧列名，用于替代左侧索引作为连接键
how	同 merge()：'left'、'right'、'outer'、'inner'、'cross'
lsuffix / rsuffix	列名重叠时自动添加的后缀。on=None 且存在重叠时必须指定
sort	结果是否按键排序
validate	同 merge() 的校验选项

基础用法：索引对索引

import pandas as pd
 
left = pd.DataFrame({'A': [1, 2]}, index=['x', 'y'])
right = pd.DataFrame({'B': [10, 20]}, index=['x', 'z'])
 
print(left.join(right))
#    A     B
# x  1  10.0
# y  2   NaN
 
print(left.join(right, how='outer'))
#    A     B
# x  1.0  10.0
# y  2.0   NaN
# z  NaN  20.0
 
print(left.join(right, how='inner'))
#    A   B
# x  1  10

on 参数：左侧指定列

left = pd.DataFrame({'key': ['a', 'b'], 'A': [1, 2]})
right = pd.DataFrame({'B': [10, 20]}, index=['a', 'b'])
 
print(left.join(right, on='key'))
#   key  A   B
# 0   a  1  10
# 1   b  2  20

suffixes：重叠列处理

必须指定后缀

当 on=None（使用索引）且两侧存在同名非键列时，join() 要求显式提供 lsuffix / rsuffix，否则抛出异常。

left = pd.DataFrame({'val': [1, 2]}, index=['a', 'b'])
right = pd.DataFrame({'val': [10, 20]}, index=['a', 'c'])
 
print(left.join(right, lsuffix='_left', rsuffix='_right'))
#    val_left  val_right
# a         1       10.0
# b         2        NaN
 
# 使用 merge 则可通过 suffixes 参数自行控制
print(pd.merge(left, right, left_index=True, right_index=True, suffixes=('_L', '_R')))

多个对象连接

left = pd.DataFrame({'A': [1, 2]}, index=['x', 'y'])
r1 = pd.DataFrame({'B': [10]}, index=['x'])
r2 = pd.DataFrame({'C': [100]}, index=['x'])
 
print(left.join([r1, r2]))
#    A     B      C
# x  1  10.0  100.0
# y  2   NaN    NaN

Series.join 与 Index.join

说明

Series 和 Index 也有 join 方法，但用法与语义不同。

# Index.join：返回索引元组
idx1 = pd.Index(['a', 'b'])
idx2 = pd.Index(['b', 'c'])
print(idx1.join(idx2, how='outer'))
# Index(['a', 'b', 'c'], dtype='object')
 
# Series.join 与 DataFrame.join 相同，other 可为 Series
s1 = pd.Series([1, 2], index=['a', 'b'], name='s1')
s2 = pd.Series([10, 20], index=['a', 'c'], name='s2')
print(s1.join(s2, how='outer'))
#      s1    s2
# a   1.0  10.0
# b   2.0   NaN
# c   NaN  20.0

join vs merge

选择建议

• 按索引连接数据时，join() 更简洁。
• 需要指定不同键列、使用 indicator 或 validate 时，merge() 更灵活。
• join() 的 on 参数使得“左侧按列 + 右侧按索引”非常方便。

🔗 相关链接

• 14.2 merge() - 完整参数与数据库风格合并
• 五、数据选择与索引 - 索引操作基础
• 3. Index - Index.join 的索引方法