如何在Python中使用Pandas读取HDF5格式的高性能大型数据集？

先说说各位在使用Pandas读取HDF5文件时，最让人头疼的两个问题：要么是内存直接爆掉，要么是收到一个莫名其妙的`KeyError: 'No object named … in the file'`。

问题出在HDF5文件的结构上。它不是一个“一张表对应一个文件”的简单玩意儿，而是一个像文件系统一样的容器，里头可以存放多个数据集（就是代码里的`key`）。而且，它默认不会告诉你里面到底有哪些东西。你直接调用`pd.read_hdf('data.h5')`，Pandas会尝试去读取一个叫`'/df'`或`'table'`的默认键。但现实是，很多生产环境下的HDF5文件，根本不会按这个约定来命名。

这时候，正确的做法是先摸清文件结构，用`h5py`来探路：

import h5py
with h5py.File('data.h5', 'r') as f:
    print(list(f.keys()))  # 看看顶层有哪些group
    # 如果还有嵌套，比如 '/processed/2023Q1/sales'，就需要写上完整路径

另外，还有两个常见坑需要留意：

• pd.read_hdf() 只能读取它自己用 pd.to_hdf() 写进去的 Table 或 Fixed 格式。如果这个HDF5是用 h5py、MATLAB 或者别的什么工具生成的原始数据集，那它就没辙了。
• 键名里如果带着斜杠（比如 '/raw/feature_matrix'），引用时一定要加引号，并且开头的那个 / 不能省略。
• 一个容易忽略的安全点：处理大文件时，务必用 mode='r'（只读模式），不小心用了 'a' 模式，可能会触发一些意想不到的写入操作，甚至把文件锁死。

如何用 pd.read_hdf() 高效读取子集，避免全量加载

HDF5 支持按行过滤和按列选取，但这有个前提：只对一种格式生效——format='table'（也就是 PyTables 格式）。如果当初写入时用的是 format='fixed'，那这些参数就全白费了，Pandas还是会老老实实把整个文件砸进内存里。

读取时，有几个关键参数组合值得记住：

• where：传入查询条件，比如 "date > '2023-01-01' & category == 'A'"。但要注意，前提是这些列在写入时已经被索引了（通过 data_columns=['date', 'category'] 指定）。
• columns：指定你真正需要的列名列表，比如 ['user_id', 'event_time']，这能显著减少内存占用，属于“精准打击”。
• start/stop：按行号切片读取。对于没有索引的大宽表，这个方法比 where 更快，但它没法做条件过滤。
• iterator=True + chunksize=10000：返回一个 HDFStore 迭代器。如果你要处理的数据流非常大，这个组合能帮你实现流式处理，一点一点消化。

举个例子，带条件加列筛选，清爽又高效：

df = pd.read_hdf(
    'data.h5', 
    key='/sales/table', 
    where="region == 'CN' and revenue > 1000",
    columns=['order_id', 'revenue', 'ts'],
)

用 h5py 手动读取原始 dataset 后转为 DataFrame 的适用场景

当你的HDF5文件是科学计算常用的格式（比如直接存了NumPy数组），或者是由非Pandas工具生成的，那么pd.read_hdf()就会彻底失效。这时候，必须请出底层的 h5py 来亲自操刀。

典型的操作流程是这样：

• 用 f[key] 拿到数据集对象，再调用 [...] 触发读取。特别提醒：[...] 会一次性把数据全量加载到内存，如果文件很大，务必小心。
• 数据太大怎么办？用 f[key][start:stop] 切片读取，然后分批拼成DataFrame，这是避免OOM的常规操作。
• 列名需要手动构造：pd.DataFrame(data, columns=col_names)。这些列名通常藏在同一个group的 attrs 里，或者单独有个group存放。
• 时间戳字段经常是 int64 类型（纳秒级的Unix时间戳），需要手动转换：pd.to_datetime(..., unit='ns')。

看一个安全切片读取的例子：

import h5py
import numpy as np

with h5py.File('sensor.h5', 'r') as f:
    dset = f['/measurements']
    # 分块读取，避免内存爆炸
    chunk = dset[0:50000]  # shape (50000, 12)
    df = pd.DataFrame(chunk, columns=['temp', 'hum', 'vib_x', ...])

写入时就该注意的三点，决定后续读取效率

读取慢，或者功能受限，90%的锅都能甩到写入时的配置上。关键参数必须在 to_hdf() 时明确指定，不能偷懒：

• format='table'：这是开启查询、列选取、增量追加等高级功能的大门。而 format='fixed' 虽然写入快，但功能受限，后续只能全量读取。
• data_columns：把你未来要频繁过滤的字段（比如 date, user_id）都加到这个列表里。否则，where 参数就是个摆设。
• complib='blosc' + complevel=9：这对组合对数值型大数据的压缩效率高，解压速度也快。相比之下，zlib 在Pandas HDF5里的支持表现就比较一般。

很多新手图省事，写出来往往是这样的：

# ❌ 不推荐：没指定 format 和 data_columns
df.to_hdf('out.h5', 'data')

但真正懂行的人，会这么写：

# ✅ 推荐：可过滤、可选列、高压缩
df.to_hdf(
    'out.h5', 
    'data', 
    format='table',
    data_columns=['timestamp', 'device_id'],
    complib='blosc',
    complevel=9
)

说到底，真正难的不是怎么读，而是先搞清楚这个HDF5文件里到底存了什么、是怎么存的。花两分钟时间，用 h5py 看一眼结构，远比你在那里反复试错 key 和 where 参数要省事得多。这，才是效率的根源。