理解 df.query() 中的变量引用机制
pandas 的 df.query() 方法提供了一种简洁且高效的方式来使用字符串表达式筛选 dataframe。然而，当表达式中需要引用当前 python 环境中的变量时，query() 方法并不会自动识别这些变量。如果直接将变量名（如 stopdate）放入查询字符串的引号中，query() 会将其视为一个字面字符串，而非变量的值。对于日期时间对象，这会导致 pandas 尝试将字面字符串 "stopdate" 转换为日期时间类型进行比较，从而抛出 valueerror: unknown string format: stopdate 错误。
例如，在以下代码片段中，尝试在循环中根据不同的年份筛选数据：
import datetime as dt
import pandas as pd
# 假设 df 已经从 Excel 加载，且 Commissioned 和 Decommissioned 列为 datetime64[ns] 类型
# df = pd.read_excel("Ships.xlsx")
lstCruisers = []
yearStart = 1980
yearStop = 1985
for yr in range(yearStart, yearStop + 1):
stopDate = pd.Timestamp(yr, 12, 31).date() # 创建 datetime.date 对象
print(f"Current stopDate: {stopDate}, type: {type(stopDate)}")
# 错误示例：直接引用 stopDate 变量名
qrystr = "Type == 'Cruiser' " \
" and (Commissioned != 'NaT' and Commissioned <= 'stopDate')" \
" and (Decommissioned >= 'stopDate' or Decommissioned == 'NaT') "
try:
dfCruisers = df.query(qrystr)
print(f"Ships for {yr}: {len(dfCruisers)}")
except ValueError as e:
print(f"Error for year {yr}: {e}")
print("This error occurs because 'stopDate' is treated as a literal string.")
# nrShips = len(dfCruisers) # 如果发生错误，这里会因为 dfCruisers 未定义而报错
# lstCruisers.append([yr, nrShips])
# print(lstCruisers)运行上述代码，在尝试执行 df.query(qrystr) 时，将会遇到 ValueError: Unknown string format: stopDate。这明确指出 df.query() 无法识别 stopDate 是一个外部变量，而是试图解析字符串 "stopDate" 为一个日期。
解决方案：使用 @ 符号引用外部变量
为了在 df.query() 表达式中正确引用 Python 环境中的变量，Pandas 提供了一个特殊的语法：在变量名前加上 @ 符号。这个符号告诉 query() 引擎，它应该查找当前作用域中与 @ 后面的名称匹配的 Python 变量，并使用其值来替换表达式中的变量名。
修正后的查询字符串如下所示：
import datetime as dt
import pandas as pd
# 模拟 DataFrame 和数据加载
data = {
'BF': ['X', 'X', 'X', 'X', 'X'],
'Ship': ['Able', 'Abraham Lincoln', 'Acadia', 'Adroit', 'Adventurous'],
'Type': ['Cruiser', 'Destroyer', 'Cruiser', 'Submarine', 'Cruiser'],
'Commissioned': pd.to_datetime(['1992-07-22', '1989-11-11', '1981-06-06', '1957-03-04', '1988-08-19']),
'Decommissioned': pd.to_datetime(['2030-09-30', pd.NaT, '1994-12-16', '1991-12-12', '1992-06-05'])
}
df = pd.DataFrame(data)
lstCruisers = []
yearStart = 1980
yearStop = 1985
for yr in range(yearStart, yearStop + 1):
stopDate = pd.Timestamp(yr, 12, 31).date() # 创建 datetime.date 对象
print(f"Current stopDate: {stopDate}, type: {type(stopDate)}")
# 正确示例：使用 @ 符号引用 stopDate 变量
qrystr = "Type == 'Cruiser' " \
" and (Commissioned != 'NaT' and Commissioned <= @stopDate)" \
" and (Decommissioned >= @stopDate or Decommissioned == 'NaT') "
dfCruisers = df.query(qrystr)
nrShips = len(dfCruisers)
lstCruisers.append([yr, nrShips])
print(f"Ships for {yr}: {nrShips}")
print(dfCruisers) # 打印筛选结果以便检查
print("\nFinal list of cruisers by year:")
print(lstCruisers)在这个修正后的代码中，@stopDate 告诉 df.query() 去查找名为 stopDate 的 Python 变量，并使用它的值（一个 datetime.date 对象）来执行比较操作。这样，查询就能正确地根据年份筛选出在役的巡洋舰数量。
注意事项与最佳实践
- 通用性： @ 符号不仅适用于日期时间变量，也适用于任何需要从外部 Python 环境引入到 query() 表达式中的变量，例如数字、字符串、布尔值等。
- 数据类型匹配： 确保 DataFrame 中用于比较的列（如 Commissioned 和 Decommissioned）与外部变量（如 stopDate）具有兼容的数据类型。通常，将 DataFrame 的日期列转换为 datetime64[ns] 类型，并将外部变量也保持为 datetime.date 或 pandas.Timestamp 类型，可以确保平滑的比较。
- NaT 处理： 在处理可能包含缺失日期（NaT - Not a Time）的列时，使用 != 'NaT' 或 == 'NaT' 是正确的做法，因为 NaT 是一种特殊的 Pandas 日期时间缺失值。
- 可读性与复杂性： 对于非常复杂的查询，虽然 query() 语法很强大，但有时直接使用布尔索引（例如 df[(df['col']
- 性能： df.query() 在内部使用了 numexpr 库，对于大型 DataFrame，其性能通常优于链式布尔索引，因为它能减少中间对象的创建。正确使用 @ 引用变量并不会显著影响其性能优势。
总结
在 Pandas df.query() 中引用外部 Python 变量，特别是日期时间对象时，务必使用 @ 符号前缀。这不仅是避免 ValueError 的关键，也是编写清晰、高效且可维护的 Pandas 查询表达式的重要实践。通过理解 query() 引擎如何处理变量引用，开发者可以更灵活地构建动态查询，从而更好地分析和处理数据。
