本文介绍如何在 polars 中对多股票时间序列数据执行「按 symbol 分组 + 基于日期的向前查找连接」，即每个事件仅匹配 fr 中同 symbol 下首个 ≥ 事件日期的记录，并确保每个事件最多被匹配一次。
本文介绍如何在 polars 中对多股票时间序列数据执行「按 symbol 分组 + 基于日期的向前查找连接」，即每个事件仅匹配 fr 中同 symbol 下首个 ≥ 事件日期的记录，并确保每个事件最多被匹配一次。
在金融或事件驱动分析中，常需将离散事件（如财报发布日、分红公告日）对齐到连续交易日数据上——但二者日期通常不完全重合。此时，join_asof 是 Polars 提供的核心解决方案：它支持有序键上的“最近前向匹配”（nearest-earlier-or-equal），并天然支持按分组键（如 Symbol）独立执行。
以下是一个完整、可复现的示例：
import polars as pl
# 主数据：按 Symbol 和 Date 排序的交易日序列（已设为 sorted）
fr = pl.DataFrame({
'Symbol': ['A'] * 5 + ['B'] * 4,
'Date': ['2010-08-29', '2010-09-01', '2010-09-05', '2010-11-30', '2010-12-02',
'2010-09-01', '2010-09-05', '2010-12-01', '2010-12-02'],
}).with_columns(
pl.col('Date').str.to_date('%Y-%m-%d')
).with_row_index().set_sorted("Date")
# 事件数据：含 Symbol、事件日期和事件值，也需按事件日期排序
events = pl.DataFrame({
'Symbol': ['A', 'A', 'A', 'B', 'B'],
'Earnings_Date': ['2010-06-01', '2010-09-01', '2010-12-01',
'2010-08-20', '2010-12-01'],
'Event': [1, 4, 7, 2, 9],
}).with_columns(
pl.col('Earnings_Date').str.to_date('%Y-%m-%d')
).set_sorted("Earnings_Date")
✅ 第一步：基础 asof join（支持分组）
使用 join_asof(..., by="Symbol", left_on="Date", right_on="Earnings_Date") 即可实现「每只股票内部独立匹配」：对 fr 中每个 (Symbol, Date)，查找 events 中相同 Symbol 下 Earnings_Date ≤ Date 的最大日期对应行。
result = fr.join_asof(
events,
left_on="Date",
right_on="Earnings_Date",
by="Symbol"
)
print(result)
⚠️ 注意：join_asof 默认行为是「左表每行匹配右表最近的 ≤ 日期行」，且右表同一事件可能被多次匹配（如 2010-09-01 事件会匹配 2010-09-01, 2010-09-05, 2010-11-30 三行）。若业务要求「每个事件仅触发一次」（即首次匹配后失效），需额外去重。
✅ 第二步：限制每个事件仅匹配一次（关键增强）
利用 .over("Symbol") 窗口 + is_first_distinct() 标记每个 Symbol 内首次出现的 (Earnings_Date, Event) 组合，再用 pl.when().then().otherwise(None) 清除重复匹配：
result_once = (
fr.join_asof(events, left_on="Date", right_on="Earnings_Date", by="Symbol")
.with_columns(
pl.when(
pl.col("Earnings_Date", "Event").is_first_distinct()
)
.then(pl.col("Earnings_Date", "Event"))
.otherwise(None)
.over("Symbol")
.name.keep() # 保留原列名
)
)
该逻辑确保：在每个 Symbol 分组内，只有 Earnings_Date 首次出现的那行事件会被保留，其余重复匹配位置自动置为 null。
? 重要前提与最佳实践：
- 左右表用于 asof 连接的列（Date / Earnings_Date）必须已调用 .set_sorted()，否则性能严重下降甚至报错；
- by 列（如 Symbol）无需预排序，但建议类型一致、无空值；
- 若需「向后查找」（即匹配 ≥ 当前日期的首个事件），可改用 strategy="forward"（Polars ≥ 0.20.0），或对右表日期取负再 asof；
- 对超大数据集，可先 .filter() 限定日期范围，避免全量扫描。
最终结果语义清晰：每条交易记录关联其「所属股票的、尚未发生的最近一次事件」，完美支撑事件研究、因子对齐等典型量化场景。
