--- title: "Aggregation" enterprise: true framework: javascript version: "36.1.0" --- # Aggregation Apply custom or provided functions to values to calculate group values in the grid. #### Aggregation Overview ```ts import { ClientSideRowModelModule, GridApi, GridOptions, ModuleRegistry, createGrid, enableDevValidations, } from "ag-grid-community"; import { ColumnMenuModule, RowGroupingModule } from "ag-grid-enterprise"; import { IOlympicData } from "./interfaces"; // Enable extended validations only for development if (process.env.NODE_ENV !== "production") { enableDevValidations(); } ModuleRegistry.registerModules([ ClientSideRowModelModule, ColumnMenuModule, RowGroupingModule, ]); let gridApi: GridApi; const gridOptions: GridOptions = { columnDefs: [ { field: "country", rowGroup: true, hide: true }, { field: "bronze", aggFunc: "sum" }, { field: "silver", aggFunc: "avg" }, { field: "gold", aggFunc: "custom_Mode" }, ], defaultColDef: { flex: 1, minWidth: 100, }, autoGroupColumnDef: { minWidth: 200, }, grandTotalRow: "bottom", groupTotalRow: "bottom", aggFuncs: { custom_Mode: (params) => { const counts = new Map(); let mode = null; let maxCount = 0; for (const value of params.values) { if (value == null) continue; const count = (counts.get(value) ?? 0) + 1; counts.set(value, count); if (count > maxCount) { maxCount = count; mode = value; } } return mode; }, }, }; const gridDiv = document.querySelector("#myGrid")!; gridApi = createGrid(gridDiv, gridOptions); fetch("https://www.ag-grid.com/example-assets/small-olympic-winners.json") .then((response) => response.json()) .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data)); ``` [Live example: Aggregation Overview](https://www.ag-grid.com/examples/aggregation/aggregation-overview/typescript) This example also demonstrates using the built in aggregations of `sum` and `avg` as well as a custom `mode` implementation via a [Custom Aggregation Function](https://www.ag-grid.com/javascript-data-grid/aggregation-custom-functions/). [Group and Grand Total Rows](https://www.ag-grid.com/javascript-data-grid/aggregation-total-rows/) are also enabled. ## Enabling Aggregation Aggregations can be enabled in the grid by setting the `aggFunc` column definition value to one of: `sum`, `min`, `max`, `count`, `avg`, `first`, or `last`. The following configuration demonstrates how to enable aggregation on a column: ```js const gridOptions = { columnDefs: [ { field: 'gold', aggFunc: 'sum' }, { field: 'silver', aggFunc: 'max' }, { field: 'bronze', aggFunc: 'avg' }, // ... other column definitions ], // other grid options ... } ``` ## API Reference > **Note** > > The aggregation state can be saved and restored as part of [Grid State](https://www.ag-grid.com/javascript-data-grid/grid-state/). Aggregations can be configured using the following column properties: | Property | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `aggFunc` | [`string \| IAggFunc \| null`](https://www.ag-grid.com/javascript-data-grid/aggregation-custom-functions/) | | | Name of function to use for aggregation. In-built options are: `sum`, `min`, `max`, `count`, `avg`, `first`, `last`. Also accepts a custom aggregation name or an aggregation function. See [Enabling Aggregation](https://www.ag-grid.com/javascript-data-grid/aggregation-columns/#enabling-aggregation) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `initialAggFunc` | [`string \| IAggFunc`](https://www.ag-grid.com/javascript-data-grid/aggregation-custom-functions/) | | | Same as `aggFunc`, except only applied when creating a new column. Not applied when updating column definitions. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). [Initial](https://www.ag-grid.com/javascript-data-grid/grid-interface/#initial-grid-options). | | `valueIndex` | `number` | | | The position of this column in the order of value columns when aggregating in pivot mode. When aggregating by a single column, any number can be used. When aggregating by multiple columns, this determines the order (e.g. `0` for first, `1` for second). Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `initialValueIndex` | `number` | | | Same as `valueIndex`, except only applied when creating a new column. Not applied when updating column definitions. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/). [Initial](https://www.ag-grid.com/javascript-data-grid/grid-interface/#initial-grid-options). | | `enableValue` | `boolean` | | `false` | Set to `true` if you want to be able to aggregate by this column via the GUI. This will not block the API or properties being used to achieve aggregation. See [Configuring via the UI](https://www.ag-grid.com/javascript-data-grid/aggregation-columns/#configuring-via-the-ui) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `allowedAggFuncs` | `string[]` | | | Aggregation functions allowed on this column e.g. `['sum', 'avg']`. If missing, all installed functions are allowed. This will only restrict what the GUI allows a user to select, it does not impact when you set a function via the API. See [Allowed Functions](https://www.ag-grid.com/javascript-data-grid/aggregation-columns/#allowed-functions) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `defaultAggFunc` | `string` | | `'sum'` | The name of the aggregation function to use for this column when it is enabled via the GUI. Note that this does not immediately apply the aggregation function like `aggFunc` See [Default Function](https://www.ag-grid.com/javascript-data-grid/aggregation-columns/#default-function) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `showValuesAs` | `ShowValuesAsType \| ShowValuesAs \| null` | | | The active "Show Values As" mode for this column. Shows the column's aggregated value relative to another total, for example as a percentage of the grand total, column total, row total or parent total. This changes only the displayed value; the underlying value used by `getDataValue` and charts is unchanged. Use a built-in mode name, or the object form `{ type, params, precision }`. Set `null` for no active mode. See [Show Values As](https://www.ag-grid.com/javascript-data-grid/aggregation-show-values-as/) for more information. Module: [`ShowValuesAsModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `initialShowValuesAs` | `ShowValuesAsType \| ShowValuesAs` | | | Same as `showValuesAs`, except only applied when creating a new column. Module: [`ShowValuesAsModule`](https://www.ag-grid.com/javascript-data-grid/modules/). [Initial](https://www.ag-grid.com/javascript-data-grid/grid-interface/#initial-grid-options). | | `showValuesAsDef` | `ShowValuesAsDef \| null` | | | Per-column "Show Values As" configuration: `precision`, `suppressHeaderIndicator`, and user-provided `modes` (custom modes / overrides of the built-ins). Deep-merges from `defaultColDef`. The active mode is the `showValuesAs` selector. `null` disables the feature for the column (useful to opt a column out via `defaultColDef`). See [Configuration](https://www.ag-grid.com/javascript-data-grid/aggregation-show-values-as/#configuration) for more information. Module: [`ShowValuesAsModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `enableShowValuesAs` | `boolean` | | `false` | Shows the "Show Values As" submenu in the column menu. On `defaultColDef`, `true` shows the submenu only for value columns and numeric columns. On an individual column, `true` always shows it; use this when the grid cannot infer that the column returns numbers, for example with a `valueGetter` or custom `aggFunc`. `false` hides the submenu. This controls menu visibility only. Modes set through `showValuesAs` or Column State still apply. Module: [`ShowValuesAsModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | Aggregation functions can be registered with the grid using the following grid options: | Property | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `aggFuncs` | `IAggFuncs` | | | A map of 'function name' to 'function' for custom aggregation functions. See [Custom Aggregation Functions](https://www.ag-grid.com/javascript-data-grid/aggregation-custom-functions/) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). [Initial](https://www.ag-grid.com/javascript-data-grid/grid-interface/#initial-grid-options). | | `groupTotalRow` | `'top' \| 'bottom' \| UseGroupTotalRow` | | | When provided, an extra row group total row will be inserted into row groups at the specified position, to display when the group is expanded. This row will contain the aggregate values for the group. If a callback function is provided, it can be used to selectively determine which groups will have a total row added. See [Group Total Rows](https://www.ag-grid.com/javascript-data-grid/aggregation-total-rows/#enabling-group-total-rows) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `grandTotalRow` | `'top' \| 'bottom' \| 'pinnedTop' \| 'pinnedBottom'` | | | When provided, an extra grand total row will be inserted into the grid at the specified position. This row displays the aggregate totals of all rows in the grid. See [Grand Total Row](https://www.ag-grid.com/javascript-data-grid/aggregation-total-rows/#enabling-a-grand-total-row) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `suppressAggFuncInHeader` | `boolean` | | `false` | When `true`, column headers won't include the `aggFunc` name, e.g. `'sum(Bank Balance)`' will just be `'Bank Balance'`. See [Omit Function Name from Header](https://www.ag-grid.com/javascript-data-grid/aggregation-columns/#omit-function-name-in-header) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `aggregateOnlyChangedColumns` | `boolean` | | `false` | When using change detection, only the updated column will be re-aggregated. See [Change Detection](https://www.ag-grid.com/javascript-data-grid/change-detection/#tree-path-selection) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `suppressAggFilteredOnly` | `boolean` | | `false` | Set to `true` so that aggregations are not impacted by filtering. See [Aggregate Before Filtering](https://www.ag-grid.com/javascript-data-grid/aggregation-filtering/) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `groupAggFiltering` | `boolean \| IsRowFilterable` | | `false` | Set to determine whether filters should be applied on aggregated group values. See [Filtering for Aggregate Values](https://www.ag-grid.com/javascript-data-grid/aggregation-filtering/#filtering-for-aggregated-values) for more information. Module: [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `groupSuppressBlankHeader` | `boolean` | | `false` | If `true`, and showing footer, aggregate data will always be displayed at both the header and footer levels. This stops the possibly undesirable behaviour of the header details 'jumping' to the footer on expand. See [Showing Values in Group and Total Rows](https://www.ag-grid.com/javascript-data-grid/aggregation-total-rows/#keeping-group-row-values) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `suppressStickyTotalRow` | `boolean \| 'grand' \| 'group'` | | | Suppress the sticky behaviour of the total rows, can be suppressed individually by passing `'grand'` or `'group'`. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `alwaysAggregateAtRootLevel` | `boolean` | | `false` | When using aggregations, the grid will always calculate the root level aggregation value. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `getGroupRowAgg` | `GetGroupRowAgg` | | | Callback to use when you need access to more then the current column for aggregation. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`ServerSideRowModelModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | After the grid is initialised aggregations can be applied / retrieved / removed via the `api` with the following methods: | Property | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `getValueColumns` | `Function` | | | Get a list of the existing value columns. Module: [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `addValueColumns` | `Function` | | | Add the given list of columns to the existing set of value columns. Module: [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `removeValueColumns` | `Function` | | | Remove the given list of columns from the existing set of value columns. Module: [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `setValueColumns` | `Function` | | | Set the value columns to the provided list of columns. Module: [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `setColumnAggFunc` | `Function` | | | Sets the agg function for a column. `aggFunc` can be one of the built-in aggregations or a custom aggregation by name or direct function. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `addAggFuncs` | `Function` | | | Add aggregations function with the specified keys. See [Registering Custom Functions](https://www.ag-grid.com/javascript-data-grid/aggregation-custom-functions/#registering-custom-functions) for more information. Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | | `clearAggFuncs` | `Function` | | | Clears all aggregation functions (including those provided by the grid). Modules (any of): [`RowGroupingModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`PivotModule`](https://www.ag-grid.com/javascript-data-grid/modules/), [`TreeDataModule`](https://www.ag-grid.com/javascript-data-grid/modules/). | ## Editing Aggregated Values Group row cells displaying aggregated values can be made editable, allowing users to edit a group total and have the change distributed back down to descendant rows. The built-in distribution supports all standard aggregation functions and can be customised per column. See [Editing Group Rows](https://www.ag-grid.com/javascript-data-grid/grouping-edit/) for full details on `groupRowEditable`, `groupRowValueSetter`, and distribution strategies. ## Retrieving Aggregated Children The method `rowNode.getAggregatedChildren(colKey)` with Client Side Row Model returns the immediate children that contribute to the aggregation of a group row. This is useful when implementing custom logic based on aggregated data or when [Editing Group Rows](https://www.ag-grid.com/javascript-data-grid/grouping-edit/) to update child rows accordingly. - For regular group columns, returns the direct children used for aggregation (respecting `suppressAggFilteredOnly` and `groupAggFiltering` settings). - For pivot columns on leaf groups, returns only the children matching the column's pivot keys. - Returns an empty array for leaf (non-group) rows. ### Retrieving All Leaf Descendants Pass `true` as the second argument to collect all descendant leaf (data) rows recursively: ```ts const allLeaves = groupNode.getAggregatedChildren(colKey, true); ``` This traverses the full group hierarchy and returns every non-group row that ultimately contributes to the group's aggregated value, respecting the same filtering and pivot rules as the non-recursive call. > **Note** > > Calling `getAggregatedChildren(colKey, true)` allocates a new array and visits every descendant node. On large or deeply nested datasets this can be expensive, so prefer the non-recursive form when only immediate children are needed.