Pandas使用to_hdf存储含numpy数组的DataFrame报TypeError: int类型无len()

报错触发逻辑 #

• 当调用to_hdf开启format='table'与data_columns=True参数时，pandas的PyTables适配层会逐列拆解数据为可独立索引的扁平原子结构，以支持后续的列裁剪、条件过滤查询。
• 示例中c列是逐行存储高维NumPy数组的嵌套结构，无法被拆解为扁平列，底层代码在计算块维度时传入了整数类型的维度值，最终触发TypeError: object of type 'int' has no len()异常。

HDF格式下的对应解决路径 #

• 纯备份场景：直接改用fixed格式存储
  调整写入参数为df.to_hdf("test.h5", "df", format='fixed')即可跳过列拆解逻辑。局限性：该模式不支持后续读取时只加载指定列，必须将整个数据集读入内存，不符合按需取列的核心需求。
• 兼顾列裁剪需求的方案：拆分嵌套列与普通列分key存储
  核心逻辑是将可扁平索引的普通列、无法拆解的嵌套数组列拆分为独立的存储块，写入同一个HDF文件的不同键值下：
  1. 将普通标量列（示例中的a、b列）以table模式存储，开启列索引支持
  2. 将含NumPy数组的嵌套列以fixed模式存储到同一文件的独立键下
  3. 后续读取时按需加载普通列的指定子集，需要用到数组列时再单独加载对应键的内容，按行索引对齐合并即可
     对应实现代码：

  # 拆分写入
  df[["a", "b"]].to_hdf("test.h5", "flat_cols", format="table", data_columns=True)
  df[["c"]].to_hdf("test.h5", "nested_arr_cols", format="fixed")
  
  # 按需读取示例：仅加载a列
  a_col = pd.read_hdf("test.h5", key="flat_cols", columns=["a"])
  # 需要数组列时再单独加载
  c_col = pd.read_hdf("test.h5", key="nested_arr_cols")
  merged = a_col.join(c_col)
  

• 兼容写入方案：对嵌套列显式指定序列化大小
  写入table模式时，针对嵌套数组列显式指定其为object类型的可序列化原子，通过min_itemsize参数跳过默认的维度检测逻辑，例如df.to_hdf("test.h5", "df", format='table', min_itemsize={'c': 100000})（数值根据单个数组序列化后的实际字节数调整）。注意：该方式仅能完成写入，嵌套列无法参与后续的条件过滤查询，也不支持作为独立列被单独裁剪加载。

支持列级裁剪的适配存储格式 #

• Parquet格式
  对嵌套数据结构的序列化兼容性远高于pandas的HDF适配层，原生支持列级裁剪读取，读取时可通过columns参数指定仅加载需要的列，高维NumPy数组会自动按二进制结构序列化存储，不需要手动拆分列。
  基础实现：

  df.to_parquet("test.parquet", engine="pyarrow")
  # 按需仅加载a、b列
  sub_df = pd.read_parquet("test.parquet", columns=["a", "b"])
  

• Feather格式
  基于Arrow标准实现，支持内存映射读取，读取速度显著优于HDF格式，同样原生支持列级裁剪，对嵌套数组的兼容性好，适合单机场景下的中间数据存储，唯一需要注意的是跨环境读取时需保持对应Arrow库的版本一致，避免兼容问题。
• 直接基于h5py操作HDF5文件
  如果必须使用HDF5格式，可以跳过pandas自带的PyTables适配层，直接通过h5py库手动管理数据集：将普通列存为二维数据集，高维NumPy数组按行序整理为三维结构化数组存为独立数据集，后续读取时直接按列索引取对应数据集即可，完全不受pandas层的维度检测逻辑限制。

内容的提问来源于stack exchange，提问作者r0f1