maxframe.dataframe.DataFrame.join#

DataFrame.join(other: DataFrame | Series, on: str = None, how: str = 'left', lsuffix: str = '', rsuffix: str = '', sort: bool = False, method: str = None, auto_merge: str = 'both', auto_merge_threshold: int = 8, bloom_filter: bool | Dict = True, bloom_filter_options: Dict[str, Any] = None, left_hint: JoinHint = None, right_hint: JoinHint = None) → DataFrame#

连接另一个 DataFrame 的列。

将列与 other DataFrame 按索引或键列连接。通过传递一个列表，可以高效地一次性按索引连接多个 DataFrame 对象。

参数:

  • other (DataFrame, Series, or list of DataFrame) -- 索引应与此 DataFrame 中的某一列相似。如果传递的是 Series，则必须设置其 name 属性，该属性将用作结果连接 DataFrame 中的列名。

  • on (str, list of str, or array-like, optional) -- 调用方中用于与 other 中索引连接的列或索引层级名称，否则按索引与索引连接。如果给定多个值，other DataFrame 必须具有 MultiIndex。如果连接键不在调用方 DataFrame 中，可以传递一个数组。类似 Excel 的 VLOOKUP 操作。

  • how ({'left', 'right', 'outer', 'inner'}, default 'left') -- 如何处理两个对象的操作。 * left：使用调用方的索引（如果指定了 on，则使用列） * right：使用 other 的索引。 * outer：将调用方的索引（如果指定了 on，则使用列）与 other 的索引取并集，并按字典序排序。 * inner：将调用方的索引（如果指定了 on，则使用列）与 other 的索引取交集，并保留调用方的顺序。

  • lsuffix (str, default '') -- 来自左框中重叠列的后缀。

  • rsuffix (str, default '') -- 来自右框中重叠列的后缀。

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

  • method ({"shuffle", "broadcast"}, default None) -- 当一个 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) -- 左侧 DataFrame 使用的连接策略。当出现数据倾斜时，可以考虑使用这些策略来避免长尾问题，但应谨慎使用以防止内存溢出和不必要的开销。

  • right_hint (JoinHint, default None) -- 右侧 DataFrame 使用的连接策略。

返回:

一个包含调用者和 other 列的 DataFrame。

返回类型:

DataFrame

参见

DataFrame.merge

用于列与列之间的操作。

示例

>>> import maxframe.dataframe as md
>>> df = md.DataFrame({'key': ['K0', 'K1', 'K2', 'K3', 'K4', 'K5'],
...                    'A': ['A0', 'A1', 'A2', 'A3', 'A4', 'A5']})

>>> df.execute()
  key   A
0  K0  A0
1  K1  A1
2  K2  A2
3  K3  A3
4  K4  A4
5  K5  A5

>>> other = md.DataFrame({'key': ['K0', 'K1', 'K2'],
...                       'B': ['B0', 'B1', 'B2']})

>>> other.execute()
  key   B
0  K0  B0
1  K1  B1
2  K2  B2

使用索引连接 DataFrame。

>>> df.join(other, lsuffix='_caller', rsuffix='_other').execute()
  key_caller   A key_other    B
0         K0  A0        K0   B0
1         K1  A1        K1   B1
2         K2  A2        K2   B2
3         K3  A3       NaN  NaN
4         K4  A4       NaN  NaN
5         K5  A5       NaN  NaN

如果我们想使用关键列进行连接，则需要将 df 和 other 中的关键列设为索引。连接后的 DataFrame 将以该关键列为索引。

>>> df.set_index('key').join(other.set_index('key')).execute()
      A    B
key
K0   A0   B0
K1   A1   B1
K2   A2   B2
K3   A3  NaN
K4   A4  NaN
K5   A5  NaN

另一种使用关键列进行连接的方法是使用 on 参数。DataFrame.join 总是使用 other 的索引，但我们可以使用 df 中的任意列。此方法会在结果中保留原始 DataFrame 的索引。

>>> df.join(other.set_index('key'), on='key').execute()
  key   A    B
0  K0  A0   B0
1  K1  A1   B1
2  K2  A2   B2
3  K3  A3  NaN
4  K4  A4  NaN
5  K5  A5  NaN

使用非唯一键值可以展示它们是如何匹配的。

>>> df = md.DataFrame({'key': ['K0', 'K1', 'K1', 'K3', 'K0', 'K1'],
...                    'A': ['A0', 'A1', 'A2', 'A3', 'A4', 'A5']})

>>> df.execute()
  key   A
0  K0  A0
1  K1  A1
2  K1  A2
3  K3  A3
4  K0  A4
5  K1  A5

>>> df.join(other.set_index('key'), on='key').execute()
  key   A    B
0  K0  A0   B0
1  K1  A1   B1
2  K1  A2   B1
3  K3  A3  NaN
4  K0  A4   B0
5  K1  A5   B1