pandas.merge() OOM因全量加载建哈希表，需改用小表建索引+大表分块流式JOIN；务必校验键无NaN、类型一致、无重复；DuckDB或Dask更稳。
为什么直接 pandas.merge() 会 OOM
内存受限时，pandas.merge() 默认把两张表全载入内存建哈希表，哪怕只是 2GB + 1.5GB 的 CSV，JOIN 后中间结构可能暴涨到 5GB+，触发 MemoryError。这不是数据量“太大”，而是它没做分块策略——连 chunksize 参数都不支持在 merge() 里用。
核心思路：外键对齐 + 分块哈希 + 临时文件中转
不能一次读完大表，就得让小表（驱动表）先建好内存哈希，再流式读大表（被驱动表）分块匹配。但前提是：JOIN 键必须能对齐——比如都是 user_id 且类型一致、无 NaN 冲突。否则分块后无法保证语义正确。
- 选小表做
build_table（通常 ≤ 500MB），一次性pd.read_csv()加索引：build_df.set_index('key', inplace=True) - 大表用
pd.read_csv(..., chunksize=N)流式读（N 依内存定，常见 5k–50k 行） - 每块调
chunk.merge(build_df, left_on='key', right_index=True)，结果立即写入tempfile.NamedTemporaryFile(delete=False) - 最后用
pd.concat([pd.read_csv(f) for f in temp_files], ignore_index=True)合并（仍可分批 concat 避免峰值）
容易踩的坑：NaN、类型不一致、重复键
分块 JOIN 最怕隐式错误——某一块 merge 出来空结果，你根本看不出是键不匹配还是读错了列。务必提前校验：
-
build_df['key'].isna().sum()和chunk['key'].isna().sum()都得为 0；有 NaN 就得先dropna(subset=['key'])或填默认值 -
build_df['key'].dtype必须和chunk['key'].dtype完全一致（int64vsInt64不行，object里混数字字符串也不行） - 如果
build_df中key有重复，merge会爆炸式膨胀——用build_df = build_df[~build_df.index.duplicated(keep='first')]去重（或按业务逻辑选keep='last'）
比纯 Pandas 更稳的选择：Dask 或 DuckDB
自己手写分块合并容易漏边界 case（比如最后一块没 flush、临时文件没清理）。如果只是要可靠 JOIN，dask.dataframe.merge() 内置 chunking + spill-to-disk，默认就走外键哈希；或者更轻量的 duckdb：
立即学习“Python免费学习笔记（深入）”；
import duckdb
conn = duckdb.connect(database=':memory:') # 或指定 .db 文件实现磁盘暂存
conn.execute("CREATE TABLE big AS SELECT * FROM read_csv_auto('big.csv')")
conn.execute("CREATE TABLE small AS SELECT * FROM read_csv_auto('small.csv')")
result = conn.execute("SELECT * FROM big JOIN small USING(key)").df()DuckDB 在内存不足时自动落盘，且对 CSV 类型推断比 Pandas 稳，USING(key) 还能避免左右表 key 名不一致的问题。真正卡内存时，它比手写分块更少出幺蛾子。
关键不在“怎么写循环”，而在确认键干净、类型对齐、临时路径可写——这些比算法本身更容易让整个流程静默失败。
