merge_asof 默认实现最近匹配但不支持 tolerance 参数，需先 merge_asof 再用 query 筛选满足容差的行；左右 on 列须预排序，backward 方向用 delta = left_on - right_on 并 query('delta >= 0 and delta
merge_asof 默认就是最近匹配，但不支持 tolerance 参数
merge_asof 的设计目标就是在左表每行的 on 列值附近，找右表中「最大但不超过它」（direction='backward'）或「最小但不低于它」（direction='forward'）的行——这本身就是一种“最近匹配”，但它**不接受 tolerance 范围限制**。如果你看到报错 TypeError: merge_asof() got an unexpected keyword argument 'tolerance'，说明你误以为它像 numpy.isclose 那样支持容差。
要实现带 tolerance 的最近匹配，必须手动过滤 + 二次筛选，不能靠 merge_asof 一步到位。
用 merge_asof + query 实现带 tolerance 的最近匹配
核心思路：先用 merge_asof 找到每个左行最接近的右行（默认 direction='backward'），再计算实际距离，用 query 剔除超出 tolerance 的结果。
- 确保左右表的
on列已排序（merge_asof强制要求） - 合并后新增一列，比如
delta = left_on - right_on（对backward场景） - 用
.query('delta = 0')筛选（注意符号方向） - 若需双向容差（左右都可偏），改用
abs(left_on - right_on) ，但此时merge_asof的单向语义失效，应改用pd.merge+sort_values+drop_duplicates组合
left = pd.DataFrame({'time': [1, 5, 10], 'val': ['a', 'b', 'c']})
right = pd.DataFrame({'time': [2, 4, 8, 12], 'info': ['x', 'y', 'z', 'w']})
tolerance = 2
result = pd.merge_asof(left.sort_values('time'),
right.sort_values('time'),
on='time',
direction='backward')
result['delta'] = result['time'] - result['time']
实际应为 result['delta'] = result['time'] - result['time_right']（需重命名右表 time）
result = result.query('delta <= @tolerance')
tolerance 较大时，merge_asof 不再适用，该换 join + idxmin
当 tolerance 占数据跨度比例较高（例如时间范围 0–100，tolerance=30），merge_asof 的“单侧最近”逻辑会漏掉本应在容差内、但方向相反的候选行。这时更稳妥的做法是：对左表每行，在右表中搜索所有满足 abs(left_time - right_time) 的行，再取绝对差最小的那个。
- 用
pd.merge做笛卡尔积（仅适用于中小数据量） - 或用
scipy.spatial.cKDTree加速（大数据量、单维度） - 最通用的写法是：对左表每行，用
right.loc[(right.time - row.time).abs().idxmin()]，但性能差；可向量化为right.iloc[abs(right.time.values - left.time.values[:, None]).argmin(axis=1)] - 注意：此方式不保证稳定性（多个相同最小距离时取第一个），如需确定性，得加
keep='first'或显式去重
容易忽略的排序与重复问题
merge_asof 要求左右表 on 列严格单调递增，如果存在重复值，它会取最后一个匹配项（不是报错）。但 tolerance 过滤后，可能只剩空结果——这不是 bug，而是数据本身不满足条件。
- 务必检查
left['on'].is_monotonic_increasing和right['on'].is_monotonic_increasing - 右表若有重复
on值，merge_asof会任选其一（按原始顺序），无法控制；如需确定行为，先right.drop_duplicates(subset=['on'], keep='first') - tolerance 是数值型阈值，对 datetime 列需统一转为
pd.Timedelta（如pd.Timedelta('2s')），不可直接用整数秒
真正难的不是写哪一行代码，而是想清楚：你要的“最近”，是指时间上最邻近的一条记录，还是在某个误差范围内、且满足业务逻辑（比如不能用未来的数据）的最优解。这两者在建模阶段就该区分清楚。
