当 DataFrame 列中存在 pd.NA 或 None 等缺失值时，df.query() 默认使用 numexpr 引擎会因字符串方法（如 .str.contains()）无法处理空值而报错；可通过 fillna("") 预处理或显式指定 engine='python' 解决，二者在大数据量下性能接近。
当 dataframe 列中存在 `pd.na` 或 `none` 等缺失值时，`df.query()` 默认使用 `numexpr` 引擎会因字符串方法（如 `.str.contains()`）无法处理空值而报错；可通过 `fillna("")` 预处理或显式指定 `engine='python'` 解决，二者在大数据量下性能接近。
在 Pandas 中，query() 方法以其简洁、类 SQL 的语法广受青睐，但在处理含缺失值（尤其是 pd.NA、None 或 np.nan）的字符串列时，常遇到 UndefinedVariableError 或 KeyError。根本原因在于：numexpr 引擎（query() 默认引擎）不支持对包含缺失值的 Series 直接调用 .str 访问器方法——它会在底层尝试将布尔表达式编译为高效数值运算，但 Subjects.str.contains("Math") 在遇到 pd.NA 时无法返回确定的布尔标量，导致解析失败。
以下复现问题的最小示例：
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")')✅ 两种可靠解决方案
方案一：预填充空值（推荐用于语义安全场景）
对目标字符串列调用 .fillna("")，将缺失值转为空字符串后再执行 .str.contains()。该方式语义清晰——空值自然不匹配 "Math"，且兼容 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⚠️ 注意：若业务逻辑中需区分“空字符串”和“缺失值”，此方案可能掩盖语义差异。此时应优先选用方案二或结合 .notna() 显式过滤。
方案二：切换至 Python 引擎（推荐用于复杂逻辑或需严格空值语义）
显式指定 engine='python'，使 query() 回退到 Python 解释器执行表达式。此时 .str.contains() 可正确处理 pd.NA（返回 pd.NA），配合布尔逻辑自动实现三值逻辑（True & pd.NA → pd.NA，最终被 query() 视为 False 过滤掉）：
result = df_test.query('Title.str.startswith("T") and Subjects.str.contains("Math")',
engine='python')
print(result)
# Title Subjects
# 0 Title1 Math; Science
# 1 Title2 English; Math虽然 Pandas 文档提示 engine='python' “效率低于 numexpr”，但实测表明：在百万行规模数据上，两种方案性能差异极小（如测试中 556ms vs 573ms）。对于绝大多数业务场景，可放心选用，尤其当查询逻辑涉及多层 .str 链式调用或需保留空值语义时。
? 补充建议与最佳实践
- 避免混合使用：不要在同一个 query() 字符串中混用 fillna() 和 engine='python'，无必要且易引发混淆。
- 空值类型一致性：确保缺失值为 pd.NA（推荐）而非 np.nan（后者在 .str 方法中可能静默转为 False，行为不一致）。
- 替代写法对比：传统布尔索引（df[mask1 & mask2]）始终最稳定，但 query() 在复杂条件组合时可读性更高。权衡点在于：是否需要牺牲少量性能换取表达力提升。
- 版本注意：该问题在 Pandas ≥1.5 和 ≥2.0 均存在，非版本 Bug，而是 numexpr 引擎的设计限制。
综上，query() 对空值的支持并非缺陷，而是引擎选型与数据清洗策略协同的结果。合理选择 fillna("") 或 engine='python'，即可在保持代码简洁性的同时，稳健处理真实世界中普遍存在的缺失值场景。
