
本文介绍如何在 Polars LazyFrame 中实现类似 Pandas groupby().apply(...to_parquet...) 的功能,利用 sink_parquet 与 PartitionByKey 按分组字段自动拆分并保存为独立 Parquet 文件,并支持自定义文件路径与命名逻辑。
本文介绍如何在 polars lazyframe 中实现类似 pandas `groupby().apply(...to_parquet...)` 的功能,利用 `sink_parquet` 与 `partitionbykey` 按分组字段自动拆分并保存为独立 parquet 文件,并支持自定义文件路径与命名逻辑。
在 Polars 中,直接对 LazyFrame 进行“循环分组 + 逐块写入”(如 Pandas 风格)并不推荐——LazyFrame 的核心优势在于延迟执行与查询优化,而显式 Python 循环会破坏其性能潜力,且无法利用底层 Rust 引擎的并行 I/O 能力。正确的做法是使用 Polars 原生支持的分区写入(partitioned sink)机制。
✅ 推荐方案:sink_parquet + PartitionByKey
PartitionByKey 是 Polars 提供的专用分区写入策略,专为按列值自动组织输出目录结构而设计。它能将 LazyFrame 按指定列(如 'a')的唯一值自动分片,并将每组数据写入对应子目录下的 Parquet 文件中:
import numpy as np
import polars as pl
# 构造示例数据
df = pl.DataFrame({
'a': np.random.randint(0, 5, 1000),
'b': np.random.random(1000)
})
lf = df.lazy() # 或 pl.LazyFrame(df)
# 按列 'a' 分区写入,自动创建 /tmp/output/a=0/, /tmp/output/a=1/ 等子目录
lf.sink_parquet(
pl.PartitionByKey("/tmp/output", by="a"),
mkdir=True # 自动创建父目录(推荐始终启用)
)执行后,文件系统将生成如下结构:
/tmp/output/
├── a=0/
│ └── 0.parquet
├── a=1/
│ └── 0.parquet
├── a=2/
│ └── 0.parquet
├── a=3/
│ └── 0.parquet
└── a=4/
└── 0.parquet⚠️ 注意:每个分区目录下默认生成
0.parquet(或0.snappy.parquet等),这是 Polars 内部调度的分片编号;若需更精确控制文件名(例如a_0.parquet),请继续阅读进阶用法。
? 进阶控制:自定义文件路径与命名
PartitionByKey 支持通过 file_path 参数传入回调函数,动态生成每个分区的完整文件路径。该函数接收一个 dict[str, str] 类型的 partition key 映射(如 {"a": "3"}),返回目标 .parquet 文件路径(相对或绝对):
def custom_filename(partition: dict[str, str]) -> str:
key_val = partition["a"]
return f"/tmp/custom/a_{key_val}.parquet"
lf.sink_parquet(
pl.PartitionByKey("/tmp/custom", by="a", file_path=custom_filename),
mkdir=True
)运行后将直接生成:
/tmp/custom/a_0.parquet /tmp/custom/a_1.parquet /tmp/custom/a_2.parquet /tmp/custom/a_3.parquet /tmp/custom/a_4.parquet
✅ 优势:无需 Python 层循环、零内存中间 DataFrame、全链路惰性执行、支持并行写入与压缩选项(如 compression="zstd")。
❗重要注意事项
-
sink_parquet是终端操作(eager sink),调用后立即触发整个 LazyFrame 的物化与写入,不可再链式调用其他 lazy 方法; -
PartitionByKey仅支持单列by=(多列分区暂不支持,但可先with_columns(pl.col("x").cast(str) + "_" + pl.col("y").cast(str))合并为新键); - 输出路径必须为本地文件系统路径(不支持 S3/HDFS 等远程存储的原生分区写入,需配合
object_store手动实现); - 若需保留原始分组顺序或添加元数据(如行数、时间戳),建议在写入前通过
with_columns()添加辅助列,再在file_path回调中读取。
✅ 总结
Polars 并不鼓励“模拟 Pandas 循环分组”的惯性思维。sink_parquet + PartitionByKey 是更高效、更符合其设计哲学的替代方案:它将分组逻辑下沉至执行引擎,避免 Python-GIL 瓶颈,同时提供灵活的路径定制能力。对于 TB 级数据的分组导出任务,这是兼具性能、可维护性与可扩展性的首选实践。

















