【Pandas】pandas DataFrame to_hdf

Pandas2.2 DataFrame

Serialization IO conversion

pandas DataFrame to_hdf() 方法

pandas.DataFrame.to_hdf() 是 Pandas 提供的用于将 DataFrame 写入 HDF5 文件的方法。HDF5（Hierarchical Data Format）是一种适用于存储和管理大规模科学数据的二进制文件格式，支持高效读写、压缩、分组结构等特性。

方法签名

DataFrame.to_hdf(
    path_or_buf,
    *,
    key,
    mode='a',
    complevel=None,
    complib=None,
    append=False,
    format=None,
    index=True,
    min_itemsize=None,
    nan_rep=None,
    dropna=None,
    data_columns=None,
    errors='strict',
    encoding='UTF-8'
)

参数说明

返回值

无返回值，直接写入 HDF5 文件。

示例代码

示例 1：基础用法（固定格式）

import pandas as pd

# 创建示例 DataFrame
df = pd.DataFrame({
    'id': [1, 2, 3],
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [25, 30, None]
})

# 写入 HDF5 文件（固定格式）
df.to_hdf('example.h5', key='df_fixed', mode='w')

结果：

• 生成一个名为 example.h5 的 HDF5 文件。
• 其中包含一个键为 df_fixed 的数据集，使用默认的 fixed 格式存储。

示例 2：使用 table 格式并指定查询列

# 使用 table 格式，并指定可查询列
df.to_hdf('example.h5', key='df_table', mode='a', format='table', data_columns=['name', 'age'])

结果：

• 追加写入同一个 HDF5 文件。
• 键为 df_table 的数据集支持后续通过 where 条件查询，例如：

# 查询 name='Alice' 的记录
result = pd.read_hdf('example.h5', key='df_table', where='name == "Alice"')
print(result)

输出：

   id   name   age
0   1  Alice  25.0

示例 3：启用压缩

# 启用 zlib 压缩
df.to_hdf('compressed_example.h5', key='df_compressed', mode='w',
          complevel=9, complib='zlib')

结果：

• 生成压缩后的 HDF5 文件，适合节省磁盘空间。

示例 4：设置字符串列最大长度

# 设置 name 列至少存储 20 个字符
df.to_hdf('example.h5', key='df_min_itemsize', mode='a',
          min_itemsize={'name': 20})

用途：

• 避免长字符串被截断，尤其是在频繁追加写入时。

示例 5：追加写入（append）

# 第一次写入
df.head(2).to_hdf('appended.h5', key='df_append', mode='w', format='table')

# 追加写入
df.tail(1).to_hdf('appended.h5', key='df_append', mode='a', format='table')

结果：

• appended.h5 中的 df_append 数据集包含所有三行数据。

注意事项

• 推荐使用 format='table' 如果你需要进行条件查询。
• append=True 仅在 format='table' 下有效。
• 支持多种压缩算法，适合大数据归档。
• 若需读取 HDF5 文件，可使用 pd.read_hdf()。
• HDF5 文件结构复杂，建议使用专门工具（如 h5py, hdfview）查看内部结构。

总结

安装依赖

pip install tables