PyArrow write_dataset 怎么限制每个 Parquet 文件的行数

用 PyArrow 写 Parquet 数据集时，限制单个文件行数的参数就是 max_rows_per_file。只要把它设置为大于 0 的整数，write_dataset 就会把每个输出文件控制在这个行数以内；最后一个文件可以不足这个数。官方文档入口：https://arrow.apache.org/docs/python/generated/pyarrow.dataset.write_dataset.html

但它控制的是“文件里最多有多少行”，不是文件字节数，也不等于 Parquet 的 row group 大小。实际配置通常要同时看 max_rows_per_group、分区数量和 max_open_files。

最小写法：用 max_rows_per_file 限制单文件行数

下面的示例把数据按 dt 分区，并尝试让每个 Parquet 文件最多保存 500000 行：

import pyarrow as pa
import pyarrow.dataset as ds

# 示例数据；真实项目中也可以传入 RecordBatchReader
table = pa.table({
    "dt": ["2026-11-01", "2026-11-01", "2026-11-02"],
    "user_id": [101, 102, 103],
    "amount": [12.5, 8.0, 19.9],
})

# max_rows_per_file 控制单个输出文件的行数上限
ds.write_dataset(
    table,
    base_dir="parquet_out",
    format="parquet",
    partitioning=["dt"],
    max_rows_per_file=500_000,
    existing_data_behavior="delete_matching",
)

这里的关键是“上限”而不是“固定值”：如果某个分区只有 120000 行，它不会为了凑 500000 行再生成空文件；如果分区有 1200000 行，才可能拆成多个文件。分区字段不同，也会分别在各自目录中产生输出文件。

max_rows_per_file 和 max_rows_per_group 不是一回事

可以把 Parquet 想成“文件里包含多个 row group”。max_rows_per_file 决定一个文件最多装多少行，max_rows_per_group 决定单个 row group 的最大行数。前者影响文件切分，后者影响文件内部的组织粒度。

# 文件上限与行组上限分开设置
ds.write_dataset(
    table,
    base_dir="parquet_out",
    format="parquet",
    partitioning=["dt"],
    max_rows_per_file=500_000,   # 一个文件最多 50 万行
    min_rows_per_group=128_000,  # 累积到这个数量后再写一个行组
    max_rows_per_group=128_000,  # 单个行组不超过这个数量
)

官方文档给出的默认值是：max_rows_per_file=0 表示不按行数限制，max_rows_per_group=1024 * 1024；当显式设置 max_rows_per_group 时，通常也应设置 min_rows_per_group，否则输入批次可能被切成很小的行组。

如果你的目标只是避免单个文件过大，先设置 max_rows_per_file 即可；如果还要控制扫描粒度，再根据读取任务设置行组参数。不要把 row group 的行数直接当成文件大小，列类型、压缩编码和数据内容都会影响实际字节数。

分区、文件句柄和碎片化要一起看

分区输出会把数据分到不同目录，文件上限是在各个输出路径中分别生效的。此时还要留意 max_open_files：它限制同时保持打开状态的文件数量，达到上限后会关闭最近最少使用的文件。官方文档提醒，这个值过低可能造成很多小文件。

written = []

def collect_file(written_file):
    # file_visitor 可收集本次写出的文件路径和 Parquet 元数据
    written.append(written_file.path)

ds.write_dataset(
    table,
    base_dir="parquet_out",
    format="parquet",
    partitioning=["dt"],
    max_rows_per_file=500_000,
    max_open_files=128,           # 过低时可能增加文件碎片
    file_visitor=collect_file,    # 只记录写入器回调提供的文件对象
)

max_open_files 不是单文件行数参数。它解决的是资源管理问题，和 max_rows_per_file 同时设置时，文件切分可能同时受到行数上限、分区数量和文件打开策略影响。若发现文件数量异常增多，先检查分区基数和这个参数是否设得过小。

一张表选参数

因此，最常用的起点是：先用 max_rows_per_file 控制单文件行数，再按查询和扫描特征调整 row group；分区很多时，不要把 max_open_files 设得远低于实际并发写入的文件需求。

常见问题

设置了 max_rows_per_file，为什么文件行数还是不完全相等？

它是最大值，不是定长切片器。每个分区的总行数、输入批次边界和最后剩余数据都会让文件实际行数不同。

想限制 Parquet 文件大小，应该把 max_rows_per_file 换成多少？

不能直接按一个固定换算式得到。行宽和压缩比会改变字节数，通常先按业务读取粒度设行数上限，再结合实际文件元数据和存储成本做调整。