本文介绍如何使用 polars 的 pivot 方法，将长格式（key-value）稀疏数据高效转换为宽格式（列式）表示，适用于大规模稀疏特征场景。
在处理稀疏数据（如用户行为日志、特征向量、配置映射等）时，常以“ID-键-值”三元组形式存储（即长格式），以节省空间并提升写入/追加效率。但在后续分析或模型训练阶段，往往需要将其展开为列式结构（即宽格式），其中每个唯一 key 成为一列，每个 ID 对应一行，缺失值自动填充为 null。
Polars 提供了原生、高性能的 pivot 操作，专为此类行转列（reshape）任务设计。其核心语法简洁直观：
import polars as pl
df = pl.from_repr("""
┌─────┬─────┬───────┐
│ id ┆ key ┆ value │
│ --- ┆ --- ┆ --- │
│ str ┆ str ┆ i64 │
╞═════╪═════╪═══════╡
│ a ┆ m1 ┆ 1 │
│ a ┆ m2 ┆ 2 │
│ a ┆ m3 ┆ 1 │
│ b ┆ m2 ┆ 4 │
│ c ┆ m1 ┆ 2 │
│ c ┆ m3 ┆ 6 │
│ d ┆ m4 ┆ 4 │
│ e ┆ m2 ┆ 1 │
└─────┴─────┴───────┘
""")
# 执行 pivot：以 'key' 列值为新列名，'id' 为索引，'value' 为填充值
result = df.pivot(
on="key", # 要展开为列的字段（即 key 列）
index="id", # 作为行索引的字段（即分组依据）
values="value" # 用于填充新列的值字段（默认为 value 列）
)
print(result)输出结果即为目标宽格式 DataFrame：
shape: (5, 5) ┌─────┬──────┬──────┬──────┬──────┐ │ id ┆ m1 ┆ m2 ┆ m3 ┆ m4 │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ str ┆ i64 ┆ i64 ┆ i64 ┆ i64 │ ╞═════╪══════╪══════╪══════╪══════╡ │ a ┆ 1 ┆ 2 ┆ 1 ┆ null │ │ b ┆ null ┆ 4 ┆ null ┆ null │ │ c ┆ 2 ┆ null ┆ 6 ┆ null │ │ d ┆ null ┆ null ┆ null ┆ 4 │ │ e ┆ null ┆ 1 ┆ null ┆ null │ └─────┴──────┴──────┴──────┴──────┘
✅ 关键说明与注意事项：
- pivot() 仅在 eager 模式下可用（即直接对 DataFrame 调用）；若在 lazy pipeline 中需 pivot，可先用 .collect() 触发计算，或采用替代方案（如 group_by().agg() + struct 展开，详见 Polars Pivot 文档）。
- 若 key 列存在重复组合（如同一 id + key 多次出现），需指定 aggregate_function（如 pl.first(), pl.sum()）来聚合冲突值，否则会报错。
- 新列名自动取自 on 列的唯一值；若需重命名或控制列顺序，可在 pivot 后使用 .select() 或 .rename()。
- 对于超大规模稀疏数据，pivot 后的内存占用可能显著增加（因引入大量 null），建议结合 pl.datatypes.Null 或后续 fill_null()/drop_nulls() 按需优化。
该方法相比手动构造字典再拼接（如 Pandas 示例），不仅代码更简洁，且底层由 Rust 高效实现，兼具可读性与性能优势，是 Polars 稀疏数据工程中的标准实践。
