maxframe.dataframe.DataFrame.merge#

DataFrame.merge(right: DataFrame | Series, how: str = 'inner', on: str | List[str] = None, left_on: str = None, right_on: str = None, left_index: bool = False, right_index: bool = False, sort: bool = False, suffixes: Tuple[str | None, str | None] = ('_x', '_y'), copy: bool = True, indicator: bool = False, validate: str = None, method: str = 'auto', auto_merge: str = 'both', auto_merge_threshold: int = 8, bloom_filter: bool | str = 'auto', bloom_filter_options: Dict[str, Any] = None, left_hint: JoinHint = None, right_hint: JoinHint = None) → DataFrame#

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

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

连接操作在列或索引上进行。如果列与列连接，则 DataFrame 的索引*将被忽略*。否则，如果索引与索引连接，或索引与列连接，则索引将被传递下去。执行交叉合并时，不允许指定列进行合并。

参数:

  • right (DataFrame or named Series) -- 要合并的对象。

  • how ({'left', 'right', 'outer', 'inner'}, default 'inner') -- 要执行的合并类型。 * left：仅使用左框架中的键，类似于 SQL 左外连接；保留键的顺序。 * right：仅使用右框架中的键，类似于 SQL 右外连接；保留键的顺序。 * outer：使用两个框架中键的并集，类似于 SQL 全外连接；按键的字典序排序。 * inner：使用两个框架中键的交集，类似于 SQL 内连接；保留左键的顺序。

  • on (label or list) -- 要连接的列或索引级别的名称。这些必须在两个 DataFrame 中都存在。如果 on 为 None 且不基于索引合并，则默认为两个 DataFrame 中列的交集。

  • left_on (label or list, or array-like) -- 左侧 DataFrame 中要连接的列或索引级别的名称。也可以是与左侧 DataFrame 长度相同的数组或数组列表。这些数组被视为列。

  • right_on (label or list, or array-like) -- 右侧 DataFrame 中要连接的列或索引级别的名称。也可以是与右侧 DataFrame 长度相同的数组或数组列表。这些数组被视为列。

  • left_index (bool, default False) -- 使用左侧 DataFrame 的索引作为连接键。如果它是 MultiIndex，则另一个 DataFrame 中的键（索引或多个列）的数量必须与层级数匹配。

  • right_index (bool, default False) -- 使用右侧 DataFrame 的索引作为连接键。注意事项与 left_index 相同。

  • sort (bool, default False) -- 在结果 DataFrame 中按键的字典序对连接键进行排序。如果为 False，则连接键的顺序取决于连接类型（how 关键字）。

  • suffixes (list-like, default is ("_x", "_y")) -- 一个长度为 2 的序列，其中每个元素是一个可选的字符串，指示分别添加到 left 和 right 中重叠列名的后缀。传递 None 而不是字符串，表示 left 或 right 中的列名应保持不变，不添加后缀。至少有一个值不能为 None。

  • copy (bool, default True) -- 如果为 False，则尽可能避免复制。

  • indicator (bool or str, default False) -- 如果为 True，则向输出 DataFrame 添加一列名为 "_merge" 的列，包含每行来源的信息。可以通过提供字符串参数为该列指定不同的名称。该列将具有分类类型，对于合并键仅出现在左 DataFrame 中的观测值，其值为 "left_only"；对于合并键仅出现在右 DataFrame 中的观测值，其值为 "right_only"；如果合并键在两个 DataFrame 中都存在，则为 "both"。

  • validate (str, optional) -- 如果指定，则检查合并是否为指定类型。 * "one_to_one" 或 "1:1"：检查合并键在左和右数据集中是否唯一。 * "one_to_many" 或 "1:m"：检查合并键在左数据集中是否唯一。 * "many_to_one" 或 "m:1"：检查合并键在右数据集中是否唯一。 * "many_to_many" 或 "m:m"：允许，但不进行检查。

  • method ({"auto", "shuffle", "broadcast"}, default auto) -- 当一个 DataFrame 明显小于另一个时，建议使用 "broadcast"，否则 "shuffle" 是更好的选择。默认情况下，我们根据实际数据大小选择方法。

  • auto_merge ({"both", "none", "before", "after"}, default both) -- 在合并前或合并后自动合并小块 * "both"：在合并前后都自动合并小块， * "none"：不合并小块 * "before"：仅在合并前合并小块 * "after"：仅在合并后合并小块

  • auto_merge_threshold (int, default 8) -- 当 how 为 "inner" 时，合并结果可能远小于原始 DataFrame，如果块的数量超过阈值，它将自动合并小块。

  • bloom_filter (bool, str, default "auto") -- 使用布隆过滤器优化合并

  • bloom_filter_options (dict) --

    • "max_elements": 布隆过滤器中的最大元素数，默认值是所有输入块的最大大小

    • "error_rate": 错误率，默认 0.1。

    • "apply_chunk_size_threshold": 应用布隆过滤器的最小块大小，默认 10 当左右块大小超过此阈值时应用布隆过滤器

    • "filter": "large", "small", "both"，默认 "large" 决定在大、小或两个 DataFrame 上进行过滤。

  • left_hint (JoinHint, default None) -- 用于左表的连接策略。当出现数据倾斜时，考虑使用这些策略以避免长尾问题，但请谨慎使用以防止内存溢出和不必要的开销。

  • right_hint (JoinHint, default None) -- 用于右表的连接策略。

返回:

两个合并对象的 DataFrame。

返回类型:

DataFrame

示例

>>> import maxframe.dataframe as md
>>> df1 = md.DataFrame({'lkey': ['foo', 'bar', 'baz', 'foo'],
...                     'value': [1, 2, 3, 5]})
>>> df2 = md.DataFrame({'rkey': ['foo', 'bar', 'baz', 'foo'],
...                     'value': [5, 6, 7, 8]})
>>> df1.execute()
    lkey value
0   foo      1
1   bar      2
2   baz      3
3   foo      5
>>> df2.execute()
    rkey value
0   foo      5
1   bar      6
2   baz      7
3   foo      8

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

>>> df1.merge(df2, left_on='lkey', right_on='rkey').execute()
  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

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

>>> df1.merge(df2, left_on='lkey', right_on='rkey',
...           suffixes=('_left', '_right')).execute()
  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

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

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

>>> df1 = md.DataFrame({'a': ['foo', 'bar'], 'b': [1, 2]})
>>> df2 = md.DataFrame({'a': ['foo', 'baz'], 'c': [3, 4]})
>>> df1.execute()
      a  b
0   foo  1
1   bar  2
>>> df2.execute()
      a  c
0   foo  3
1   baz  4

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

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