本文介绍如何使用 polars 的 `pivot` 方法，将长格式稀疏数据（id-key-value 三列结构）高效转换为宽格式列向量表示，适用于大规模稀疏特征工程场景。

在处理稀疏特征数据（如用户行为日志、推荐系统特征、基因表达矩阵等）时，原始存储常采用「三元组」形式：id（实体标识）、key（特征名/指标名）、value（对应取值）。这种长格式（long format）节省空间且易于追加，但下游建模或向量化计算通常需要宽格式（wide format）——即每个 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)

输出结果即为目标宽格式 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 模式专属 API（当前 Polars 版本中暂不支持 LazyFrame 直接调用），适合中等规模数据的即时转换；
• 若需在 lazy pipeline 中使用，且已知所有 key 值（例如通过 df.get_column("key").unique().to_list() 预先获取），可改用 group_by("id").agg(...) + struct 展开 + unnest 组合实现等效逻辑（详见 Polars Pivot 文档）；
• 默认行为对重复 (id, key) 组合会报错，若存在冲突，需显式指定 aggregate_function（如 pl.first(), pl.sum()）；
• 列类型自动推断：结果中各 key 列类型与原始 value 列一致（本例为 i64），缺失值统一填充为 null。

该方法比手动构造字典再拼接 DataFrame（如 Pandas 示例）更简洁、内存友好且执行更快，是 Polars 处理稀疏特征标准化流程的核心操作之一。