本文介绍如何利用 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 中实现稀疏长→宽转换最简洁、最高效的标准解法，兼顾表达力与执行性能，是特征工程流水线中不可或缺的关键操作。