如何按月份对Parquet文件分组以实现高效随机访问？

核心概念澄清 #

• Row Group：Parquet文件的核心存储单元，每个Row Group是一组连续的行，自带列级统计信息（比如某列的最小/最大值、非空数）。读取时可通过这些统计信息直接跳过不需要的Row Group，这就是实现"无需读取全量数据"的关键。
• chunksize：Pandas写入文件时的参数，纯粹按行数切分数据（比如chunksize=1000就是每1000行写一次），和业务逻辑（比如月份）完全无关，没法保证一个chunk对应一个月份，因此不适合用来实现你的需求。

实现步骤（PyArrow + Pandas） #

1. 准备示例数据 #

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

# 构造2023年10-12月的示例DataFrame，索引为日期时间类型
date_range = pd.date_range(start="2023-10-01", end="2023-12-31", freq="D")
df = pd.DataFrame({"value": range(len(date_range))}, index=date_range)

2. 按月份拆分并写入Parquet（每个月份对应一个Row Group） #

直接用PyArrow写入器控制Row Group生成，确保每个月份的数据单独作为一个Row Group：

# 从原DataFrame生成Parquet的schema
table_schema = pa.Table.from_pandas(df).schema

# 初始化Parquet写入器
with pq.ParquetWriter("monthly_data.parquet", schema=table_schema) as writer:
    # 按"年-月"分组（避免跨年的同月数据混在一起）
    for month_key, month_df in df.groupby(df.index.to_period("M")):
        # 将月份子DataFrame转换为PyArrow Table
        month_table = pa.Table.from_pandas(month_df)
        # 写入当前月份的Table，自动生成独立Row Group
        writer.write_table(month_table)

3. 读取指定月份的数据（无需全量加载） #

利用Row Group的元数据快速定位目标月份，只读取对应部分：

# 打开Parquet文件
parquet_file = pq.ParquetFile("monthly_data.parquet")

# 遍历Row Group元数据，筛选目标月份的Group
target_month = "2023-11"
target_row_groups = []

for i, row_group in enumerate(parquet_file.row_groups):
    # 提取索引列的统计信息，获取当前Row Group的时间范围
    index_stats = row_group.column(0).statistics
    min_date = pd.to_datetime(index_stats.min)
    max_date = pd.to_datetime(index_stats.max)
    # 判断是否匹配目标月份
    if min_date.to_period("M") == pd.Period(target_month):
        target_row_groups.append(i)

# 只读取目标Row Group的数据并转为DataFrame
selected_table = parquet_file.read_row_groups(target_row_groups)
result_df = selected_table.to_pandas()

关键说明 #

• 分组时用df.index.to_period("M")而非df.index.month，是为了区分不同年份的同月数据（比如2023-10和2024-10）。
• 每次writer.write_table()调用都会生成一个新的Row Group，刚好对应一个月份的数据，完美匹配需求。
• 读取时通过Row Group的统计信息快速定位，完全不需要加载其他月份的数据，效率极高。

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