当 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 中，DataFrame.query() 是一种语法简洁、可读性强的布尔筛选方式，但其底层默认依赖 numexpr 引擎进行高效向量化计算。该引擎对缺失值（尤其是 pd.NA、None 或 NaN）的字符串操作（如 .str.startswith()、.str.contains()）支持有限——一旦涉及 .str 访问器且列中存在空值，numexpr 便无法安全解析表达式，从而抛出 UndefinedVariableError 或 KeyError，这并非用户误用，而是 numexpr 引擎的设计限制。
以下复现问题的数据为例：
import pandas as pd
data = {'Title': ['Title1', 'Title2', 'Title3', 'Title4'],
'Subjects': ['Math; Science', 'English; Math', pd.NA, 'English']}
df_test = pd.DataFrame(data)直接执行：
df_test.query('Title.str.startswith("T") and Subjects.str.contains("Math")')将失败，因为 Subjects.str.contains("Math") 在 pd.NA 行上返回 pd.NA，而 numexpr 无法处理该三值逻辑（True/False/NA）参与的布尔组合运算。
✅ 推荐解决方案（按优先级排序）：
-
预填充空值（最兼容、语义清晰）
对参与 .str 操作的列，用 fillna("") 将缺失值转为空字符串，确保所有元素均为字符串类型：df_test.query('Title.str.startswith("T") and Subjects.fillna("").str.contains("Math")')✅ 优点：保持 numexpr 高性能，逻辑明确（空值不匹配 "Math"），适用于绝大多数场景。
⚠️ 注意：若业务上需区分“空字符串”与“缺失值”，此法需额外校验，例如结合 Subjects.notna()。 -
切换查询引擎为 'python'（最直接、无需修改数据）
显式指定 engine='python'，交由 Python 解释器执行表达式，天然支持 pd.NA 和三值逻辑：df_test.query('Title.str.startswith("T") and Subjects.str.contains("Math")', engine='python')✅ 优点：代码零侵入，语义完全忠实原始意图（str.contains 在 pd.NA 上返回 pd.NA，布尔 and 自动按三值逻辑短路）。
⚠️ 注意：官方文档提示其性能通常低于 numexpr，但实测在百万级数据上差异微小（如测试中 556ms vs 573ms），且可读性与健壮性更优。
❌ 不推荐的绕行方式：
- 先 df[condition].query(...) 分步过滤（破坏链式表达，降低可读性，且多次索引开销可能更高）；
- 使用 df.query(...).dropna(subset=['Subjects'])（错误：query 已失败，无法执行后续操作）。
? 总结建议：
- 日常开发与中等规模数据（<10M 行）：优先使用 engine='python'，兼顾简洁性、正确性与足够性能；
- 高性能敏感场景（如 ETL 流水线）：采用 fillna("") + 默认引擎，并在注释中说明空值处理策略；
- 统一规范：团队内应约定缺失值语义（pd.NA 是否等价于空字符串？是否需单独保留？），再选择对应方案。
无论选用哪种方式，核心原则是：query() 的字符串方法调用必须作用于全量有效字符串上下文，或交由支持三值逻辑的引擎处理。
