本文介绍如何利用 polars 的 `pivot()` 方法高效地将键值对形式的稀疏长格式数据（id-key-value）转换为以 key 为列名、id 为行索引的宽格式 dataframe，适用于大规模稀疏特征工程场景。
在处理稀疏结构化数据（如用户行为特征、基因表达谱、推荐系统 item-tag 关系等）时，原始数据常以三元组形式存储：id（实体标识）、key（特征维度/字段名）、value（对应取值）。这种“长格式”节省空间且易于追加更新；但在建模或向量化计算阶段，往往需要将其展开为“宽格式”——即每个 key 成为一列，每行代表一个 id 的完整特征向量。
Polars 提供了原生、高性能的 pivot 操作来完成这一转换。核心只需一行代码：
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", index="id", values="value")
print(result)输出结果即为目标宽格式（5 行 × 5 列），自动对齐所有唯一 key（m1, m2, m3, m4），缺失位置填充 null（Polars 中的 None 等价表示）：
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 模式（即直接作用于 pl.DataFrame），不适用于 LazyFrame 流水线。若需在 lazy 模式下实现类似效果，可先用 unique("key") 获取所有列名，再结合 group_by("id").agg() 与 struct + unnest 手动构造，但性能与可读性略低；官方文档提供了该替代方案的完整示例。
- 若存在重复的 (id, key) 组合，pivot() 默认会报错。此时需预先聚合（如 df.group_by(["id", "key"]).agg(pl.col("value").first())）以明确冲突策略（取首值、求和、均值等）。
- 列类型由 values 列推断，若原始 value 类型混杂（如部分为 i64、部分为 f64），建议提前统一类型（如 df.with_columns(pl.col("value").cast(pl.Float64))），避免 pivot 后列类型不一致。
综上，df.pivot(on="key", index="id", values="value") 是 Polars 中实现稀疏长→宽转换最简洁、最高效的标准解法，兼顾表达力与执行性能，是特征工程流水线中不可或缺的关键操作。
