Python Polars表达式与普通Python函数有什么区别

如果把普通 Python 函数直接套到 Polars 的列上，最容易混淆的是“函数已经算出了一个值”和“表达式只描述了一个列变换”。一句话先记住：普通函数处理已经存在的 Python 值；Polars 表达式通常先构造一个可组合的计算描述，放进 select、with_columns、filter 或 group_by 等上下文后，才由 Polars 解释成列结果。

官方地址：https://docs.pola.rs/

这也是两者性能和写法差异的来源：能用列运算、聚合和条件表达式写出的逻辑，优先保留为原生表达式；只有原生 API 无法表达时，才考虑把纯 Python 函数放进 map_elements，并明确返回类型。

为什么说 Polars 表达式不是普通 Python 函数

普通函数调用是立即求值的。下面的 normalize 接收一个 Python 数字，返回另一个 Python 数字；它并不知道 DataFrame 有多少行，也不负责决定结果应该放进哪一列。

def normalize(value: float) -> float:
    # 普通函数只关心一个已经取出的 Python 值
    return value / 100.0

one_value = normalize(85.0)  # 这里已经得到 0.85

而 pl.col("score") / 100 先得到的是 Expr。它可以保存、继续拼接、改名或与其他表达式组合，但创建它本身不会遍历 DataFrame。真正的结果形状要由使用它的上下文决定。

同一个表达式，为什么放进不同上下文会得到不同结果

Polars 官方文档把上下文看成表达式的解释位置。select 主要产生选中的新列，with_columns 保留原列并增加或替换列，filter 使用布尔表达式筛行，group_by 则把表达式放到分组与聚合语义中。

import polars as pl

df = pl.DataFrame({"score": [65, 85, 92]})
score_expr = pl.col("score") / 100

# select只保留表达式产生的列
selected = df.select(score=score_expr)

# with_columns保留score，并增加normalized_score
enriched = df.with_columns(normalized_score=score_expr)

# filter把表达式解释为每行的布尔条件
passed = df.filter(pl.col("score") >= 80)

这里的 score_expr 没有被改写成普通列表，也没有提前产生三份结果。上下文决定了它是输出列、附加列还是筛选条件。这个差异也是表达式可以组合、复用并交给惰性查询规划的关键。

原生表达式和普通 Python 函数怎么选

先尝试把逻辑翻译成列运算。比如“每个值乘以 2”不需要自定义函数：

# 原生表达式直接描述整列运算
result = df.with_columns(
    doubled=(pl.col("score") * 2).alias("doubled")
)

如果逻辑确实无法由原生表达式表达，可以使用 map_elements。它接收的是 Python 函数，并把函数映射到列元素；这不是把普通函数自动变成了原生表达式，而是显式进入了 Python UDF 边界。

def label_score(value: int) -> str:
    # 自定义函数保持纯净，只根据传入值返回标签
    return "高分" if value >= 80 else "普通"

result = df.with_columns(
    label=pl.col("score").map_elements(
        label_score,
        return_dtype=pl.String,  # 明确UDF输出类型，避免类型推断歧义
    )
)

官方对 map_elements 的提醒很明确：它相当于逐元素调用 Python 函数，通常比原生表达式慢；函数还应当是纯函数，不能依赖或修改参数之外的外部状态。return_dtype 能让输出契约更清楚，尤其适合结果类型不容易从样本推断的函数。

兼容注意与采用建议

可以按下面的顺序做选择：

1. 如果逻辑是算术、比较、字符串、日期、聚合或条件组合，优先写成 pl.col(...) 等原生表达式。
2. 如果需要把表达式放到输出中，先确认使用的是 select 还是 with_columns，两者保留原列的行为不同。
3. 只有原生 API 不足以表达的单值逻辑，才使用 map_elements；给出 return_dtype，并让函数只依赖输入。
4. 不要把“普通函数能接收一个值”误认为“它天然理解一列数据”。若函数需要整组数据，应先明确分组或窗口上下文，再设计对应表达式。

因此，Python 函数与 Polars 表达式并不是互斥的两种语法：前者是具体值上的业务函数，后者是面向列和上下文的计算描述。把这条边界分清，通常就能同时获得更清晰的代码和更合适的执行路径。

相关问题

Polars 表达式创建后会立刻计算吗？

通常不会。表达式先描述数据变换，放入具体上下文后才产生对应结果。

什么时候不应该使用 map_elements？

当逻辑可以用原生列运算、聚合或条件表达式表达时，不应优先使用它；它会引入 Python 逐元素函数调用。