Classify rows
Create a categorical label from numeric or boolean thresholds.
Polars · Function
pl.when
Starts a conditional expression built from chained when/then branches and an optional otherwise fallback. The first true condition determines the selected value.
How it works
pl.when starts a conditional expression. Attach .then for the value selected when its condition matches, optionally chain additional condition/value pairs, and finish with .otherwise; conditions are evaluated in order and the first true branch supplies the result.
Syntax
polars.when(predicates: IntoExprColumn | Iterable[IntoExprColumn] | bool, **constraints: Any) -> WhenParameters
| Name | Type | Description |
|---|---|---|
predicates | IntoExprColumn | Iterable[IntoExprColumn] | bool | Condition(s) that must be met to apply the subsequent statement; one or more boolean expressions are implicitly combined with &. |
constraints | Any | Keyword equality conditions such as x=123; multiple constraints are implicitly combined with &. |
Returns
When
Key points
- Use
pl.whento begin a conditional Polars expression. - A
.thenbranch is required first, and further branches can be chained. - Add
.otherwiseto define the fallback for rows matching no condition. - Branch precedence is first-match-wins, rather than combining all matching branches.
- The positional predicates can contain one or more boolean expressions joined implicitly with AND.
- Keyword constraints provide convenient column-equality tests.
- Unless renamed later, the resulting expression inherits its output name from the first
thenvalue.
Common mistakes
- Every branch expression must be independently valid because Polars evaluates all branches before filtering by conditions.
- Bare strings are interpreted as column references, so use
pl.litwhen a branch should produce a string literal.
Example: Classify values with chained conditions
import polars as pl
df = pl.DataFrame({"score": [3, 8, 12]})
result = df.with_columns(
pl.when(pl.col("score") >= 10)
.then(pl.lit("high"))
.when(pl.col("score") >= 5)
.then(pl.lit("medium"))
.otherwise(pl.lit("low"))
.alias("band")
)
print(result)Classifies each score using the first matching condition.
When to use it
Provide defaults
Assign a fallback when no rule matches.
Match constraints
Express column-equality filters directly with keyword arguments.
Implement priority rules
Build ordered rule systems with multiple predicates.
Interview questions
QHow does pl.when select among multiple branches?
pl.when begins a conditional expression that is completed with .then, optional chained .when(...).then(...) branches, and optionally .otherwise. The result uses the first condition that evaluates to true.
Follow-up: What happens when every condition is false? The explicitly supplied .otherwise value is returned; without one, the default is None.
QHow are multiple conditions passed to pl.when combined?
Multiple predicates supplied to pl.when are implicitly combined with logical AND. Keyword constraints such as status="open" express equality conditions and are also combined with AND.
Follow-up: How would you require OR semantics? Build an explicit boolean expression with | inside a predicate rather than passing separate arguments.
QWhat evaluation behavior can make conditional branches fail unexpectedly?
Polars evaluates every expression in a when-then-otherwise chain in parallel and filters the results afterward. Therefore, a branch cannot rely on its condition to make an otherwise-invalid expression safe.
Follow-up: How can a literal string be returned reliably? Wrap it with pl.lit, because string inputs to then and otherwise are parsed as column names.
Related
polars.Expr.whenpolars.Expr.thenpolars.Expr.otherwisepolars.litpolars.coalesce