データサイエンスのいろは · ⏱️ 読了目安 14分

集計したのに料理が出てこない|Polarsの遅延評価

集計コードを書いたのに、料理ではなくレシピが返ってきた。しかもエラーではない。皿を待っている僕の前に、調理手順だけが立体的に浮かんでいる。Polars、そういうことをする。

一言でいうと、scan_csv から始めた処理は、書いた時点ではまだ走っていない。最後の collect() で、初めてデータを読んで計算する。僕は最初、print したものが空っぽだったので、集計が失敗したと思った。失敗していたのは集計ではなく、僕の「書いたら動く」という思い込みだった。

① 用途:大きな表を、先に計画してから読む

Polarsには、すぐにデータを読む eager な書き方と、処理の予定を組んでから最後に実行する lazy な書き方がある。

書き方読み込みのタイミング返るもの
read_csvその場で読むDataFrame
scan_csvcollect() のときに読む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 は「この順番で読んで、絞って、集計して、並べる」という計画を持っているものだった。

レシピは返ってきた。料理が出るのは、collect()のあとだった。
レシピは返ってきた。料理が出るのは、collect()のあとだった。

② 代表要素:式を組む、計画を見る、実行する

今回、僕が見る場所は三つだけにした。

要素役割返るもの・注意点
scan_csvCSVを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.00.027891秒
scan_csv → collect()A=75.0、B=75.00.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() を探す。料理が出ていないなら、味付けの問題ではなく、まだコンロに火がついていないだけかもしれない。

やあ、ここまで読んでくれてありがとう。

身近な疑問に引っかかったら、数えて確かめないと気が済まない。引っかかってから「なるほど」に辿り着くまでの過程を置く場所「猫だくさん」。