Implementation:Pola rs Polars Expr Over Window

Knowledge Sources	Polars Polars Docs
Domains	Data Engineering, DataFrame
Last Updated	2026-02-09 10:00 GMT

Overview

Concrete APIs for computing window functions that produce per-group values while preserving the original row count, using the .over() expression clause.

Description

The Expr.over() method transforms any expression into a window function. It partitions the DataFrame rows by the specified columns and evaluates the expression within each partition. The result is mapped back to the original DataFrame, preserving the row count.

The mapping_strategy parameter controls the output shape:

• "group_to_rows" (default) broadcasts a single value per group to all rows in that group, or maps sorted/ranked values back to their original positions.
• "explode" flattens the result, reordering rows so that each group's output appears contiguously.
• "join" produces a list column where each row contains the full grouped result as a list.

Common patterns include ranking with Expr.rank(), computing group means with Expr.mean(), and sorting within groups with Expr.sort_by(), all chained before .over().

Usage

Use .over() whenever you need to:

• Add group-level statistics as new columns without collapsing rows.
• Rank rows within each group.
• Sort rows within groups using the explode mapping strategy.

Code Reference

Source Location

• Repository: Polars
• File: docs/source/src/python/user-guide/expressions/window.py (lines 17-146)

Signature

# Window function via over()
Expr.over(
    *partition_by: str | Expr,
    mapping_strategy: str = "group_to_rows",  # "group_to_rows", "explode", "join"
) -> Expr

# Ranking within groups
Expr.rank(
    method: str = "dense",      # "dense", "ordinal", "min", "max", "average", "random"
    descending: bool = False,
) -> Expr

# Sorting within groups
Expr.sort_by(
    *by: str | Expr,
    descending: bool | list[bool] = False,
) -> Expr

Import

import polars as pl

I/O Contract

Inputs

Name	Type	Required	Description
*partition_by	Expr	Yes	One or more column names or expressions defining the window partition
mapping_strategy	str	No	How to map grouped results back to rows: "group_to_rows" (default), "explode", or "join"
method	str	No	Rank method: "dense" (default), "ordinal", "min", "max", "average", "random"
descending	bool	No	Reverse order for ranking or sorting (default False)

Outputs

Name	Type	Description
result	DataFrame	DataFrame with the same row count as the input, with new per-group computed columns added

Usage Examples

Rank Within Group

import polars as pl

result = pokemon.select(
    pl.col("Name", "Type 1"),
    pl.col("Speed")
    .rank("dense", descending=True)
    .over("Type 1")
    .alias("Speed rank"),
)

Group Mean as New Column

import polars as pl

result = pokemon.select(
    pl.col("Name", "Type 1", "Speed"),
    pl.col("Speed").mean().over("Type 1").alias("Mean speed in group"),
)

Sort Within Group Using Explode Strategy

import polars as pl

result = athletes.select(
    pl.all()
    .sort_by(pl.col("rank"))
    .over(pl.col("country"), mapping_strategy="explode"),
)

Multiple Window Functions

import polars as pl

result = pokemon.select(
    pl.col("Name", "Type 1", "Speed"),
    pl.col("Speed").mean().over("Type 1").alias("Mean speed"),
    pl.col("Speed").min().over("Type 1").alias("Min speed"),
    pl.col("Speed").max().over("Type 1").alias("Max speed"),
    pl.col("Speed").rank("dense", descending=True).over("Type 1").alias("Speed rank"),
)

Window with Join Mapping Strategy

import polars as pl

# Each row gets a list of all speeds in its type group
result = pokemon.select(
    pl.col("Name", "Type 1"),
    pl.col("Speed").over("Type 1", mapping_strategy="join").alias("All speeds in group"),
)

Related Pages

Implements Principle

• Principle:Pola_rs_Polars_Window_Function_Application
• Heuristic:Pola_rs_Polars_Avoid_Lambda_In_Aggregation