如何正确使用polars.LazyFrame.pivot实现多列透视？

核心问题原因 #

你遇到的错误是因为on_columns参数的传递格式不符合LazyFrame多列pivot的要求——该参数仅接受一维字符串列表，集合、嵌套列表、Series都会触发类型或逻辑错误。

正确用法示例 #

先构造测试数据，再演示正确的LazyFrame多列pivot调用：

import polars as pl

# 测试数据集
df = pl.DataFrame({
    "id": [1,1,2,2],
    "subject": ["math","english","math","english"],
    "exam": ["midterm","midterm","final","final"],
    "grade": [85,90,92,88]
})
lf = df.lazy()

# 正确的多列pivot调用
pivoted_lf = lf.pivot(
    on_columns=["id", "subject"],  # 必须是一维字符串列表
    pivot_column="exam",
    values_column="grade"
).collect()

print(pivoted_lf)

执行后输出：

shape: (4, 4)
┌────┬─────────┬─────────┬───────┐
│ id ┆ subject ┆ midterm ┆ final │
│ ---┆ ---     ┆ ---     ┆ ---   │
│ i64┆ str     ┆ i64     ┆ i64   │
├────┼─────────┼─────────┼───────┤
│ 1  ┆ math    ┆ 85      ┆ null  │
│ 1  ┆ english ┆ 90      ┆ null  │
│ 2  ┆ math    ┆ null    ┆ 92    │
│ 2  ┆ english ┆ null    ┆ 88    │
└────┴─────────┴─────────┴───────┘

错误参数的问题说明 #

• 集合（如{"id", "subject"}）：Polars不接受无序集合作为列分组参数，必须用有序列表保证结果的列顺序一致性。
• 嵌套列表（如[["id"], ["subject"]]）：on_columns需要的是一维列名序列，嵌套列表会被识别为无效的列名格式。
• Series对象：参数要求的是列名字符串的序列，直接传递Series会触发类型不匹配的错误，若要使用Series中的列名，需先转成列表（如series.to_list()）。

额外注意事项 #

Polars 1.36.0的多列pivot是新增功能，需确保参数名称为on_columns（而非旧版pivot的index参数），避免因参数名误用导致的错误。

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