Implementation:Pola rs Polars Fold and Horizontal Ops

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

Overview

Concrete APIs for horizontal reduction operations across columns, including general-purpose fold, optimized horizontal sum, and string concatenation.

Description

Polars provides three horizontal operation APIs:

• pl.fold(acc, function, exprs) applies a binary function cumulatively across selected columns, starting from an accumulator. This is the most general horizontal operation and can implement addition, multiplication, boolean logic, or any custom binary function.
• pl.sum_horizontal(*exprs) is an optimized shorthand for horizontal addition that avoids the overhead of fold's function dispatch.
• pl.concat_str(exprs, separator) concatenates the string representations of multiple columns into a single string column.

These operations are used within DataFrame.select() or DataFrame.filter() to create new columns or filter rows based on cross-column computations.

Usage

Use these APIs whenever you need to:

• Compute row-wise sums across numeric columns.
• Filter rows where all columns meet a threshold using boolean fold.
• Concatenate column values into a single string.

Code Reference

Source Location

• Repository: Polars
• File: docs/source/src/python/user-guide/expressions/folds.py (lines 1-89)

Signature

# General horizontal fold
pl.fold(
    acc: IntoExpr,                    # Accumulator initial value (e.g., pl.lit(0))
    function: Callable[[Expr, Expr], Expr],  # Binary function (e.g., operator.add)
    exprs: IntoExpr | Iterable[IntoExpr],    # Columns to fold across
) -> Expr

# Optimized horizontal sum
pl.sum_horizontal(
    *exprs: IntoExpr,
) -> Expr

# String concatenation across columns
pl.concat_str(
    exprs: IntoExpr | Iterable[IntoExpr],
    *more_exprs: IntoExpr,
    separator: str = "",
) -> Expr

# Sorting results
DataFrame.sort(
    by: str | Expr | list[str | Expr],
    descending: bool | list[bool] = False,
) -> DataFrame

Import

import operator
import polars as pl

I/O Contract

Inputs

Name	Type	Required	Description
acc	IntoExpr	Yes (fold)	Initial accumulator value, typically pl.lit(0) for numeric or pl.lit(True) for boolean
function	Callable[[Expr, Expr], Expr]	Yes (fold)	Binary function applied to accumulator and each column (e.g., operator.add, lambda acc, x: acc & x)
exprs	IntoExpr	Yes	Column expressions to fold across (e.g., pl.col("a", "b"), pl.all())
separator	str	No (concat_str)	Separator string between concatenated values (default "")

Outputs

Name	Type	Description
result	DataFrame	DataFrame with horizontal computation results as new columns or filtered rows

Usage Examples

Horizontal Sum with Fold

import operator
import polars as pl

df = pl.DataFrame(
    {
        "label": ["foo", "bar", "spam"],
        "a": [1, 2, 3],
        "b": [10, 20, 30],
    }
)

result = df.select(
    pl.fold(
        acc=pl.lit(0),
        function=operator.add,
        exprs=pl.col("a", "b"),
    ).alias("sum_fold"),
    pl.sum_horizontal(pl.col("a", "b")).alias("sum_horz"),
)

Conditional Row Filtering with Fold

import polars as pl

df = pl.DataFrame(
    {
        "a": [1, 2, 3],
        "b": [0, 1, 2],
    }
)

# Filter rows where ALL columns are greater than 1
result = df.filter(
    pl.fold(
        acc=pl.lit(True),
        function=lambda acc, x: acc & x,
        exprs=pl.all() > 1,
    )
)

String Concatenation

import polars as pl

df = pl.DataFrame(
    {
        "label": ["foo", "bar", "spam"],
        "a": [1, 2, 3],
        "b": [10, 20, 30],
    }
)

# Concatenate column values as strings
result = df.select(
    pl.concat_str(["a", "b"]).alias("concat_no_sep"),
    pl.concat_str(["a", "b"], separator="-").alias("concat_with_sep"),
)

Fold Over All Numeric Columns

import operator
import polars as pl

df = pl.DataFrame(
    {
        "label": ["foo", "bar", "spam"],
        "a": [1, 2, 3],
        "b": [10, 20, 30],
        "c": [100, 200, 300],
    }
)

# Sum all numeric columns using wildcard selection
result = df.select(
    "label",
    pl.fold(
        acc=pl.lit(0),
        function=operator.add,
        exprs=pl.col("a", "b", "c"),
    ).alias("row_total"),
)

Related Pages

Implements Principle

• Principle:Pola_rs_Polars_Horizontal_Fold_Operations