polars.Expr.arr.to_struct

Expr.arr.to_struct(n_field_strategy: ToStructStrategy = 'first_non_null', name_generator: Callable[[int], str] | None = None, upper_bound: int = 0) → Expr

Convert the series of type List to a series of type Struct.

Parameters:

n_field_strategy{‘first_non_null’, ‘max_width’}

Strategy to determine the number of fields of the struct.

name_generator

A custom function that can be used to generate the field names. Default field names are field_0, field_1 .. field_n

upper_bound

A polars LazyFrame needs to know the schema at all time. The caller therefore must provide an upper_bound of struct fields that will be set. If this is incorrectly downstream operation may fail. For instance an all().sum() expression will look in the current schema to determine which columns to select. It is advised to set this value in a lazy query.

Examples

>>> df = pl.DataFrame({"a": [[1, 2, 3], [1, 2]]})
>>> df.select([pl.col("a").arr.to_struct()])
shape: (2, 1)
┌────────────┐
│ a          │
│ ---        │
│ struct[3]  │
╞════════════╡
│ {1,2,3}    │
│ {1,2,null} │
└────────────┘
>>> df.select(
...     [
...         pl.col("a").arr.to_struct(
...             name_generator=lambda idx: f"col_name_{idx}"
...         )
...     ]
... ).to_series().to_list()
[{'col_name_0': 1, 'col_name_1': 2, 'col_name_2': 3},
{'col_name_0': 1, 'col_name_1': 2, 'col_name_2': None}]