Implementation:Pola rs Polars Filter by Time Range

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

Overview

Concrete APIs for filtering Polars DataFrames by temporal predicates including range checks, component extraction, and combined boolean conditions.

Description

DataFrame.filter(predicate) accepts a boolean expression and returns a new DataFrame containing only the rows where the predicate evaluates to True. For temporal filtering, the predicate is constructed using Expr.is_between(lower, upper) for range queries, Expr.dt.year() / Expr.dt.month() for component extraction, and standard logical operators (&, |, ~) for combining conditions.

Python's built-in datetime.date and datetime.datetime objects are used to specify temporal bounds, providing a natural interface for defining time ranges.

Usage

Use these APIs whenever you need to:

• Select rows within a specific date or datetime range.
• Filter by calendar components (year, month, day of week).
• Build complex temporal queries by combining multiple conditions.

Code Reference

Source Location

• Repository: Polars
• File: docs/source/src/python/user-guide/transformations/time-series/filter.py (lines 1-30)

Signature

DataFrame.filter(
    *predicates: Expr | bool | list[Expr],
    **constraints: Any,
) -> DataFrame

Expr.is_between(
    lower_bound: Any,
    upper_bound: Any,
    closed: str = "both",
) -> Expr

# Temporal component accessors
Expr.dt.year() -> Expr
Expr.dt.month() -> Expr
Expr.dt.day() -> Expr
Expr.dt.weekday() -> Expr

Import

from datetime import date, datetime
import polars as pl

I/O Contract

Inputs

Name	Type	Required	Description
predicates	bool | list[Expr]	Yes	Boolean expression(s) defining which rows to keep
lower_bound	date	Yes (for is_between)	Lower bound of the temporal range (inclusive by default)
upper_bound	date	Yes (for is_between)	Upper bound of the temporal range (inclusive by default)
closed	str	No	Boundary inclusion: "both" (default), "left", "right", or "none"

Outputs

Name	Type	Description
result	pl.DataFrame	A new DataFrame containing only rows that satisfy the temporal predicate

Usage Examples

Range Filter with is_between

from datetime import date, datetime
import polars as pl

# Select rows within a date range
df_filtered = df.filter(
    pl.col("Date").is_between(datetime(2020, 1, 1), datetime(2020, 12, 31))
)

Component Filter

from datetime import date, datetime
import polars as pl

# Filter by year component
df_filtered = df.filter(pl.col("Date").dt.year() == 2020)

Combined Temporal Filter

from datetime import date, datetime
import polars as pl

# Filter for second half of 2020
df_filtered = df.filter(
    (pl.col("Date").dt.month() >= 6) & (pl.col("Date").dt.year() == 2020)
)

Related Pages

Implements Principle

• Principle:Pola_rs_Polars_Time_Range_Filtering