Pandas DataFrame 包含判断：isin、merge 与集合运算选型指南

1. 为什么“判断一个 DataFrame 是否包含在另一个 DataFrame 中”是个高频刚需

做数据清洗和比对的人，几乎都绕不开一个场景：手上有两张表，一张是主表，一张是参照表，需要快速知道主表里的某些行、某些列组合，到底有没有在参照表里出现过。这个需求听起来简单，但真正动手写的时候，坑比想象中多得多。

我最早接触这类需求是在做用户行为数据对齐的时候。当时有一张全量用户表，大概几十万行，另一张是活动参与名单，几千行。业务方的诉求很直接：把参与了活动、但不在全量用户表里的记录找出来。我第一反应是用isin，结果发现单列判断还行，一旦涉及多列组合判断，isin就力不从心了。后来又试了merge、join、集合运算，每种方法在数据量、索引状态、列顺序不同的情况下表现差异很大，有的还会悄悄改变行数，导致结果对不上。

所以这篇内容我想把这件事彻底讲透。它适合三类人：一是刚上手 pandas、还在被各种“判断包含”写法绕晕的新手；二是做过数据比对、但没系统梳理过各种方法适用边界的中级使用者；三是需要把这类逻辑封装成稳定工具函数、要求结果可复现的工程向开发者。核心要解决的问题就一个：给定两个 DataFrame，如何准确、高效地判断其中一个的数据是否存在于另一个之中，并且能清楚知道哪些行匹配、哪些行不匹配。

这里说的“数据在另一个 DataFrame 中”，其实包含好几个层次，必须先拆清楚，否则方法选错，结果全错：

• 整行匹配：一行所有列的值，在另一张表里是否存在完全相同的行。
• 子集列匹配：只拿某几列作为“键”，判断这些键的组合是否在另一张表里出现。
• 单列匹配：只判断某一列的值是否在另一张表的某一列里。
• 带索引的匹配：是否要求索引也对齐，还是只看数据内容。

这四种层次对应的最优解完全不同。下面我会从整体思路开始拆，再逐个方法给到可复现的代码和实测结论。

2. 整体思路拆解：先想清楚“匹配”的语义再动手

2.1 匹配语义决定了方法选型

很多人一上来就搜“pandas 判断包含”，拿到一个isin就用，结果发现多列不行，又换merge，发现行数变了，再换集合，发现顺序丢了。问题的根源不是方法不好，而是没先定义清楚匹配语义。

我一般会先问自己三个问题：

1. 匹配的键是什么？是整行，还是指定的几列？
2. 匹配结果要什么形式？是要一个布尔列标记每行是否存在，还是要筛出存在的行，还是要筛出不存在的行？
3. 对顺序和索引有没有要求？结果是否需要保持原表顺序，索引是否要保留？

把这三个问题回答清楚，方法基本就锁定了一半。比如你要的是“给主表加一列布尔值，标记该行的键是否在参照表中”，那isin配合多列元组化，或者merge加indicator参数，就是两个主流方向。如果你要的是“直接筛出不在参照表里的行”，那merge的how='left'加indicator，或者集合差集，会更顺手。

2.2 三种主流技术路线对比

我把常见做法归成三类，每类的底层逻辑和适用场景差别很大。

第一类是成员判断路线，代表是isin。它的本质是“某个值是否在一个集合里”。单列时非常直观，多列时需要先把多列拼成一个可哈希的元组或字符串，再整体判断。优点是语义清晰、速度快，缺点是只能回答“在不在”，不能直接告诉你匹配到了哪一行，也不方便做多对多匹配。

第二类是连接路线，代表是merge和join。它的本质是关系代数里的连接操作，能处理多对多、一对多等各种关系，还能通过indicator参数直接标记每行来自左表、右表还是两边都有。优点是功能强、能保留匹配细节，缺点是会改变行数和索引，需要额外处理。

第三类是集合运算路线，代表是把键转成set做交集、差集。它的本质是数学集合操作，速度极快，尤其适合大数据量的存在性判断。缺点是丢失顺序和重复信息，只能回答“这个键在不在参照集合里”，不能保留原始行结构。

三条路线没有绝对优劣，关键看你的语义需求。下面这张表是我自己总结的选型速查，实际用的时候基本照着对号入座就行。

2.3 一个容易被忽略的前提：键的规范化

不管走哪条路线，动手前有一件事必须做，就是键的规范化。我踩过最惨的一次坑，是两张表的用户 ID 一张是字符串、一张是整数，isin判断全部返回 False，排查了半天才发现是类型不一致。还有一次是字符串两边有空格，肉眼完全看不出来，匹配率直接掉了一半。

所以我的习惯是，在判断之前先统一做三件事：

• 类型对齐：把参与匹配的列统一转成相同类型，通常用astype(str)最稳妥，但要注意数值精度问题。
• 去空格：对字符串列做str.strip()，消除首尾空白差异。
• 空值处理：明确 NaN 算不算匹配。pandas 里 NaN 不等于 NaN，如果不处理，含空值的行匹配结果会出乎意料。

这三步看起来琐碎，但能避免后面 80% 的“结果对不上”问题。我一般会封装成一个normalize_keys函数，每次比对前先跑一遍。

3. 核心方法逐个拆解与实操要点

3.1 单列判断：isin 的正确打开方式

单列判断是最简单的场景，isin就是为它设计的。基本写法是df1['col'].isin(df2['col'])，返回一个布尔 Series，长度和 df1 一致，True 表示该值在 df2 的对应列里出现过。

但这里有几个细节必须注意。第一，isin判断的是“值是否在另一个序列的值集合里”，它不关心索引，也不关心重复。df2 里同一个值出现多次，不影响判断结果。第二，如果 df2 的列里有 NaN，isin对 NaN 的处理是：只有当 df1 对应位置也是 NaN 时，才可能匹配，但实际行为在不同 pandas 版本里有过变化，稳妥做法是提前把 NaN 替换成一个明确的哨兵值，比如字符串'__MISSING__'。

实测下来，isin在百万级数据上的性能是可以接受的，因为它底层会把参照序列转成一个哈希集合。但如果 df2 特别大，比如上千万行，每次调用都重新构建集合会有开销，这时候可以手动先构建一次集合，再用map或列表推导判断。

import pandas as pd import numpy as np # 构造示例数据 df_main = pd.DataFrame({ 'user_id': ['u001', 'u002', 'u003', 'u004', None], 'amount': [100, 200, 300, 400, 500] }) df_ref = pd.DataFrame({ 'user_id': ['u002', 'u004', 'u006', None], 'level': ['A', 'B', 'C', 'D'] }) # 基础用法 mask = df_main['user_id'].isin(df_ref['user_id']) print(mask.tolist()) # [False, True, False, True, False] # 空值规范化后再判断 def normalize_series(s): return s.astype(str).str.strip().replace({'nan': '__MISSING__', 'None': '__MISSING__'}) mask2 = normalize_series(df_main['user_id']).isin(normalize_series(df_ref['user_id'])) print(mask2.tolist()) # [False, True, False, True, True]

注意最后一行，规范化之后两个 NaN 都变成了'__MISSING__'，所以判定为匹配。这就是空值语义需要提前想清楚的地方：你到底希不希望空值算匹配。如果业务上空值不应该匹配任何东西，那就不要做这种统一替换，而是单独把空值行排除。

3.2 多列组合判断：元组化是核心技巧

多列判断是真正的难点。isin本身只接受单列，但我们可以把多列拼成一个可哈希的元组，再对元组序列做isin。这是我认为最优雅、最不容易出错的多列判断方式。

具体做法是，用zip把多列组合成元组，或者用apply(tuple, axis=1)。前者更快，后者更直观。然后对两个 DataFrame 都做同样的元组化，再用isin判断。

# 多列元组化判断 df_main = pd.DataFrame({ 'user_id': ['u001', 'u002', 'u003', 'u004'], 'date': ['2024-01-01', '2024-01-02', '2024-01-03', '2024-01-04'] }) df_ref = pd.DataFrame({ 'user_id': ['u002', 'u004', 'u005'], 'date': ['2024-01-02', '2024-01-04', '2024-01-05'] }) # 方式一：zip 元组化，速度快 keys_main = list(zip(df_main['user_id'], df_main['date'])) keys_ref = set(zip(df_ref['user_id'], df_ref['date'])) mask = pd.Series([k in keys_ref for k in keys_main], index=df_main.index) print(mask.tolist()) # [False, True, False, True] # 方式二：apply 元组化，可读性好 mask2 = df_main[['user_id', 'date']].apply(tuple, axis=1).isin( df_ref[['user_id', 'date']].apply(tuple, axis=1) ) print(mask2.tolist()) # [False, True, False, True]

这里有个关键点：列的顺序必须一致。如果 df_main 是['user_id', 'date']，df_ref 是['date', 'user_id']，元组化出来的结果就完全对不上。我一般会显式指定列顺序，比如定义一个key_cols = ['user_id', 'date']，两边都用这个列表取列，杜绝顺序问题。

另外，apply(tuple, axis=1)在数据量大时比较慢，因为它逐行调用 Python 函数。百万行级别建议用zip方式，实测能快好几倍。如果列数很多，还可以考虑把多列拼成一个带分隔符的字符串，但要注意分隔符不能出现在原始值里，否则会产生歧义。元组方式没有这个问题，所以我更推荐元组。

3.3 merge 连接判断：功能最强但要注意副作用

merge是功能最全的方法，尤其适合需要知道“匹配到了什么”的场景。核心用法是how='left'加indicator=True，这样结果里会多出一列_merge，取值是both、left_only或right_only，直接告诉你每行的匹配状态。

# merge 判断，保留匹配标记 merged = df_main.merge( df_ref, on=['user_id', 'date'], how='left', indicator=True ) print(merged['_merge'].tolist()) # ['left_only', 'both', 'left_only', 'both'] # 筛出不在参照表中的行 not_in_ref = merged[merged['_merge'] == 'left_only'] print(not_in_ref[['user_id', 'date']])

merge的强大之处在于，它能处理多对多关系。如果 df_ref 里同一个键有多行，merge会把它们全部展开，结果行数会增加。这在某些场景下是需要的，比如你想知道主表每一行匹配到了参照表的哪几条记录。但如果你只想要一个布尔标记，多对多展开就会导致行数膨胀，这时候必须先去重。

我踩过的一个坑是：用merge判断存在性，结果发现结果行数比主表多，一度以为数据错了。后来才明白是参照表里有重复键。所以用merge做存在性判断时，如果只关心“在不在”，一定要先对参照表按键去重，或者用drop_duplicates(subset=key_cols)，否则结果不可控。

还有一个细节是索引。merge默认会重置索引，结果是一个新的 RangeIndex。如果你需要保留原表索引，可以在 merge 前用reset_index把索引变成普通列，merge 后再设回去，或者直接用isin路线避免这个问题。

3.4 集合运算判断：大数据量下的性能之选

当数据量很大、又只需要知道存在性时，集合运算是最快的。核心思路是把两边的键都转成set，然后做交集或差集。

# 集合运算判断 keys_main = set(zip(df_main['user_id'], df_main['date'])) keys_ref = set(zip(df_ref['user_id'], df_ref['date'])) # 交集：两边都有的键 common = keys_main & keys_ref # 差集：主表有但参照表没有的键 only_in_main = keys_main - keys_ref # 回填到主表 mask = pd.Series( [k in keys_ref for k in zip(df_main['user_id'], df_main['date'])], index=df_main.index ) print(mask.tolist())

集合运算的优点是快，构建集合是 O(n)，判断是 O(1)，整体接近线性。缺点是丢失了顺序和重复信息，而且如果键本身不可哈希（比如列表类型的列），就没法直接用。另外，集合运算只能回答“键在不在”，不能告诉你匹配到了参照表的哪一行。

实测在千万级数据上，集合差集比merge快一个数量级，内存占用也更低。所以如果你的场景是“快速找出主表里哪些键不在参照表里”，集合运算是首选。但如果还需要匹配明细，那就得回到merge。

3.5 方法选型速查表

把上面几种方法的核心特征整理成一张表，方便对照选择。

4. 完整实操流程与关键环节实现

4.1 从原始数据到匹配结果的完整链路

我把整个流程拆成六步，每一步都有明确的输入输出和检查点。这套流程我在多个项目里复用，基本能覆盖 90% 的比对需求。

第一步，明确键列和匹配语义。先和需求方确认清楚，匹配的键是哪几列，空值算不算匹配，重复键怎么处理。这一步不写代码，但决定了后面所有实现。

第二步，键规范化。对两边的键列做类型对齐、去空格、空值统一处理。我一般封装成一个函数，输入 DataFrame 和键列列表，输出规范化后的副本。

def normalize_keys(df, key_cols, na_sentinel='__MISSING__'): df = df.copy() for col in key_cols: s = df[col] if s.dtype == object: s = s.astype(str).str.strip() else: s = s.astype(str) s = s.replace({'nan': na_sentinel, 'None': na_sentinel, '': na_sentinel}) df[col] = s return df

第三步，选择判断方法。根据是否需要匹配明细、数据量大小、是否要求保序，从上面的速查表里选。大多数存在性判断场景，我首选元组化isin，因为它保序、保索引、不改变行数，最不容易出意外。

第四步，执行判断并生成标记列。把布尔结果作为新列加到主表上，列名要语义清晰，比如is_in_ref。

第五步，校验结果。这一步很多人会跳过，但我觉得最重要。校验方式包括：检查匹配行数是否合理、抽样人工核对几条、对比两种方法的结果是否一致。我经常用merge和isin两种方法交叉验证，如果结果一致，基本可以放心。

第六步，输出和落库。把结果按需求方要的格式输出，注意索引和列顺序。

4.2 一个可复用的比对函数实现

基于上面的流程，我写了一个通用函数，支持单列和多列，支持返回布尔标记或筛选结果，内部自动做键规范化。

def check_inclusion(df_main, df_ref, key_cols, return_type='mask', na_sentinel='__MISSING__'): """ 判断 df_main 的键是否存在于 df_ref 中。 参数: df_main: 主表 df_ref: 参照表 key_cols: 用于匹配的列名列表 return_type: 'mask' 返回布尔 Series, 'exists' 返回存在的行, 'not_exists' 返回不存在的行 na_sentinel: 空值替换的哨兵值 返回: 根据 return_type 返回对应结果 """ # 键规范化 main_norm = normalize_keys(df_main, key_cols, na_sentinel) ref_norm = normalize_keys(df_ref, key_cols, na_sentinel) # 元组化 main_keys = list(zip(*[main_norm[c] for c in key_cols])) ref_keys = set(zip(*[ref_norm[c] for c in key_cols])) # 判断 mask = pd.Series( [k in ref_keys for k in main_keys], index=df_main.index, name='is_in_ref' ) if return_type == 'mask': return mask elif return_type == 'exists': return df_main[mask] elif return_type == 'not_exists': return df_main[~mask] else: raise ValueError(f"不支持的 return_type: {return_type}")

这个函数有几个设计考量。第一，用zip(*[main_norm[c] for c in key_cols])而不是apply(tuple)，是为了性能，列数多的时候优势明显。第二，参照表转成set只做一次，判断时是 O(1) 查找。第三，返回的 mask 用原表索引，保证和主表对齐。第四，return_type参数让一个函数覆盖三种常见输出需求，减少重复代码。

4.3 参数选择与性能实测

为了让大家对性能有直观感受，我构造了三组不同规模的数据做实测。测试环境是普通开发机，pandas 版本 2.x。

从数据看，集合运算最快，元组化isin次之，merge最慢。但差距在可接受范围内，所以选型时性能不是唯一因素，语义匹配度更重要。我一般的原则是：需要明细用merge，需要保序用isin，纯存在性且数据量大用集合。

还有一个影响性能的点是键的基数。如果键的重复度很高，集合会很小，判断很快；如果键几乎全唯一，集合会很大，内存占用上升。百万级唯一键的集合大概占几十 MB，一般机器扛得住，但上千万就要留意内存了。

4.4 结果校验的三种手段

结果校验我通常用三招。第一招是交叉验证，用两种不同方法跑同一份数据，对比结果是否一致。比如isin和merge都跑一遍，如果布尔标记完全一致，可信度就很高。

第二招是抽样核对，从匹配和不匹配的行里各抽几条，人工看键值，确认判断符合预期。这一步能发现类型、空格这类隐蔽问题。

第三招是统计校验，检查匹配率是否在合理范围。如果匹配率异常低或异常高，往往意味着键规范化没做好，或者匹配语义理解错了。

# 交叉验证示例 mask_isin = check_inclusion(df_main, df_ref, ['user_id', 'date'], 'mask') merged = df_main.merge(df_ref, on=['user_id', 'date'], how='left', indicator=True) mask_merge = merged['_merge'] == 'both' # 对比两种方法 assert mask_isin.tolist() == mask_merge.tolist(), "两种方法结果不一致！" print("交叉验证通过")

5. 常见问题与排查技巧实录

5.1 匹配率异常低？先查类型和空格

这是最高频的问题。两张表看起来键值一样，但匹配率就是很低。九成以上的原因是类型不一致或隐藏空格。排查方法很简单，分别打印两边的dtype和几条样本的repr，repr能把空格和不可见字符显示出来。

print(df_main['user_id'].dtype) print(df_ref['user_id'].dtype) print(repr(df_main['user_id'].iloc[0])) print(repr(df_ref['user_id'].iloc[0]))

如果发现类型不同，统一转字符串；如果发现空格，用str.strip()；如果发现大小写不一致，用str.lower()统一。这些都在键规范化那一步解决。

5.2 merge 后行数变多？参照表有重复键

用merge做存在性判断时，如果参照表里同一个键有多行，结果会展开成多行，导致行数膨胀。解决办法是在 merge 前对参照表按键去重。

df_ref_dedup = df_ref.drop_duplicates(subset=['user_id', 'date'])

如果业务上确实需要保留参照表的所有匹配行，那就不能用 merge 做存在性判断，而应该用isin先标记存在性，再单独做明细关联。

5.3 空值判断不符合预期？明确 NaN 语义

pandas 里 NaN 不等于 NaN，这导致含空值的行在匹配时行为诡异。我的建议是，在键规范化阶段就把空值替换成一个明确的哨兵值，然后根据业务需求决定这个哨兵值是否参与匹配。如果空值不应该匹配任何东西，那就把哨兵值设成一个绝对不会出现在真实数据里的字符串，并且只在主表里替换，参照表里的空值行直接排除。

5.4 结果顺序乱了？merge 和集合都会打乱

merge和集合运算都不保证原顺序。如果结果需要保序，用元组化isin生成布尔标记，再用这个标记筛选原表，顺序自然保持。或者给主表加一个自增序号列，任何操作后按序号排序回填。

5.5 常见问题速查表

5.6 几个我踩过的坑和独家技巧

第一个坑是浮点数键。用浮点数做键匹配是灾难，因为 0.1 + 0.2 不等于 0.3，看起来一样的浮点数可能因为精度差异匹配不上。如果键是浮点数，先转成定点数或字符串，再做匹配。

第二个坑是时间类型键。一张表是datetime64，另一张是字符串，直接匹配全 False。统一转成字符串，并且格式要一致，比如都用%Y-%m-%d。

第三个技巧是分块处理超大表。如果参照表大到内存放不下，可以把参照表按块读入，每块构建一个集合，主表逐行判断是否在任意一个集合里。这样内存可控，速度也还行。

第四个技巧是用 categorical 类型加速。如果键的基数不高，把键列转成category类型，isin和merge都会更快，因为底层用整数编码比较。

第五个技巧是保留中间结果。键规范化后的表、构建好的集合，如果后续还要复用，就存下来，避免重复计算。我在做迭代式数据比对时，会把参照集合缓存起来，每次只更新变化的部分。

6. 不同数据规模下的策略选择

6.1 小数据量：可读性优先

数据量在几万行以内时，性能完全不是问题，这时候应该优先选可读性最好的写法。我一般直接用apply(tuple)加isin，代码一目了然，别人接手也容易看懂。这个阶段不要过早优化，把语义写清楚比什么都重要。

6.2 中等数据量：平衡性能和可维护性

十万到百万行级别，apply(tuple)开始变慢，这时候换成zip元组化。如果还需要匹配明细，用merge但记得先去重。这个阶段我建议把比对逻辑封装成函数，加上参数控制和结果校验，方便复用和排查。

6.3 大数据量：性能和内存双重考量

百万行以上，集合运算和分块处理是主力。核心思路是尽量减少中间对象的创建，能转集合就转集合，能分块就分块。如果单机扛不住，就要考虑用更专业的工具，但那是另一个话题了。这个阶段一定要做性能测试，用真实数据量跑一遍，别等上线了才发现跑不动。

6.4 不同规模策略对照表

7. 写在最后的一点个人体会

这套判断逻辑我用了好几年，从最开始只会isin，到后来被各种边界情况教育，再到现在形成一套相对稳定的方法论，中间踩的坑基本都写在上面的内容里了。我的核心体会是，判断包含这件事，难点从来不在代码本身，而在匹配语义的定义和键的规范化。把这两件事想清楚，代码怎么写都不会太离谱；这两件事没想清楚，用再高级的方法也会出错。

另外分享一个我最近常用的习惯：每次做数据比对，先拿一小份样本数据跑通全流程，人工核对结果无误后，再上全量数据。这样能提前发现类型、空格、空值这些问题，避免在大数据量上浪费时间。样本不用多，几百行就够，但能省下大量排查时间。

如果后续还要扩展，可以考虑把比对结果做成可视化报告，标出匹配率、不匹配样本、键的分布情况，这样给需求方看的时候更直观。这个方向我还在摸索，有成熟经验了再单独整理。