narwhals.Expr.list

contains

contains(item: NonNestedLiteral) -> ExprT

Check if sublists contain the given item.

Parameters:

Name	Type	Description	Default
item	NonNestedLiteral	Item that will be checked for membership.	required

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame({"a": [[1, 2], None, []]})
>>> df = nw.from_native(df_native)
>>> df.with_columns(a_contains_1=nw.col("a").list.contains(1))
┌────────────────────────────┐
|     Narwhals DataFrame     |
|----------------------------|
|shape: (3, 2)               |
|┌───────────┬──────────────┐|
|│ a         ┆ a_contains_1 │|
|│ ---       ┆ ---          │|
|│ list[i64] ┆ bool         │|
|╞═══════════╪══════════════╡|
|│ [1, 2]    ┆ true         │|
|│ null      ┆ null         │|
|│ []        ┆ false        │|
|└───────────┴──────────────┘|
└────────────────────────────┘

get

get(index: int) -> ExprT

Return the value by index in each list.

Negative indices are not accepted.

Returns:

Type	Description
ExprT	A new expression.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame({"a": [[1, 2], [3, 4, None], [None, 5]]})
>>> df = nw.from_native(df_native)
>>> df.with_columns(a_first=nw.col("a").list.get(0))
┌──────────────────────────┐
|    Narwhals DataFrame    |
|--------------------------|
|shape: (3, 2)             |
|┌──────────────┬─────────┐|
|│ a            ┆ a_first │|
|│ ---          ┆ ---     │|
|│ list[i64]    ┆ i64     │|
|╞══════════════╪═════════╡|
|│ [1, 2]       ┆ 1       │|
|│ [3, 4, null] ┆ 3       │|
|│ [null, 5]    ┆ null    │|
|└──────────────┴─────────┘|
└──────────────────────────┘

len

len() -> ExprT

Return the number of elements in each list.

Null values count towards the total.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame({"a": [[1, 2], [3, 4, None], None, []]})
>>> df = nw.from_native(df_native)
>>> df.with_columns(a_len=nw.col("a").list.len())
┌────────────────────────┐
|   Narwhals DataFrame   |
|------------------------|
|shape: (4, 2)           |
|┌──────────────┬───────┐|
|│ a            ┆ a_len │|
|│ ---          ┆ ---   │|
|│ list[i64]    ┆ u32   │|
|╞══════════════╪═══════╡|
|│ [1, 2]       ┆ 2     │|
|│ [3, 4, null] ┆ 3     │|
|│ null         ┆ null  │|
|│ []           ┆ 0     │|
|└──────────────┴───────┘|
└────────────────────────┘

unique

unique() -> ExprT

Get the unique/distinct values in the list.

Null values are included in the result. The order of unique values is not guaranteed.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame({"a": [[1, 1, 2], [3, 3, None], None, []]})
>>> df = nw.from_native(df_native)
>>> df.with_columns(a_unique=nw.col("a").list.unique())
┌────────────────────────────┐
|     Narwhals DataFrame     |
|----------------------------|
|shape: (4, 2)               |
|┌──────────────┬───────────┐|
|│ a            ┆ a_unique  │|
|│ ---          ┆ ---       │|
|│ list[i64]    ┆ list[i64] │|
|╞══════════════╪═══════════╡|
|│ [1, 1, 2]    ┆ [1, 2]    │|
|│ [3, 3, null] ┆ [null, 3] │|
|│ null         ┆ null      │|
|│ []           ┆ []        │|
|└──────────────┴───────────┘|
└────────────────────────────┘