Polars 自定义函数返回多列的正确实现方法

在 Polars 中，自定义函数需直接返回多个 Expr 对象（而非 struct），再通过生成器表达式或字典解包方式为每列指定别名，才能在 with_columns() 中一次性添加多个新列。

在 Polars 中，自定义函数需直接返回多个 `Expr` 对象（而非 `struct`），再通过生成器表达式或字典解包方式为每列指定别名，才能在 `with_columns()` 中一次性添加多个新列。

Polars 的 with_columns() 方法原生支持同时添加多个列，但关键前提在于：传入的表达式必须是独立、已命名（或可命名）的 Expr 对象。若将多个计算结果封装进 pl.struct()，虽逻辑上“打包”成功，但 Polars 不会自动展开结构体字段为独立列——这与 Pandas 的 apply(..., result_type='expand') 行为不同，也不同于 DuckDB 或 SQL 中的 SELECT struct.* 语法。

因此，正确的做法是让自定义函数直接返回一个 tuple（或 list）形式的多个 Expr，例如：

import polars as pl
import numpy as np

def _func(x: pl.Expr) -> tuple[pl.Expr, pl.Expr]:
    x1 = x + 1
    x2 = x + 2
    return x1, x2

df = pl.DataFrame({"test": np.arange(1, 11)})

随后，在 with_columns() 中灵活绑定列名。以下是三种推荐方案：

✅ 方案一：序号自动命名（推荐用于通用/批量场景）

适用于列数固定但名称模式统一（如 "col1", "col2"）的情况：

df.with_columns(
    expr.alias(f"test{i+1}") 
    for i, expr in enumerate(_func(pl.col("test")))
)

✅ 方案二：显式命名列表（清晰可控）

适合预定义列名，语义明确：

names = ["test1", "test2"]
df.with_columns(
    expr.alias(name) 
    for expr, name in zip(_func(pl.col("test")), names)
)

✅ 方案三：字典解包（最简洁，支持任意键名）

利用 with_columns(**dict) 接口，代码紧凑且可读性强：

df.with_columns(
    **dict(zip(["test1", "test2"], _func(pl.col("test"))))
)

⚠️ 注意事项：

• ❌ 避免使用 pl.struct([...]).alias([...]) —— alias() 对 struct 仅设置整个结构体字段名，不会展开；
• ✅ 函数返回值必须是 Expr 实例（非标量、非 Series、非 DataFrame）；
• ✅ 若函数需处理更复杂逻辑（如条件分支、聚合），仍应确保每个分支均返回同构的 Expr 元组；
• ? 所有方案均天然支持扩展至 N 列（如返回 x1, x2, x3, x4），无需修改调用逻辑。

最终输出将严格匹配预期结构：

shape: (10, 3)
┌──────┬───────┬───────┐
│ test ┆ test1 ┆ test2 │
│ ---  ┆ ---   ┆ ---   │
│ i32  ┆ i32   ┆ i32   │
╞══════╪═══════╪═══════╡
│ 1    ┆ 2     ┆ 3     │
│ 2    ┆ 3     ┆ 4     │
└──────┴───────┴───────┘

掌握这一模式后，即可高效构建可复用、可扩展的 Polars 自定义列生成逻辑。