io-bound-data-processing

制約のあるリソースでのコミュニティ I/O バウンドデータ処理のベストプラクティス

RAM を超えるデータセットを、計算能力の低い単一マシンで処理するエンジニア向けのリファレンスです。実行ライフサイクルへの影響度順にまとめています。表の上部にあるルールは、ジョブがそもそも実行できるかどうかを左右し、下部のルールは最後の 10％を改善します。上から順に最適化してください。

対象範囲： ノートパソコン、2 vCPU のコンテナ、または Raspberry Pi クラスのノードで行う、実際の ETL／データエンジニアリング／バッチ処理で見られるパターンです。ストリーミング、フォーマット、チャンク化、スピル、バックプレッシャー、コーデック、および I/O バウンドのボトルネックに実際に適合する並行処理モデルを扱います。対象外（別途扱われています）：アルゴリズムの基本要素そのもの（computer-science-algorithmsを参照）、単一マシンを超える分散コンピューティング（Spark／Dask を使用）、データベースエンジンの内部実装（公式ドキュメントを参照）。

Apache Arrow / Parquet のドキュメント、Polars User Guide、DuckDB のドキュメント、pandas — 大規模データセットへのスケーリング、Linux の man ページ（mmap(2)、sendfile(2)、posix_fadvise(2)）、Brendan Gregg の USE メソッドと『Systems Performance』、Kleppmann の『Designing Data-Intensive Applications』、および zstd／lz4 のリファレンスベンチマークから要点をまとめています。

適用するタイミング

次のような場合に、これらのルールを参照してください。

• 小規模なマシンでジョブが OOM キルされたり、スワップが発生したり、予想より大幅に遅くなったりする
• 入力が RAM よりも大きく、スキャン、フィルタリング、集計、ソート、結合が必要である
• パイプラインの各段階の間に上限のないバッファーがある、または「ストリーミング」ジョブ中にメモリ使用量が線形に増加する
• 行ごとに RTT が発生する書き込みがある（行ごとの INSERT、URL ごとの requests.get、レコードごとの f.read(32)）
• フォーマット／コーデック／シリアライザーを選定しており、その選択が大規模な処理に影響する
• top で CPU 使用率が低く iowait が高い、またはどちらが原因かわからない
• 「遅いけれど原因がわからない」—まず obs- カテゴリから確認してください

優先度別のルールカテゴリ

#	カテゴリ	プレフィックス	影響度	連鎖的に影響する理由
1	メモリの適切な管理	mem-	重大	RAM にすべて読み込むと、制約のあるマシンでは以降のあらゆる手法が無意味になります
2	I/O アクセスパターン	io-	重大	ディスク／ネットワークは RAM より 10³～10⁶ 倍遅く、アクセスパターンが実行時間を左右します
3	データフォーマットとエンコーディング	fmt-	高	フォーマットによって、ロジックを実行する前に I/O 量とデコードコストの下限が決まります
4	チャンク化とバッチ処理	batch-	高	粒度によってピークメモリが決まり、項目ごとのオーバーヘッドが分散されます
5	ディスクへのスピルと外部メモリ	spill-	高	データが RAM を超える場合、「適切にスピルする」か「OOM」かの選択になります
6	パイプライン処理とバックプレッシャー	pipe-	中～高	高速なプロデューサーと低速なシンクの間に上限のないバッファーがあると、OOM が発生します
7	圧縮とシリアライズ	codec-	中	CPU と I/O をトレードオフします。適切なコーデックを選ぶと桁違いに効率が向上します
8	I/O バウンドのワークロードにおける並行処理	conc-	中	非同期処理／スレッド／プロセスはそれぞれ異なる手段です。誤ったモデルを選ぶと CPU を無駄にします
9	可観測性とスループットのチューニング	obs-	低～中	測定できないものは調整できません。iowait は CPU バウンドを意味しません

クイックリファレンス

1. メモリ管理（CRITICAL）

• mem-stream-dont-slurp — ソースをチャンクごとに反復処理します。ピーク時の RAM 使用量はファイルサイズではなく、チャンクサイズで決まります
• mem-prefer-generators-over-lists-for-pipelines — ジェネレーターはデータを流し、リストはすべてをメモリ上に展開します
• mem-shrink-dtypes-before-loading — 整数型を小さくし、カテゴリ型を使用すると、読み込み時のメモリ使用量を 2～8 倍削減できます
• mem-use-views-not-copies — コピーせずにスライスします。NumPy／Arrow のゼロコピーセマンティクスを活用します
• mem-bound-the-working-set — チャンクサイズは切りのよい数値ではなく、「予算 ÷ 行サイズ × 増幅率」で算出します
• mem-release-references-explicitly — 中間データを破棄し、ピーク使用量が N × チャンクにならないようにします

2. I/O アクセスパターン（CRITICAL）

• io-prefer-sequential-over-random — オフセットをソートし、カーネルにヒントを与えて、先読みの効果を活用します
• io-buffer-explicitly-for-small-records — BufferedReader を使うと、システムコールを 1000 分の 1 に減らせます
• io-stream-http-bodies-with-iter-content — .content ではなく、stream=True と iter_content を使います
• io-mmap-for-random-or-shared-large-files — ランダムアクセスには、ゼロコピーとオンデマンドページングを使用します
• io-async-for-many-concurrent-streams — 1 つのスレッドで数千の await を処理します
• io-batch-and-pipeline-network-roundtrips — COPY、パイプライン、複数キー対応エンドポイント、HTTP/2 を活用します
• io-zero-copy-when-moving-bytes-as-is — sendfile、copy_file_range、shutil.copyfile を使います

3. データ形式とエンコーディング（HIGH）

• fmt-columnar-for-analytical-scans — フィルターと列選択を伴う処理には Parquet／Arrow を使います
• fmt-line-delimited-for-streaming-row-ingest — ストリーミングには JSON 配列ではなく NDJSON を使います
• fmt-push-predicates-into-the-reader — 行グループの統計情報を使ってチャンク全体をスキップします
• fmt-prefer-schema-on-write-when-possible — 可能な場合はスキーマオンリードよりスキーマオンライトを優先します。型付き列は常にスキーマオンリードに勝ります
• fmt-avoid-deeply-nested-json-for-hot-paths — ホットパスにはフラットなスキーマを使うか、バイナリ形式を使います

4. チャンク化とバッチ処理（HIGH）

• batch-pick-chunk-size-by-memory-budget — 固定値ではなく、メモリ予算から算出します
• batch-use-vectorized-apis-not-row-loops — iterrows ではなく、NumPy／Polars／Arrow のカーネルを使います
• batch-process-with-stable-iterators — iter_batches、chunksize=、collect(streaming=True) を使います
• batch-coalesce-writes-with-buffered-output — COPY／executemany と、サイズを指定した書き込みバッファーを使います
• batch-keyset-pagination-over-offset — WHERE id > $last_id を使い、深いカーソルで OFFSET N は決して使いません

5. ディスクへのスピルと外部メモリ（HIGH）

• spill-external-merge-sort-when-data-exceeds-ram — メモリに収まらないデータのソート。可能であれば sort / DuckDB に委譲します
• spill-partition-by-hash-for-out-of-core-groupby-join — 両側をハッシュでパーティション分割し、パーティションごとに処理します
• spill-use-temp-files-not-process-memory — SpooledTemporaryFile を使い、無制限の BytesIO は使いません
• spill-use-engines-that-spill-automatically — DuckDB / Polars / Dask にスピルを任せます

6. パイプライン処理とバックプレッシャー（MEDIUM-HIGH）

• pipe-use-bounded-queues-for-producer-consumer — 有界 Queue がバックプレッシャーの仕組みになります
• pipe-apply-backpressure-from-slow-stages — 遅いシンクが高速なソースを抑制します
• pipe-prefer-pull-iteration-over-push-callbacks — プル方式は自然にバックプレッシャーがかかります。プッシュ方式ではポリシーが必要です
• pipe-checkpoint-progress-for-resumability — 各バッチの後にアトミックなチェックポイントを作成し、やり直しを限定します

7. 圧縮とシリアライズ（MEDIUM）

• codec-zstd-or-lz4-as-defaults-not-gzip — アクセスパターンに応じてコーデックを選びます。gzip はレガシーです
• codec-dictionary-encoding-for-repetitive-strings — カーディナリティの低い列で 5～50 倍の効果があります
• codec-prefer-binary-protocols-over-json-for-rpc — 頻繁にデータが流れる箇所では Protobuf / Arrow IPC / MsgPack を使います
• codec-train-a-zstd-dictionary-for-many-small-payloads — 1 KB 未満のメッセージには zstd --train を使います

8. I/O バウンドなワークロード向けの並行処理（MEDIUM）

• conc-asyncio-for-many-network-streams-not-for-cpu — Asyncio は待機を多重化しますが、計算には役立ちません
• conc-thread-pools-for-blocking-io-libraries — ブロッキング I/O 中は GIL が解放されるため、スレッドが有効です
• conc-overlap-compute-with-prefetch — バックグラウンドスレッド / コルーチンで 1 バッチ先行させます
• conc-tune-parallelism-to-the-bottleneck — ワーカー数をボトルネックとなるリソースに合わせます

9. 可観測性とスループットの調整（LOW-MEDIUM）

• obs-measure-iowait-not-just-cpu — iostat -x、vmstat、psutil で実際のボトルネックを見つけます
• obs-instrument-throughput-rows-per-second — 処理率を使えば実行ごとの比較が可能になり、性能低下を検出できます
• obs-profile-with-py-spy-or-strace-for-syscall-storms — 推測せず、アタッチして調査します

使い方

まず、問題に当てはまる質問を探します。

• 「OOM が発生する／ストリーミングジョブ中に RAM 使用量が直線的に増える」 → mem- と pipe-（バッファーが無制限に増えているか、反復ごとに蓄積している可能性があります）
• 「CPU はアイドル状態なのに、ディスク使用率が 100 % になっている」 → io-（ランダムアクセス、バッファーなしの I/O、または不適切な形式が原因の可能性があります）
• 「この 10 GB のファイルを読み込むのに、なぜこんなに時間がかかるのか？」 → fmt-columnar-for-analytical-scans と io-buffer-explicitly-for-small-records から始めます
• 「チャンクのサイズはどれくらいがよいか？」 → batch-pick-chunk-size-by-memory-budget
• 「データが RAM に収まらない」 → spill-（自動でスピルするエンジンを優先してください：spill-use-engines-that-spill-automatically）
• 「ネットワーク呼び出しが大量にある」 → io-batch-and-pipeline-network-roundtrips、io-async-for-many-concurrent-streams
• 「ワーカーを追加しても改善しなかった」 → conc-tune-parallelism-to-the-bottleneck、obs-measure-iowait-not-just-cpu
• 「処理が遅いが、原因がわからない」 → まず obs- を確認します。何かを変更する前にプロファイリングしてください

コード例には Python を使用しています（幅広い読者にとって最も読みやすいためです）。考え方はほかのエコシステムにも当てはまります。ほかのエコシステムの同等のライブラリ（Arrow C++/Rust/Java、Polars Rust、あらゆる環境の DuckDB、libuv 形式の非同期処理）も同じパターンに従います。

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルールを追加するためのテンプレート
metadata.json	バージョンとリファレンス情報
AGENTS.md	自動生成された目次ナビゲーション

関連スキル

• computer-science-algorithms — このスキルの基盤となるアルゴリズムの基本要素（外部マージソート、スケッチ、ハッシュパーティショニング、サンプリング）