catalog.fn.groupBy()
Group items by an attribute value and compute aggregations for each group. Perfect for creating categorized lists, calculating group statistics, and building hierarchical data displays.
Syntax
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
attribute | string | Yes | The attribute to group items by |
aggregates | AggregationOptions[] | No | Aggregations to compute per group (sum, avg, min, max, count, distinct) |
items | DcuplSectionItemOption[] | No | Configure which groups should include actual items (use { key: "*" } for all) |
excludeZeros | boolean | No | Exclude groups with 0 items (default: false) |
excludeUndefineds | boolean | No | Exclude groups with undefined value (default: false) |
sort | { attributes: string[], order: ("ASC" | "DESC")[] } | No | Sort groups by specified attributes |
projection | Projection<T> | No | Control which properties are returned for items |
Return Type
Returns a GroupByResponse object:
Usage Notes
- Groups respect current query filters - group counts update as filters change
- Use aggregates to compute statistics like sum, avg, min, max per group
- Items are only included if explicitly requested via the items option
- Supports deep queries for grouping by related model attributes (e.g., "category.parent")
- Performance: Only request items when needed - use { key: "specific-key" } instead of { key: "*" }
- Performance: Limit items per group with count parameter to avoid loading thousands of items
- Performance: Use projection to return only needed properties for items
- Troubleshooting: Use excludeUndefineds: true to skip groups with undefined key values
Related Methods
catalog.fn.facets()- Get unique values with counts for building filter UIscatalog.fn.aggregate()- Compute aggregations across all itemscatalog.fn.pivot()- Create multi-dimensional pivot tables
Examples
Product Catalog by Category
Group products by category with multiple aggregations and include actual items with pagination.
Sales by Region with Sorting
Group orders by region, calculate revenue metrics, and sort by aggregated values.
Tasks by Project with Selective Items
Group tasks by project and include items only for specific projects that need attention.
Content by Tag (Multi-valued)
Group articles by tags (multi-valued attribute) with sorting and item inclusion.
Orders by Customer Segment (Deep Property)
Group orders by customer segment using deep property access with dot notation.
Campaigns by Channel with KPIs
Group marketing campaigns by channel and calculate conversion metrics from aggregations.
Feedback by Rating with Selective Retrieval
Group feedback by rating and retrieve items only for low ratings that need attention.
Products Low on Stock by Category
Pre-filter to low-stock products, then group by category to identify inventory issues.