Membership filtering
Filter or flag rows whose scalar values belong to an allowed-value collection.
Polars · Module
.is_in
Checks whether each value in a Series occurs in another Series or collection. It returns a Boolean Series, with optional control over whether null is treated as a distinct value.
How it works
Series.is_in compares each value with a Series or collection and returns a Boolean Series indicating membership. By default, null follows null-propagation semantics; setting nulls_equal=True makes null a distinct comparable value.
Syntax
Series.is_in(*other: Series | Collection[Any], ***, nulls_equal: bool = False) → SeriesParameters
| Name | Type | Description |
|---|---|---|
other | Series | Collection[Any] | A Series or collection to search in. |
nulls_equal | bool, default False | If True, treat null as a distinct value. Null values will not propagate. |
Returns
Series of data type Boolean.
Key points
- The method performs an element-wise membership test against another Series.
- The other argument may be a Series or a collection.
- The result is a Boolean Series.
- Setting nulls_equal=True changes null handling so null is compared as its own value.
- The method can compare values against a Series whose elements are lists, enabling sublist membership checks.
Common mistakes
- With nulls_equal=True, null is treated as a distinct value rather than propagating a null result.
Example: Check Series membership
import polars as pl
values = pl.Series("values", [1, 2, 3, None])
allowed = [2, 3]
print(values.is_in(allowed))
print(values.is_in(allowed, nulls_equal=True))Creates Boolean membership masks, with the second call treating null as a distinct value.
When to use it
List membership checks
Test candidate values against list-valued Series elements.
Null-aware comparisons
Choose explicit null behavior when building Boolean masks.
Interview questions
QWhat does Series.is_in return?
Series.is_in checks whether each element of the Series occurs in the supplied Series or collection and returns a Boolean Series. Its signature accepts the search values through other and exposes nulls_equal as a keyword-only option.
Follow-up: How would you make null comparable during membership testing? Pass nulls_equal=True so null is treated as a distinct value.
QHow does nulls_equal affect membership tests?
By default, nulls_equal is False, so null participates in null-propagation behavior. When it is True, null is considered a distinct value for the membership check.
Follow-up: What changes in the result when the searched values contain null? A null input can produce a Boolean result when nulls_equal=True, depending on whether null is present in the search values.
QWhat kinds of inputs can other contain?
The method accepts either another Series or a collection as the values to search. The resulting Series has Boolean data type.
Follow-up: How can membership be tested against row-wise list values? Use the Series containing candidate values as the receiver and the Series of list values as other, as shown by the documented sublist example.
Related
polars.Expr.is_inpolars.Expr.list.containspolars.Expr.arr.contains