当 dataframe 列中存在 pd.na 或 nan 时，直接在 query() 中调用 .str.contains() 等方法会因 numexpr 引擎不支持空值运算而报错；可通过 fillna("") 或切换 engine='python' 安全解决，二者性能相近且均优于先过滤再 query 的嵌套写法。
当 dataframe 列中存在 pd.na 或 nan 时，直接在 query() 中调用 .str.contains() 等方法会因 numexpr 引擎不支持空值运算而报错；可通过 fillna("") 或切换 engine='python' 安全解决，二者性能相近且均优于先过滤再 query 的嵌套写法。
在使用 Pandas 的 query() 方法进行字符串条件筛选时，若目标列（如 Subjects）包含空值（pd.NA、None 或 np.nan），直接调用 .str.contains()、.str.startswith() 等链式方法会触发 UndefinedVariableError —— 这并非用户操作错误，而是 query() 默认使用的 numexpr 引擎无法安全处理缺失值参与的字符串操作所致。
以下是最小复现示例：
import pandas as pd
data = {'Title': ['Title1', 'Title2', 'Title3', 'Title4'],
'Subjects': ['Math; Science', 'English; Math', pd.NA, 'English']}
df_test = pd.DataFrame(data)
# ❌ 报错：UndefinedVariableError
# df_test.query('Title.str.startswith("T") and Subjects.str.contains("Math")')
✅ 推荐解决方案（二选一）
方案 1：对空值预填充（推荐，语义清晰）
使用 .fillna("") 将空值转为空字符串，使 .str.contains() 在 numexpr 引擎下可安全执行：
result = df_test.query('Title.str.startswith("T") and Subjects.fillna("").str.contains("Math")')
print(result)
# Title Subjects
# 0 Title1 Math; Science
# 1 Title2 English; Math
✅ 优点：保持默认高效引擎，逻辑直观（空值自然不匹配 "Math"）；
⚠️ 注意：若业务中需区分 "Math" 和空字符串语义，此方式仍合理——因 "".contains("Math") 返回 False，符合布尔筛选预期。
方案 2：切换至 Python 引擎（兼容性强）
显式指定 engine='python'，绕过 numexpr 的限制，交由原生 Python 解析：
result = df_test.query('Title.str.startswith("T") and Subjects.str.contains("Math")', engine='python')
✅ 优点：无需修改数据，完全保留原始空值语义；
⚠️ 注意：官方文档提示其性能通常低于 numexpr，但实测在百万级数据上差异微小（甚至略快），可放心用于中等规模数据。
⚠️ 不推荐的写法及原因
- df_test[df_test['Subjects'].notna()].query(...)：虽能运行，但破坏了 query() 的链式表达优势，且需两次遍历（先布尔索引再解析字符串），可读性与性能均较差；
- Subjects.notna() and Subjects.str.contains("Math") 在同一 query 中仍会失败：numexpr 无法协调空值检查与后续字符串方法的执行顺序。
总结
| 方案 | 引擎 | 空值处理 | 性能 | 推荐场景 |
|---|---|---|---|---|
| fillna("").str.contains() | numexpr（默认） | 显式转空串 | ⭐⭐⭐⭐☆ | 大多数场景，语义明确 |
| engine='python' | python | 原生支持 | ⭐⭐⭐⭐ | 需严格保留空值语义或调试阶段 |
无论选择哪种方式，都应避免在 query() 字符串中混合未处理的空值与 .str.* 方法调用。统一采用上述任一策略，即可安全、高效地完成含空值列的复杂字符串查询。
