polars

Polars の注意点

Polars の大部分は、学習データで十分にカバーされています。このスキルでは、小規模データのテストでは表面化せず、見落とされやすい注意点のみを説明します。

join はデフォルトで行の順序を保持しません

DataFrame.join と LazyFrame.join には、デフォルトが 'none' のキーワード専用引数 maintain_order があります。

# ❌ 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" にしても解決しません。これは保持するキーを制御するものであり、行の順序は制御しません。左結合でも、左側のフレームに対して出力の順序が変わることがあります。

ルール： 結合後の処理が行の順序に依存する場合は、maintain_order を明示的に指定してください。観察した動作から順序を推測しないでください。

maintain_order の値

値	意味
'none'（デフォルト）	順序は保証されません。最も高速です。バージョン、実行ごと、データサイズによって変わることがあります。
'left'	左側のフレームの行順序を保持します。
'right'	右側のフレームの行順序を保持します。
'left_right'	まず左側の順序を保持し、次に右側の順序を保持します。
'right_left'	まず右側の順序を保持し、次に左側の順序を保持します。

「ルックアップテーブルをフレームに結合し、フレームの順序を維持したい」という一般的なケースでは、maintain_order="left" を使用してください。

よくある間違い

間違い	修正方法
df.join(meta, on="id") の後に hstack／位置指定の配列や Series を代入する	maintain_order="left" を指定してください。結合によって配列に対する順序が変わることがあります。
「左結合なら左側のフレームの順序が保たれる」	誤りです。how="left" は保持するキーを制御するものであり、行の順序は制御しません。順序は maintain_order によって決まります。
小さなテストで問題がなかったからと、順序を信頼する	小規模なデータでは並べ替えが表面化しません。観察した動作に頼るのではなく、maintain_order を設定してください。
df.join(meta, "id", maintain_order="left") のように位置指定で渡す	maintain_order はキーワード専用です。キーワードとして渡してください。
すべての結合で maintain_order を使う	後続の処理で順序が重要な場合にのみ必要です。再度並べ替える場合や、出力を集合として扱う場合は省略してください（より高速になります）。