query方法必须用@引用变量而非f-string拼接，因解析的是表达式非Python代码；漏反引号或@会导致静默失败或KeyError。
query 方法支持动态条件，但必须把变量名用 @ 前缀显式引用，直接拼字符串会报错或逻辑错误。
为什么不能直接用 f-string 拼接条件字符串？
因为 query 解析的是表达式字符串，不是 Python 代码；f-string 拼出来的字符串若含未加引号的变量名（如 f"col == {value}"），会被当成列名而非值，导致 KeyError 或意外过滤结果。
常见错误现象：KeyError: "name 'value' is not defined" 或筛选结果为空/全中。
- 正确做法：用
@引用外部变量，例如df.query("col == @value") - 字符串值需保留引号，
df.query("name == @name_str")中name_str = "Alice"即可，无需手动加引号 - 多个变量同理：
df.query("age > @min_age and city in @cities")，其中cities是 Python list
如何安全地构建多条件动态查询？
避免字符串拼接，优先用 @ + 字典解包或局部变量传入。复杂逻辑建议拆成独立布尔 Series，再配合 query 做二次过滤。
立即学习“Python免费学习笔记（深入）”；
使用场景：Web 接口接收参数后筛选 DataFrame、配置文件驱动的报表条件、交互式分析中用户输入值。
- 推荐方式：
df.query("a > @low and b in @valid_list", local_dict={"low": 10, "valid_list": ["x", "y"]}) - 不推荐：
df.query(f"a > {low} and b in {valid_list}")—— 易注入、类型错乱、引号难处理 - 注意：
local_dict中键名仍需用@引用，和默认命名空间行为一致
query 中哪些语法容易踩坑？
看似像 Python，实则用的是 pandas 的 mini-language，兼容性与行为有差异。
-
and/or必须小写，&/|不可用（会报SyntaxError） -
in只支持 Python 容器（list/tuple/set），不支持pd.Series；想用 Series 做 in 判断，请改用isin() - 列名含空格或特殊字符时，必须用反引号包裹：
df.query("`user name` == @name") - 性能提示：对超大 DataFrame，
query比链式布尔索引略快，但首次调用有编译开销；简单条件用df[cond]更直观
最常被忽略的是反引号包裹列名和 @ 引用变量的强制性——漏掉任一，都会静默失败或抛出难以定位的解析错误。
