Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Polars when-then-otherwise: Conditional Expressions in Python

Learn how to use Polars when-then-otherwise expressions to create conditional columns, chain multiple conditions, and handle type and null edge cases.

~5 min readPython
#Polars#Conditional Logic#DataFrames#Python
Illustration of a Polars DataFrame with conditional branches flowing into a result column, representing when-then-otherwise logic.

When you need to apply conditional logic to a Polars DataFrame, when-then-otherwise is the primary tool. It behaves like a vectorized if-elif-else that operates on entire columns, avoiding Python-level loops. This article covers the syntax, common patterns, and practical considerations for using conditional expressions in Polars.

Basic Syntax of when-then-otherwise

The core structure is pl.when(condition).then(value).otherwise(value). The condition is a boolean expression evaluated element-wise, and the then and otherwise branches can be literals, column references, or other expressions.

python
import polars as pl df = pl.DataFrame({ "score": [45, 78, 92, 61, 30], }) df.with_columns( pl.when(pl.col("score") >= 60) .then("pass") .otherwise("fail") .alias("result") )

This adds a result column where each row gets "pass" if the score is at least 60, otherwise "fail". The expression is evaluated column-wise, so Polars processes data in chunks and avoids Python-level row iteration.

Chaining Multiple Conditions with then

For more than two outcomes, chain additional .when() calls after a .then(). This mirrors an elif chain. The first matching condition determines the result; in the final output, later branches only affect rows that did not match earlier conditions. Internally, Polars still applies the branches as columnar expressions, so this is not a row-by-row Python short-circuit.

python
df.with_columns( pl.when(pl.col("score") >= 90) .then("A") .when(pl.col("score") >= 75) .then("B") .when(pl.col("score") >= 60) .then("C") .otherwise("F") .alias("grade") )

Order matters. If you reverse the thresholds, the logic breaks because the first condition catches rows that should fall into a later bucket. This is a common source of bugs, especially when thresholds overlap.

Using Conditions Across Multiple Columns

Conditions can reference any number of columns. For example, you might classify rows based on both a numeric threshold and a categorical flag.

python
df = pl.DataFrame({ "user": ["alice", "bob", "carol"], "age": [25, 17, 32], "is_student": [True, True, False], }) df.with_columns( pl.when((pl.col("age") < 18) | (pl.col("is_student"))) .then("discount") .otherwise("standard") .alias("ticket_type") )

Combine conditions with & (and), | (or), and ~ (not). Parentheses are required around each comparison because Python evaluates bitwise operators like | before comparison operators; wrap each condition in parentheses to avoid ambiguity.

Using when-then-otherwise Inside Other Expressions

A when-then-otherwise expression can be nested inside other Polars expressions, such as aggregation functions. For example, you can use it inside pl.sum to perform conditional aggregation.

python
df = pl.DataFrame({ "category": ["A", "B", "A", "B"], "value": [10, 20, 30, 40], }) df.group_by("category").agg( pl.sum(pl.when(pl.col("value") > 15).then(pl.col("value")).otherwise(0)).alias("sum_over_15") )

Here, pl.sum receives an expression that returns the original value only when it exceeds 15, otherwise zero. This avoids filtering rows and then aggregating separately and keeps the logic in one expression.

Performance Considerations

Because when-then-otherwise is a vectorized expression, it avoids Python-level row iteration. In a LazyFrame, it is part of the query plan and can be optimized before execution. For large DataFrames, this is generally faster than using apply or a list comprehension.

One nuance: chained .when() calls are not implemented as a row-level short-circuit. The logic is applied through columnar masks, so do not expect Python-style behavior where later conditions are skipped for rows that already matched. This is still efficient for typical workloads, but if you have many conditions, the intermediate masks can add memory overhead. Keep the number of conditions reasonable.

Common Pitfalls and How to Avoid Them

Missing otherwise

If you omit .otherwise(), rows that do not match any condition become null. This is sometimes intentional, but often a bug. Always verify whether nulls are acceptable in the output column.

python
# This yields null for scores below 60 df.with_columns( pl.when(pl.col("score") >= 60).then("pass").alias("result") )

Mixing Data Types

The then and otherwise branches must produce the same data type, or Polars will attempt to cast. If you use an integer in one branch and a string in another, you may get an error or an unexpected cast. For example, .then(1).otherwise("no") will fail because Polars cannot unify Int64 and String automatically. Use .cast(pl.Utf8) or choose consistent types.

Using Python if Instead of when

A common mistake is trying to use a Python if statement inside a select or with_columns. That does not work because if is evaluated once at the expression-building stage, not per row. Always use pl.when for row-wise conditional logic.

Advanced Pattern: Conditional Column with Multiple Branches and Null Handling

Sometimes you need to handle nulls explicitly. You can use pl.when(pl.col("value").is_null()) as a condition to assign a default, then chain other conditions.

python
df = pl.DataFrame({ "value": [None, 5, 12, None, 20], }) df.with_columns( pl.when(pl.col("value").is_null()) .then(pl.lit("missing")) .when(pl.col("value") < 10) .then("low") .otherwise("high") .alias("bucket") )

This produces "missing" for nulls, "low" for values under 10, and "high" otherwise. Every branch must use the same data type. If you used .then(0) for the null branch while "low" and "high" are strings, Polars would not be able to combine those branches into one column.

Using when-then-otherwise with pl.col and pl.lit for Dynamic Values

The then and otherwise branches can also be expressions that reference other columns. This allows you to copy values conditionally.

python
df = pl.DataFrame({ "a": [1, 2, 3], "b": [10, 20, 30], }) df.with_columns( pl.when(pl.col("a") > 1) .then(pl.col("b")) .otherwise(pl.lit(0)) .alias("c") )

Here, column c gets the value of b when a is greater than 1, otherwise 0. This is a common pattern for applying business rules that depend on multiple columns.

For literals, pl.lit is not always required; Polars accepts Python literals directly in then and otherwise. However, when you need to combine a literal with an expression (for example, pl.col("b") * 2), you can write that directly as an expression.

Compatibility with LazyFrames and Streaming

when-then-otherwise works on LazyFrame as well as on DataFrame. In a LazyFrame, select and with_columns add to the query plan and run when you call collect(). In an eager DataFrame, these methods execute immediately. In both cases, the conditional logic is vectorized rather than row-by-row.

Streaming support depends on the Polars version. If you use streaming execution, check the Polars documentation for the version you are using; the supported expression set can change between releases.

Final Thoughts on Structuring Complex Conditional Logic

When you find yourself chaining many .when() calls, consider whether the logic can be expressed more clearly with a mapping or a separate function. For example, if you are assigning categories based on a numeric range, a cut or binning utility might be more appropriate. However, for arbitrary boolean conditions, when-then-otherwise remains the most direct tool.

Another maintainability tip: name your conditions or use intermediate expressions. Polars allows you to define an expression as a variable and reuse it.

python
high_score = pl.col("score") >= 90 medium_score = pl.col("score") >= 70 df.with_columns( pl.when(high_score).then("high") .when(medium_score).then("medium") .otherwise("low") .alias("level") )

This makes the logic easier to read and modify. The same expression objects can be reused across multiple with_columns calls if needed.

Finally, remember that when-then-otherwise returns a Polars expression that can be used wherever an expression of the resulting type is accepted. This includes select, with_columns, group_by aggregations, and sort keys. It can also be used in filter when the branches produce a boolean result. Understanding this flexibility lets you solve many data transformation problems without resorting to Python loops or user-defined functions.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.