Polars 中基于容差的双时间戳序列懒加载同步（join_asof 实现）

使用 Polars LazyFrame 的 join_asof 配合 drop_nulls()，可在不触发计算的前提下高效完成两个时间戳数组的最近邻同步，支持毫秒级容差过滤，适用于大规模流式时序数据对齐。

处理高频传感器数据、日志流或是金融行情时，我们常常会碰到一个经典难题：如何将两组采集节奏不同步的时间戳序列，优雅地“对齐”起来？这里说的对齐，可不是简单的硬匹配，而是要为每个主时间戳，在另一组里找到那个最接近、并且时间差还在我们容忍范围之内的伙伴。

乍一看，你可能会想到用 NumPy 的 `np.subtract.outer` 配合 `argmin` 来暴力计算所有配对的距离。这个方法确实直观，但问题也很明显：它无法延迟执行，内存消耗随着数据量平方级增长，面对动辄 GB 级别的大规模时序数据，就显得力不从心了。好在，Polars 库为我们准备了一个“秘密武器”——专为这种有序时间近似匹配场景设计的原生懒加载操作：`join_asof`。

✅ 正确实现：join_asof + drop_nulls()

这套方案的核心逻辑非常清晰，分三步走：

• 首先，确保主时间戳序列和参考时间戳序列都按照时间升序排列好，这是 `join_asof` 正确工作的前提。
• 接着，调用 `join_asof(..., strategy="nearest", tolerance="500ms")` 执行一次左连接。这个操作会智能地为左边表的每一个时间戳，在右边表中寻找绝对时间差最小的那个记录，并且只接受时间差在指定容差（比如500毫秒）以内的匹配。
• 最关键的一步：别忘了，`join_asof` 在找不到符合条件的匹配项时，会用 null 值填充右侧的列。因此，我们必须紧接着调用 `.drop_nulls()`（或者显式地用 `.filter(pl.col("other_values").is_not_null())`）来过滤掉这些超出容差范围的“失配”行，这样才能得到纯净的同步结果。

下面是一个完整的、基于 LazyFrame 的可运行示例，全程保持惰性求值：

import polars as pl
import numpy as np

# 构建示例 LazyFrames（保持 lazy 特性）
timestamps = pl.LazyFrame(
    np.array([
        np.datetime64("1970-01-01T00:00:00.500000000"),
        np.datetime64("1970-01-01T00:00:01.500000000"),
        np.datetime64("1970-01-01T00:00:02.600000000"),
        np.datetime64("1970-01-01T00:00:03.400000000"),
        np.datetime64("1970-01-01T00:00:04.500000000"),
        np.datetime64("1970-01-01T00:00:05.300000000"),
        np.datetime64("1970-01-01T00:00:06.200000000"),
        np.datetime64("1970-01-01T00:00:07.400000000"),
        np.datetime64("1970-01-01T00:00:08.500000000"),
    ]),
    schema={"values": pl.Datetime("ns")})

other_timestamps = pl.LazyFrame(
    np.array([
        np.datetime64("1970-01-01T00:00:01.500000000"),
        np.datetime64("1970-01-01T00:00:02.000000000"),
        np.datetime64("1970-01-01T00:00:02.500000000"),
        np.datetime64("1970-01-01T00:00:04.500000000"),
        np.datetime64("1970-01-01T00:00:06.000000000"),
        np.datetime64("1970-01-01T00:00:06.500000000"),
    ]),
    schema={"values": pl.Datetime("ns")})

# ✅ 懒加载同步：无需 collect，全程延迟执行
synced = (
    timestamps.sort("values")
    .join_asof(
        other_timestamps.with_columns(
            pl.col("values").alias("other_values")
        ).sort("values"),
        on="values",
        strategy="nearest",
        tolerance="500ms"  # 支持 '1s', '250ms', '1us' 等字符串解析
    )
    .drop_nulls()  # 必须！移除未匹配到容差范围内的行
)

# 最终结果（仅在需要时 materialize）
result = synced.collect()
print(result)

运行上述代码，你会得到如下输出，只有时间差在500毫秒以内的记录被成功匹配：

shape: (4, 2)
┌─────────────────────────┬─────────────────────────┐
│ values                  ┆ other_values            │
│ ---                     ┆ ---                     │
│ datetime[ns]            ┆ datetime[ns]            │
╞═════════════════════════╪═════════════════════════╡
│ 1970-01-01 00:00:01.500 ┆ 1970-01-01 00:00:01.500 │
│ 1970-01-01 00:00:02.600 ┆ 1970-01-01 00:00:02.500 │
│ 1970-01-01 00:00:04.500 ┆ 1970-01-01 00:00:04.500 │
│ 1970-01-01 00:00:06.200 ┆ 1970-01-01 00:00:06.000 │
└─────────────────────────┴─────────────────────────┘

⚠️ 注意事项与最佳实践

掌握了基本用法，要想在实战中游刃有余，还得注意下面这几个细节：

• 排序是硬性前提：`join_asof` 的算法依赖于左右两张表都严格按照连接键（on 列）升序排列。如果输入数据是乱序的，结果将不可预测。所以，别忘了在连接前显式调用 `.sort()`。
• 妥善处理列名冲突：当左右两表有同名列时，Polars 默认会覆盖。因此，通常需要提前给右侧表的目标列起一个别名（例如用 `alias("other_values")`），以避免数据丢失。
• 容差单位非常灵活：`tolerance` 参数可以直接使用像 `"500ms"`、`"1s300ms"`、`"2us"` 这样符合直觉的字符串，Polars 会在底层自动将其转换为纳秒进行整数比较，省去了手动换算的麻烦。
• 性能优势显著：这套方案的时间复杂度是 O(n + m)，本质上是一种归并扫描，远优于 NumPy 那种 O(n×m) 的外积暴力计算。更重要的是，在 LazyFrame 上操作，整个同步流程可以和后续的过滤、聚合等步骤融合在一起，由 Polars 的查询优化器进行整体优化，真正实现了端到端的惰性执行。
• 明确其适用边界：`join_asof` 设计初衷是单向的“最近邻”查找。如果你需要的是双向同步（即保留双方所有未匹配的记录），那么可能需要考虑使用 `full` 或 `outer` 连接并自行实现距离逻辑。不过，这通常意味着要离开高效的懒加载模式，或许需要评估是否降级为即时执行（eager mode）或采用分块处理策略。

总的来说，`join_asof` 不仅让时序对齐的代码意图更清晰、写法更简洁，更是 Polars 为解决这类问题提供的一个高性能原生方案。只要记住排序、重命名、剔除空值这三个关键要素，你就可以放心地将其应用于生产环境中，处理海量时间序列数据的同步任务了。