PyArrow write_dataset为何无法保留字段元数据？

使用pyarrow.dataset.write_dataset写入Parquet时，默认配置不会将字段级自定义元数据持久化到文件中。Parquet格式对元数据的存储需要显式开启相关选项，否则字段的metadata属性会被忽略。

在写入时通过format_options参数指定Parquet写入配置，确保字段元数据被保留；读取时可通过遍历字段或直接读取文件schema来验证元数据。

修改后的写入代码 #

import pyarrow as pa
import pyarrow.dataset as ds

# 定义输出路径、schema和测试数据（原有代码不变）
parquet_output_path = "data/Parquet"
schema = pa.schema([
    pa.field('id', pa.int64(), metadata={'description': 'ID of the record'}),
    pa.field('name', pa.string(), metadata={'description': 'Name of the person'}),
    pa.field('age', pa.int32(), metadata={'description': 'Age of the person'}),
])
data = {
    'id': [1, 2, 3],
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [25, 30, 35],
}
table = pa.Table.from_pydict(data, schema=schema)
dataset = ds.dataset([table])

# 写入时添加format_options配置
ds.write_dataset(
    dataset,
    parquet_output_path,
    format="parquet",
    basename_template="sample_{i}.parquet",
    schema=schema,
    existing_data_behavior="overwrite_or_ignore",
    format_options=pa.parquet.ParquetWriteOptions(
        store_schema=True  # 存储包含字段元数据的完整schema
    )
)

验证元数据的读取代码 #

parquet_output_path = r'data\PARQUET\sample_0.parquet'

# 方式1：直接读取Parquet文件的schema
parquet_schema = pa.parquet.read_schema(parquet_output_path)
print(parquet_schema)

# 方式2：通过dataset读取后遍历字段查看元数据
parquet_dataset = ds.dataset(parquet_output_path, format="parquet")
for field in parquet_dataset.schema:
    print(f"{field.name}: {field.type}")
    print(f"  -- 字段元数据 --")
    for key, value in field.metadata.items():
        print(f"  {key}: {value.decode('utf-8')}")

关键说明 #

• store_schema=True会将完整的Arrow schema（包含字段元数据）写入Parquet文件的元数据区，确保读取时可恢复这些信息。
• 直接打印parquet_dataset.schema不会默认展示字段元数据，但元数据已实际存储，通过遍历字段的metadata属性即可访问。
• 该方案无需加载整个数据集到内存，完全符合你基于Arrow Dataset API的流式处理需求。

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