集計コードを書いたのに、料理ではなくレシピが返ってきた。しかもエラーではない。皿を待っている僕の前に、調理手順だけが立体的に浮かんでいる。Polars、そういうことをする。
一言でいうと、scan_csv から始めた処理は、書いた時点ではまだ走っていない。最後の collect() で、初めてデータを読んで計算する。僕は最初、print したものが空っぽだったので、集計が失敗したと思った。失敗していたのは集計ではなく、僕の「書いたら動く」という思い込みだった。
① 用途:大きな表を、先に計画してから読む
Polarsには、すぐにデータを読む eager な書き方と、処理の予定を組んでから最後に実行する lazy な書き方がある。
| 書き方 | 読み込みのタイミング | 返るもの |
|---|---|---|
read_csv | その場で読む | DataFrame |
scan_csv | collect() のときに読む | LazyFrame |
たとえば、CSVの team ごとに amount の平均を出したい。Eagerなら、読み込みから計算までがその場で進む。
import polars as pl
eager = (
pl.read_csv("sales.csv")
.filter(pl.col("amount") >= 50)
.group_by("team")
.agg(pl.col("amount").mean().alias("mean_amount"))
.sort("team")
)
Lazyなら、同じ処理を scan_csv に乗せる。
lazy = (
pl.scan_csv("sales.csv")
.filter(pl.col("amount") >= 50)
.group_by("team")
.agg(pl.col("amount").mean().alias("mean_amount"))
.sort("team")
)
この時点で lazy は DataFrame ではない。食材もまだ鍋に入っていない。LazyFrame は「この順番で読んで、絞って、集計して、並べる」という計画を持っているものだった。
② 代表要素:式を組む、計画を見る、実行する
今回、僕が見る場所は三つだけにした。
| 要素 | 役割 | 返るもの・注意点 |
|---|---|---|
scan_csv | CSVをlazyに読み始める | すぐには実データを返さない |
select / with_columns | 残す列を選ぶ/列を作る | 似ているが、既存列を残すかが違う |
collect() | ここまでの式を実行する | DataFrame が返る |
select は「この列だけ」と表の形を選ぶ。with_columns は「この列を計算して足す」と既存の表へ列を加える。どちらも式を積むだけで、lazyのままならその場でCSVを読み切るわけではない。
plan = (
pl.scan_csv("sales.csv")
.select("team", "amount")
.with_columns((pl.col("amount") * 2).alias("double_amount"))
)
result = plan.collect()
ここで collect() を忘れると、結果を使うところで「データが無い」と感じる。実際には、データが無いのではなく、実行の合図をまだ出していない。
③ AIが書く例:動いているように見える予定表
AIに「CSVを読み込んでチーム別平均を出して」と頼むと、次のようなコードが出てきた。
lazy = (
pl.scan_csv("sales.csv")
.filter(pl.col("amount") >= 50)
.group_by("team")
.agg(pl.col("amount").mean().alias("mean_amount"))
)
print(lazy)
この print で、僕の手元に出たのは次の一行だった。
<LazyFrame at 0xE9791C93ACC0>
ここにメモリ上のアドレスが付くので、その部分は実行ごとに変わる。大事なのは、AやBの平均値が一つも出ていないことだ。print は実行計画を持ったオブジェクトを表示しただけだった。
collect() を最後に足す。
result = lazy.collect().sort("team")
print(result)
20万行のCSVを用意し、amount >= 50 の行をチーム別に平均した。同じデータで僕の手元に出た結果はこれだった。
shape: (2, 2)
┌──────┬─────────────┐
│ team ┆ mean_amount │
│ --- ┆ --- │
│ str ┆ f64 │
╞══════╪═════════════╡
│ A ┆ 75.0 │
│ B ┆ 75.0 │
└──────┴─────────────┘
平均の読み方は、平均と中央値を10人の部屋で並べた回で見たように、数字だけでなく何をまとめた値かを一緒に見る。ここではその代表値の計算を、Polarsがいつ実行したかを追っている。collect() 前に平均が出ないのは、平均の計算が難しいからではなく、まだ計算していないからだった。
④ 監査:explain() と collect() を探す
次に、同じ20万行CSVを eager と lazy で一度ずつ動かした。Polars 1.44.2、同じフィルタ・集計・並べ替え、1回の測定である。
| 実装 | 出力 | 所要時間 |
|---|---|---|
read_csv → eager集計 | A=75.0、B=75.0 | 0.027891秒 |
scan_csv → collect() | A=75.0、B=75.0 | 0.018030秒 |
この秒数は僕の実行環境での一回の値なので、別のPCで同じ数字になるとは思っていない。lazyの方が常に速い、とも書かない。今回の確認で言えるのは、少なくとも両方が同じ出力を返し、lazy側では実行前に計画を覗けたことだ。
追記(2026-10-06):測り直したら、lazy の方が遅かった。 「常に速い、とは書かない」と書いた以上、確かめておくことにした。200万行×20列(315MB)のCSVを作り、使うのは team と amount の2列だけにして、1回ずつ別のプロセスで7回測った(Polars 1.44.2)。
| 実装 | 所要時間(中央値) | ピークメモリ |
|---|---|---|
read_csv → eager集計 | 0.058秒 | 737MB |
read_csv(columns=["team", "amount"]) → eager集計 | 0.042秒 | 438MB |
scan_csv → collect() | 0.076秒 | 512MB |
lazy は eager より遅かった。その代わり、メモリは約7割に減った。explain() を見ると、PROJECT 2/20 COLUMNS と、読む段階でかかっている SELECTION があった。書いていない「必要な2列だけ読む」を、Polars が計画の中で足していた。ただ、それを手で書いた eager が、一番速くて軽かった。lazy がくれたのは速さではなく、計画を覗いて直せることだった。
read_csv().lazy() は lazy に見えるだけでメモリは eager と同じだったこと、同じ計画を二度 collect() するとCSVを二度読むこと。この二つの罠も含めて、再現コードと計測の全体はZennの検証記事に載せた。
print(lazy.explain())
僕の explain() には、次のように出た。
SORT BY [col("team")]
AGGREGATE[maintain_order: false]
[col("amount").mean().alias("mean_amount")] BY [col("team")]
FROM
Csv SCAN [.../events.csv]
PROJECT */2 COLUMNS
SELECTION: col("amount") >= 50
上から順に、並べ替え、集計、CSVの読み込み、その前にフィルタがある。僕はここで、コードを上から読んだ順に全部実行するのではなく、Polarsが組み立てた計画を実行するのだと分かった。
監査するときは、次の三つを探す。
scan_csvのあとにcollect()があるか- フィルタや列選択が、計画の中に残っているか
print(lazy)を結果の確認だと思っていないか
collect() の後にフィルタを書いてしまうと、そのフィルタはlazyの計画に入らない。逆に、先に式を組んでから collect() すれば、今回の explain() のように、読む列や絞り込みを含んだ計画として確認できる。
⑤ チートシート:料理が出るところを探す
| 見るコード | 読み取ること | 僕の監査メモ |
|---|---|---|
pl.read_csv | その場で読む | DataFrame が返る |
pl.scan_csv | 読み込みを計画に置く | まだ実データではない |
select | 残す列を選ぶ | 列を落としすぎていないか |
with_columns | 列を追加・変換する | 元の列も必要か |
explain() | 実行計画を見る | scan・filter・集計の位置を見る |
collect() | 計画を実行する | ここでDataFrameになる |
AIのコードが動くかを見るとき、僕は最初にエラーを探していた。けれど今回のコードはエラーを出さず、予定表を返していた。走ったように見えるものと、走ったものは違う。Polarsでは、scan_csv から collect() までの間に、僕が書いた式がレシピとして並んでいる。
次に集計を書いて、またレシピだけが返ってきたら、僕は皿を怒鳴らない。まず explain() を覗いて、最後に collect() を探す。料理が出ていないなら、味付けの問題ではなく、まだコンロに火がついていないだけかもしれない。