Create a struct column
Group related values into one nested column while retaining named fields.
Polars · Function
pl.struct
Collects columns or expressions into a single struct column. It returns an expression by default or an evaluated Series when eager=True.
How it works
pl.struct collects columns or expressions into a single struct-valued expression. Positional inputs become fields using their column names, keyword inputs use the keyword as the field name, and eager=True evaluates immediately to a Series.
Syntax
polars.struct(exprs: IntoExpr | Iterable[IntoExpr]*, schema: SchemaDict | None = None, eager: bool = False, **named_exprs: IntoExpr) → Expr | SeriesParameters
| Name | Type | Description |
|---|---|---|
exprs | IntoExpr | Iterable[IntoExpr] | Column or columns to collect into a struct; strings are column names and other non-expressions are literals. |
schema | SchemaDict | None | Optional mapping that explicitly defines struct field data types; its keys define columns when no expressions are supplied. |
eager | bool | If true, evaluate immediately and return a Series; otherwise return an expression. |
named_exprs | IntoExpr | Additional columns or expressions to collect; each field is renamed to its keyword. |
Returns
Expr | Series
Key points
- The function combines multiple column or expression results into one struct-valued column.
- Inputs may be Polars expressions, column-name strings, or other values interpreted as literals.
- A string selects a column, while a non-expression value contributes a literal field value.
- Use schema to declare field types explicitly instead of relying only on inferred dtypes.
- Keyword arguments provide another way to add fields while controlling their output names.
Common mistakes
- An empty input list does not infer fields; provide schema keys when defining a struct without expressions.
- The default returns an expression; set eager=True only when an immediate Series is wanted.
- Keyword arguments replace the original column names inside the resulting struct.
Example: Pack columns into a struct
import polars as pl
df = pl.DataFrame({"a": [1, 2], "b": ["x", "y"]})
result = df.select(
pl.struct("a", b="b").alias("record")
)
print(result)Packs columns into one struct column, naming the fields a and b.
When to use it
Compose expressions
Build a multi-column expression that can be processed as one value.
Rename struct fields
Give packed fields stable names independent of their source columns.
Interview questions
QWhat does pl.struct do, and what does it return by default?
pl.struct packs multiple columns or expressions into one struct column. With the default eager=False, it returns an Expr that can participate in a lazy or DataFrame expression pipeline.
Follow-up: How would you obtain an immediate result? Set eager=True, which evaluates the inputs and returns a Series instead of an expression.
QHow are positional and keyword inputs interpreted?
Positional inputs are collected as struct fields, and strings are interpreted as column names. Keyword expressions add fields whose names are the supplied keywords.
Follow-up: How can field names differ from source column names? Pass an input as a keyword expression, such as pl.struct(label="source").
QWhat is the purpose of schema?
schema optionally specifies the struct field data types. When no columns or expressions are supplied, its keys can also define the columns.
Follow-up: When is an explicit schema useful? Use it when field dtypes must be declared rather than inferred from supplied expressions.
Related
polars.Expr.struct.fieldpolars.Expr.struct.with_fieldspolars.datatypes.StructDataFrame.unnest