catalog.fn.aggregate()
Perform statistical aggregations on numeric attributes. Calculate sum, average, count, min, max, and distinct values across your dataset for analytics dashboards, KPI displays, and data summaries.
Syntax
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
attribute | string | Yes | The attribute to aggregate (supports deep queries like "product.price") |
types | AggregationType[] | Yes | Array of aggregation types: "sum", "avg", "count", "min", "max", "distinct", "group" |
excludeZeros | boolean | No | Exclude zero values from calculations (default: false) |
excludeUndefineds | boolean | No | Exclude undefined values from calculations (default: false) |
excludeUnresolved | boolean | No | Exclude unresolved references (default: false) |
distinctOptions.limit | number | No | Limit the number of distinct values returned |
distinctOptions.skipKeys | boolean | No | Skip returning item keys for distinct values (default: false) |
groupOptions.groups | AggregationGroupOption[] | No | Define custom ranges for grouped aggregation (e.g., { from: 0, to: 50 }) |
groupOptions.calculateNotFound | boolean | No | Include count of items not matching any group |
Return Type
Returns an Aggregation object with the requested metrics:
Usage Notes
- Aggregations respect current query filters - metrics update as filters change
- Use distinctOptions.limit for large datasets to limit returned distinct values
- Supports deep property queries (e.g., "product.brand.rating")
- Performance: Request only the aggregation types you need - each type adds computation cost
- Performance: Use distinctOptions.skipKeys: true when you only need values, not item references
- Performance: For large datasets, set distinctOptions.limit to avoid returning millions of distinct values
- Troubleshooting: If sum/avg returns 0 or undefined, verify the attribute is a numeric type
- Troubleshooting: Use excludeUndefineds: true if null/undefined values are skewing your averages
Related Methods
catalog.fn.facets()- Get unique values with counts for filter UIscatalog.fn.groupBy()- Group items with aggregations per groupcatalog.fn.pivot()- Create multi-dimensional pivot tables
Examples
Dashboard KPIs
Calculate key metrics for a dashboard including revenue, order count, average order value, and unique customers.
Customer Lifetime Value
Use distinct aggregation with keys to iterate through customers and calculate individual lifetime values.
Discount Analysis
Analyze discounts given across orders, calculate total discount amount and effective discount rate.
Sales by Region
Iterate through regions and calculate revenue metrics for each using filtered aggregations.
Product Category Performance
Get distinct categories and then aggregate price and rating metrics for each category.
Response Time Metrics
Calculate performance monitoring metrics including average, min, max response times and status code distribution.
Budget vs Actual Analysis
Compare budgeted amounts against actual spending with variance calculations.
Deep Property Aggregation
Aggregate values from referenced models using dot notation for deep property access.