---
schema_version: "1"
id: c9709a7d003798e97bd82129f6fc81ce45b33daaa8dabcc106e6c99bfdbf3c3e
title: Group Aggregate Results
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/graphql-api/graphql/guides/aggregate/aggregate-groupby.md
canonical_url: https://developer.salesforce.com/docs/platform/graphql/guide/aggregate-groupby.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 64065336184dabdec5f2a7484c7d994d50a44fefc21eb276240ad0ecd755497f
products:
  - GraphQL API
---
# Group Aggregate Results

| AVAILABLE API VERSION |
| --------------------- |
| API v58.0 and later   |

Group results using the `groupBy` argument. Results are grouped according to the field values within the record and the provided grouping function.

When querying a [`RecordAggregate`](https://developer.salesforce.com/docs/platform/graphql/guide/aggregate.md#recordaggregate-type), you can pass in an aggregate function and a `groupBy` argument. If you don't need aggregation, use the [`RecordQuery` type](https://developer.salesforce.com/docs/platform/graphql/query/query-record-objects.md) instead.

The `groupBy` argument behaves like the [SOQL `GROUP BY` clause](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_groupby.htm). It can map elements to groups in three ways:

- Using the distinct set of values you provide for the `groupBy` argument
- Using the `CUBE` type
- Using the `ROLLUP` type

## Groupable Fields

Grouping is useful for summarizing your data based on a particular field. For example, when grouping by an Industry, passing in `Industry` to the `groupBy` argument clause assigns all Accounts that share an Industry to the same group, similar to a `GROUP BY Industry` SOQL clause.

The following field types support grouping. A Date/Time function can be applied to the field if it's a Date, Time, or DateTime function.

|         | Group by ApiName | Group by Date/Time Function |
| :-----: | :--------------: | :-------------------------: |
| Boolean |        ✅        |                             |
|  Date   |        ✅        |             ✅              |
|   Int   |        ✅        |                             |
|  Email  |        ✅        |                             |
| String  |        ✅        |                             |
|   ID    |        ✅        |                             |

Group your results to avoid iterating through individual query results, specifying a group of records instead. You can use `groupBy` with aggregate functions like `sum` or `max`, which summarizes the data and enables you to roll up query results.

## Example: Query Object with Grouping

First, you can query the `LeadSource` without grouping, which returns a list of all lead sources on each lead, including duplicate values.

```
query LeadSourceExample {
  uiapi {
    query {
      Lead {
        edges {
          node {
            LeadSource {
              value
            }
          }
        }
      }
    }
  }
}
```

The previous query is similar to the following SOQL statement.

```
SELECT LeadSource FROM Lead
```

Instead of writing code to iterate through the query results and increment counters for each LeadSource value, you can use `groupBy` to return the same results.

```
query LeadSourceExample {
  uiapi {
    aggregate {
      Lead ( groupBy: { LeadSource: { group: true } } ) {
        edges {
          node {
            aggregate {
              Name {
                count {
                  value
                }
              }
            }
          }
        }
      }
    }
  }
}
```

The previous query is similar to the following SOQL statement.

```
SELECT LeadSource, COUNT(Name)
FROM Lead
GROUP BY LeadSource
```

You can also query all distinct values, including `null`, without an aggregated function.

```
query LeadSourceWithoutNullValues {
  uiapi {
    aggregate {
      Lead ( groupBy: { LeadSource: { group: true } } ) {
        edges {
          node {
            aggregate {
              LeadSource {
                value
              }
            }
          }
        }
      }
    }
  }
}
```

The previous query is similar to the folowing SOQL statement.

```
SELECT LeadSource
FROM Lead
GROUP BY LeadSource
```