polars

Polars 中容易踩坑的地方

Polars 的大部分内容都已在训练数据中得到充分覆盖。本技能仅记录那些不会在小数据测试中显现、因而容易被忽略的细节。

join 默认不保留行顺序

DataFrame.join 和 LazyFrame.join 接受一个仅限关键字的 maintain_order 参数，默认值为 'none'：

# ❌ Result row order is NOT guaranteed. It may match the left frame on small
#    data, then differ on larger data, across runs, or across polars versions.
result = df.join(meta, on="sample_id", how="left")

# ✅ Preserve the left frame's order explicitly when downstream code relies on it.
result = df.join(meta, on="sample_id", how="left", maintain_order="left")

风险在于，对于你测试时使用的小规模输入，默认行为通常看起来是有序的——只有在较大的数据上启用多线程哈希连接时，Polars 才会重新排序。依赖位置来对齐连接结果的代码（hstack、赋值 NumPy 数组或 pl.Series、索引）随后就会在生产环境中悄无声息地出错。

how="left" 并不能避免这个问题：它控制保留哪些键，而不是行顺序。左连接仍可能相对于左侧 DataFrame 重新排列输出。

**规则：**如果连接后的任何操作依赖行顺序，就要显式传入 maintain_order。不要根据观察到的行为推断顺序。

maintain_order 的取值

取值	含义
'none'（默认）	不保证顺序；速度最快。顺序可能因版本、运行次数或数据规模而变化。
'left'	保留左侧 DataFrame 的行顺序。
'right'	保留右侧 DataFrame 的行顺序。
'left_right'	优先保留左侧顺序，然后是右侧顺序。
'right_left'	优先保留右侧顺序，然后是左侧顺序。

对于“将查找表连接到我的 DataFrame，并保留我的 DataFrame 的顺序”这一常见情况，请使用 maintain_order="left"。

常见错误

错误	修正方法
执行 df.join(meta, on="id") 后再使用 hstack／赋值位置数组或 Series	传入 maintain_order="left"——连接可能会相对于数组重新排序。
“左连接会保留左侧 DataFrame 的顺序”	错误。how="left" 控制保留哪些键，而不是行顺序。顺序由 maintain_order 控制。
因为小规模测试通过就相信顺序不会变	小规模数据会掩盖重新排序。请设置 maintain_order，不要依赖观察到的行为。
位置传入 df.join(meta, "id", maintain_order="left")	maintain_order 仅限关键字传参——请将其作为关键字传入。
每次连接都使用 maintain_order	只有在后续操作依赖顺序时才需要。当你会重新排序或将输出视为集合时，可以省略它（速度更快）。