Grouped aggregation
Summarize measures by category, customer, or other keys.
Polars · Module
df.group_by
Starts a group-by operation over columns or expressions and returns a GroupBy object for per-group aggregation. Group order can optionally follow input order with maintain_order=True.
How it works
Call group_by with one or more grouping columns or expressions to obtain a GroupBy object. Use that object’s aggregation methods, such as agg, to calculate results per group; optionally enable maintain_order when group order must follow the input.
Syntax
DataFrame.group_by(by: IntoExpr | Iterable[IntoExpr], maintain_order: bool = False, **named_by: IntoExpr) → GroupByParameters
| Name | Type | Description |
|---|---|---|
by | IntoExpr | Iterable[IntoExpr] | Column(s) to group by; accepts expressions, and strings are interpreted as column names. |
maintain_order | bool = False | Whether group order should follow input order; enabled ordering may be slower and disables streaming. |
named_by | IntoExpr | Additional grouping columns supplied as keyword arguments; each output grouping column uses its keyword name. |
Returns
GroupBy object used to perform aggregations.
Key points
- The method creates a grouping context rather than immediately producing an aggregated DataFrame.
- Use
byto specify the columns or expressions that define group membership. - Grouping keys may be expressions, enabling derived values to define groups.
- A string passed as a grouping key is resolved as a column name.
- Keyword arguments provide extra grouping columns and rename them to their keyword names.
Common mistakes
- Setting
maintain_order=Truecan reduce performance compared with the default behavior. - Using
maintain_order=Trueprevents execution with the streaming engine. - The option controls group ordering, not the original row order within each group.
Example: Group and aggregate rows
import polars as pl
df = pl.DataFrame({"team": ["A", "A", "B"], "points": [10, 20, 7]})
result = df.group_by("team").agg(
pl.col("points").sum().alias("total_points")
)
print(result.sort("team"))Groups rows by team and computes the total points for each group.
When to use it
Expression-based grouping
Build groups from calculated expressions instead of only existing columns.
Group iteration
Inspect or process rows belonging to each group.
Order-sensitive grouping
Preserve the order in which groups first appear in the input.
Interview questions
QWhat does DataFrame.group_by return and how is it used?
DataFrame.group_by starts a grouping operation and returns a GroupBy object. Aggregations are then performed through methods such as agg.
Follow-up: How would you preserve input group order? Use maintain_order=True, accepting its performance and streaming limitations.
QWhat kinds of grouping keys does group_by accept?
The by argument accepts a column name, multiple columns, or expressions. A string is interpreted as a column name, while expressions allow computed grouping keys.
Follow-up: How can multiple grouping keys be supplied? Pass an iterable of expressions or column names, or use named keyword arguments for additional renamed grouping columns.
QWhen should maintain_order be enabled?
By default, the ordering of groups is not guaranteed to match the input order. Setting maintain_order=True makes group order consistent with the input data.
Follow-up: Does this option reorder rows inside each group? No; row order within every group remains preserved regardless of the setting.
Related
polars.dataframe.group_by.GroupByGroupBy.aggGroupBy.lenGroupBy.sumDataFrame.group_by_dynamic