使用pyarrow写入Parquet表时如何处理空字典引发的报错

报错原因 #

Parquet 格式不支持存储无任何子字段的 struct 类型，当数据中出现空字典时，pyarrow 会自动将其推断为无子字段的 struct 类型，触发如下报错：

Cannot write struct type 'subject' with no child field to Parquet. Consider adding a dummy child field

可选解决方案 #

• 方案1：预定义固定 Schema（推荐，类型安全）
  提前明确指定所有字段的类型，包括嵌套struct的子字段，避免pyarrow自动推断出错。示例代码如下：

import pandas as pd
import pyarrow as pa
import pyarrow.parquet as pq

data =[
      {
       "name":"david",
       "subject":{}
     }
    ]
# 预定义完整Schema，明确指定subject下的所有子字段
schema = pa.schema([
    ("name", pa.string()),
    ("subject", pa.struct([
        ("math", pa.int64()),
        ("english", pa.int64())
        # 可按业务需求补充其他子字段
    ]))
])

df = pd.DataFrame.from_records(data)
# 转换Table时指定预定义Schema
table = pa.Table.from_pandas(df, schema=schema)
pq.write_table(table, 'file1.parquet')

该方案适合明确知道嵌套字段结构的场景，空字典会按照Schema自动填充对应子字段的空值。

• 方案2：为空字典添加哑字段
  按照报错提示，给所有空嵌套字典添加一个无意义的哑字段，避免出现无子字段的struct。示例代码如下：

import pandas as pd
import pyarrow as pa
import pyarrow.parquet as pq

def fill_empty_struct(data: list, struct_field: str):
    for item in data:
        # 检测指定字段是否为空字典
        if isinstance(item.get(struct_field), dict) and len(item[struct_field]) == 0:
            item[struct_field]["_dummy"] = None
    return data

data =[
      {
       "name":"david",
       "subject":{}
     }
    ]
# 处理空嵌套字段
data = fill_empty_struct(data, "subject")

df = pd.DataFrame.from_records(data)
table = pa.Table.from_pandas(df)
pq.write_table(table, 'file1.parquet')

该方案适合不确定嵌套字段结构的兼容场景，哑字段不会影响正常业务字段的读取。

• 方案3：将空字典替换为None
  如果业务上空嵌套字典等价于无值，可以直接将空字典替换为None，pyarrow会自动将该字段识别为可空struct类型，不会触发报错。示例代码如下：

import pandas as pd
import pyarrow as pa
import pyarrow.parquet as pq

def empty_dict_to_none(data: list, struct_field: str):
    for item in data:
        if isinstance(item.get(struct_field), dict) and len(item[struct_field]) == 0:
            item[struct_field] = None
    return data

data =[
      {
       "name":"david",
       "subject":{}
     }
    ]
# 空字典转None
data = empty_dict_to_none(data, "subject")

df = pd.DataFrame.from_records(data)
table = pa.Table.from_pandas(df)
pq.write_table(table, 'file1.parquet')

该方案适合空嵌套字段无业务含义的场景，处理逻辑最简洁。

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