Row selection
Select records meeting numeric or categorical conditions before further transformations.
Polars · Function
filter
Filters a DataFrame to rows whose predicate expressions evaluate to true. It preserves their order and supports keyword equality constraints that combine with other conditions.
How it works
Call DataFrame.filter with one or more expressions that produce Boolean series, or use keyword constraints for equality checks. Conditions are combined with logical AND, and the returned DataFrame keeps the input order of rows that evaluate to true.
Syntax
DataFrame.filter(predicates: IntoExprColumn | Iterable[IntoExprColumn] | bool | list[bool] | np.ndarray[Any, Any], **constraints: Any) → DataFrameParameters
| Name | Type | Description |
|---|---|---|
predicates | IntoExprColumn | Iterable[IntoExprColumn] | bool | list[bool] | np.ndarray[Any, Any] | Expression or iterable of expressions that evaluate to a Boolean Series; Boolean values and supported Boolean arrays are also accepted. |
**constraints | Any | Keyword column filters. Each name=value condition is equivalent to equality with that column and is combined with other conditions using AND. |
Returns
A DataFrame containing only rows retained by the predicate conditions.
Key points
- Use expressions to select only rows matching the desired conditions.
- Filtering does not reorder the surviving rows.
- Predicates may be expressions or supported Boolean collections.
- Each predicate must resolve to Boolean values across rows.
- Keyword arguments provide concise equality filters for named columns.
- Named constraints act as equality expressions and join conjunctively.
Common mistakes
- Rows whose predicate evaluates to null are removed just like rows evaluating to false.
- Comparisons involving null values do not retain rows through three-valued Boolean logic.
Example: Filter rows with predicates and a constraint
import polars as pl
df = pl.DataFrame({"score": [3, 8, 5], "team": ["A", "B", "A"]})
result = df.filter(
pl.col("score") >= 5,
team="A",
)
print(result)Keeps rows whose score is at least 5 and whose team equals A.
When to use it
Conjunctive filtering
Apply several required conditions without manually joining every expression with &.
Column equality filters
Use concise column=value syntax for straightforward equality checks.
Interview questions
QWhat does DataFrame.filter return?
DataFrame.filter returns a DataFrame containing rows whose predicate expressions evaluate to true. It preserves the original order of the retained rows.
Follow-up: What happens when a predicate produces null? The row is discarded because only true results are retained.
QHow are multiple filtering conditions combined?
Pass expressions such as pl.col("score") >= 5 as predicates. Multiple predicates can be supplied separately and are combined as conjunctive conditions.
Follow-up: How would you express a disjunction? Combine expressions with the | operator inside a predicate.
QHow do keyword constraints work?
A keyword constraint such as team="A" is treated like pl.col("team").eq("A"). Constraints are implicitly combined with other filter conditions using &.
Follow-up: What is the null caveat for equality constraints? A null comparison produces null, so that row is not retained.
Related
polars.DataFrame.removepolars.LazyFrame.filterpolars.Expr.filter