23.2 二进制格式导出

核心内容

将 DataFrame 导出为 Pickle、Feather、Parquet、HDF 等二进制格式，具备「速度快、体积小、保留 dtype」的优势。

一、to_pickle() — Python 原生序列化

import pandas as pd
 
df = pd.DataFrame({'A': [1, 2, 3], 'B': ['x', 'y', 'z']})
 
# 导出
df.to_pickle('df.pkl')
 
# 读取
df_load = pd.read_pickle('df.pkl')

特性	说明
保留内容	数据 + index + columns + dtype + attrs
压缩	自动使用 pickle 协议，可配合 gzip 等
安全	⚠️ 不要加载不可信的 pickle 文件（存在代码执行风险）
跨语言	仅限 Python

# 带压缩
df.to_pickle('df.pkl.gz', compression='gzip')

安全警告

Pickle 文件可执行任意代码，仅应从可信来源加载。

二、to_feather() — Feather 格式

Feather 是 Apache Arrow 定义的轻量列式二进制格式，读写极快。

# 导出（需要 pyarrow 或 feather-format）
df.to_feather('data.feather')
 
# 读取
df_load = pd.read_feather('data.feather')

特性	说明
速度	极快（接近内存拷贝速度）
保留 dtype	完整保留（含 nullable、category 等）
依赖	需要 pyarrow
设计目标	跨语言数据交换（R / Python）
限制	单 DataFrame，无压缩选项（Arrow IPC 本身高效）

# 在 R 中使用
# library(feather); read_feather("data.feather")

三、to_parquet() — Parquet 列式存储

Parquet 是 Hadoop 生态广泛使用的列式格式，压缩率高、适合大数据分析。

# 基础导出
df.to_parquet('data.parquet')
 
# 常用参数
df.to_parquet(
    'data.parquet',
    engine='pyarrow',        # 'pyarrow' / 'fastparquet'
    compression='snappy',    # 'snappy' / 'gzip' / 'zstd' / 'lz4' / None
    index=True,              # 是否保存索引
    partition_cols=['year'], # 按列分区存储（目录结构）
    storage_options={},      # S3 / GCS 等对象存储配置
    coerce_timestamps='ms',  # 时间戳精度转换
    allow_truncated_timestamps=False,
    row_group_size=10_000    # 行组大小
)
 
# 读取
df_load = pd.read_parquet('data.parquet')

特性	说明
压缩比	高（列式 + snappy / zstd）
大数据生态	Spark / Hive / DuckDB 通用
保留元数据	schema 完整保留
分区	partition_cols 目录分区
谓词下推	仅读取所需列（columns 参数）

# 分区分目录示例
df.to_parquet('output/', partition_cols=['region'])
# output/
# ├── region=North/
# │   └── part-0.parquet
# └── region=South/
#     └── part-0.parquet
 
# 只读部分分区
import pyarrow.parquet as pq
table = pq.read_table('output/', filters=[('region', '=', 'North')])

四、to_hdf() — HDF5 格式

HDF5 支持多数据集、分层存储，适合科学计算场景。

# 基础导出
df.to_hdf('data.h5', key='df')
 
# 常用参数
df.to_hdf(
    'data.h5',
    key='mydata',              # 数据集键名
    mode='w',                  # 'w' 覆盖 / 'a' 追加 / 'r' 只读
    format='table',            # 'fixed' 固定（快）/ 'table' 表格（可查询）
    append=True,               # format='table' 时追加
    complevel=5,               # 压缩级别 0-9
    complib='zlib',            # 'zlib' / 'lzo' / 'bzip2' / 'blosc'
    data_columns=['A', 'B'],   # 可查询的列（table 格式）
    encoding='utf-8',
    errors='strict',
    dropna=True
)
 
# 读取
df_load = pd.read_hdf('data.h5', key='mydata')
 
# 多数据集
df1.to_hdf('data.h5', key='df1')
df2.to_hdf('data.h5', key='df2')
 
# 查询（table 格式支持）
pd.read_hdf('data.h5', key='mydata', where="A > 2 & B == 'x'")

特性	说明
多数据集	一个文件中可存多个 key
条件查询	format='table' 支持 where 过滤
压缩	complevel + complib
依赖	需要 tables（PyTables）库
使用场景	科学计算、需局部读取的大型数据

HDFStore 高级用法

# 创建 HDFStore 对象
store = pd.HDFStore('data.h5', mode='a')
 
store['df1'] = df1          # 写入
store.append('df2', df2)    # 追加
print(store.keys())         # ['/df1', '/df2']
store.select('df1')         # 读取
store.get_storer('df1').table.read()   # 底层表
 
# where 过滤
store.select('df2', where="index > 100")
 
# 删除数据集
store.remove('df2')
 
# 关闭
store.close()

二进制格式对比

格式	大小	速度	保留 dtype	多数据集	依赖	跨语言
Pickle	中	快	完整	否	无	仅 Python
Feather	小	极快	完整	否	pyarrow	是（R）
Parquet	最小	快	完整	支持分区	pyarrow/fastparquet	广泛
HDF5	小~中	中	完整	是（key）	tables	是

选择建议

• 临时缓存 / Python 内部：Pickle
• 跨语言 / 极速读写：Feather
• 大数据分析 / 持久化存档：Parquet
• 多数据集科学计算：HDF5

相关笔记

• 23.3 格式参数与高级功能 - 压缩参数
• Pandas-四-数据输入输出 - 对应读取函数