Transform nested values
A list column contains values that need an expression-based transformation.
Polars · Function
pl.element
Returns an expression representing the item currently processed by an eval or filter expression. Use it to transform, rank, or filter elements within Polars list expressions.
How it works
pl.element() returns an expression representing the current item while Polars evaluates an expression inside a list eval or filter operation. Combine it with normal expression methods or operators to transform, rank, or select those items.
Syntax
polars.element() → ExprReturns
Expr
Key points
- It is the current-item placeholder for evaluation and filtering expressions.
- Combine it with
.rank()to calculate a rank for each item in every list. - Arithmetic operators can transform every list item without writing a Python loop.
- Use it as the predicate input when filtering list elements.
Common mistakes
- Use it only as the placeholder for the item currently being processed by an evaluation or filter expression; it is not a standalone scalar value.
Example: Transform list elements
import polars as pl
df = pl.DataFrame({"a": [1, 8, 3], "b": [4, 5, 2]})
result = df.with_columns(
pl.concat_list("a", "b")
.list.eval(pl.element() * 2)
.alias("doubled")
)
print(result)Builds a list from two columns and evaluates an expression against each list element.
When to use it
Rank list members
Each row stores a list and its members must be ranked relative to one another.
Filter list members
Lists should retain only members matching a condition.
Interview questions
QWhat does pl.element() represent?
pl.element() creates an expression for the current item in an eval or filter expression. It lets the surrounding list operation apply another expression to each item.
Follow-up: How would you double every item in list values? Use .list.eval(pl.element() * 2).
QHow is pl.element() used with list expressions?
Use it inside .list.eval(...) when transforming each list item. For example, .list.eval(pl.element().rank()) computes ranks within each list.
Follow-up: What operation can apply a predicate instead? Use .list.filter(pl.element() % 2 == 0) to retain matching items.
QWhat are the signature and return type?
The function has no arguments and returns an Expr. The returned expression is then composed with operators or expression methods inside the surrounding evaluation context.
Follow-up: Why is the return type useful? Because it can participate in Polars' expression tree rather than forcing Python-level iteration.
Related
polars.Expr.list.evalpolars.Expr.list.filterpolars.Expr.arr.eval