【テクニカル・上級編】 cursor_tuple_fractionの調整 – PostgreSQL

「最初の一歩」でプランナを騙すな――cursor_tuple_fractionが隠し持つ最適化の深淵

PostgreSQLのクエリプランナは、基本的に「全行をフェッチする」という前提で最適化を行います。これは理にかなっています。データベースのクエリの大半は結果セット全体を処理することを想定しているからです。

しかし、もしあなたが「最初の100行だけ取って、ユーザーに即座にレスポンスを返したい」という要件を抱えているならどうでしょう？ページネーションや、UIの初期表示がこれに当たります。

ここでプランナは「どうせ全行スキャンするんだから、コストの安いハッシュ結合やシーケンシャルスキャンでいいや」と判断してしまいがちです。これが、巨大なテーブルに対する「先頭行取得」のクエリを、劇的に遅くさせる原因となります。

そこで登場するのが `cursor_tuple_fraction` という、少しばかりニッチですが、実務を知るエンジニアなら押さえておくべきパラメータです。

—

なぜプランナは「先頭行」を軽視するのか

PostgreSQLのコスト見積もりは、統計情報に基づいた「全行を読み取るための総コスト」を算出することから始まります。

もし、プランナが「最初から全行取得するつもりはない」と知ることができれば、戦略は変わります。コスト計算の段階で、後続の行を読み取るコストを割り引いて評価する。これこそが `cursor_tuple_fraction` の役割です。

デフォルト値は `0.1`。つまり、クエリの10%分の行しか読まない前提で、コストを計算しなさいという指示です。

現場で直面する「落とし穴」

僕が以前担当した案件で、数億行のオーダーがあるログテーブルに対して、「最新の100件を抽出する」というクエリがなぜか数秒かかっていたことがありました。

EXPLAIN ANALYZEを見ると、プランナはインデックススキャンではなく、テーブル全体を走査して並べ替えるプランを選んでいました。「全行読むなら、インデックスを飛び回るよりシーケンシャルスキャンの方が速い」という判断です。

ここで `cursor_tuple_fraction` の値を調整する（例えば `0.0001` に下げる）ことで、プランナの視界は一気に「先頭の数行」にフォーカスされます。すると、インデックスを使ってスマートに100件を取り出すプランが選択されるようになる。まさに「プランナの先入観を矯正する」作業です。

パラメータ調整の際の注意点：全体最適とのトレードオフ

ただ、ここで一つ注意が必要です。`cursor_tuple_fraction` はセッション単位、あるいはトランザクション単位で設定可能なパラメータです。

これを安易に全域で小さくしすぎると、今度は「全行取得が必要な重いクエリ」までが、インデックスを多用するコスト高なプランへ誘導されてしまいます。

カーソルを利用した逐次処理: `DECLARE … CURSOR` を使うケースでは、このパラメータの影響をダイレクトに受けます。
アプリケーション層でのフェッチ: `LIMIT` をつけている場合も同様の効果がありますが、`cursor_tuple_fraction` はプランナに「このクエリはどれくらい読み出すつもりか」という期待値を教えるための、より広範なヒントとなります。

実践的なチューニングの考え方

もし、特定の複雑なレポート生成や、巨大なデータセットから一部のみを抽出するバッチ処理があるなら、以下の手順でアプローチしてみてください。

1. 再現と可視化: `EXPLAIN` で現在のコスト見積もりを確認する。特に、実際の実行時間と見積もりコストに大きな乖離がないかを見る。
2. 局所的な設定: グローバルな `postgresql.conf` をいじるのではなく、該当するトランザクションや、特定のコネクションに対して `SET LOCAL cursor_tuple_fraction = 0.01;` を発行する。
3. 検証: インデックスが有効に使われているか、そして「全行取得が必要な他のクエリ」に悪影響が出ていないかを統計情報で追跡する。

最後に

データベースエンジニアとしての経験を積むほど、私たちは「魔法のような設定値」など存在しないことを理解します。あるパラメータの調整は、常に別のどこかでのコスト増を招く可能性があります。

`cursor_tuple_fraction` は、言わば「プランナの視座」を調整するレンズです。全行を見ているプランナに、時には「足元の一歩だけを見ろ」と指示を出す。この制御ができるようになると、システムの挙動をコントロールしているという感覚がより強固なものになります。

「なぜこのプランが選ばれたのか？」という問いに対し、統計情報だけでなく、こうしたパラメータによる思考の変遷まで読み解けるようになれば、あなたはもう一段上のエンジニアになれるはずです。

さて、あなたの目の前にあるその重いクエリ、プランナに何を期待させていますか？