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, you can pass in an aggregate function and a groupBy argument. If you don’t need aggregation, use the RecordQuery type instead.

The groupBy argument behaves like the SOQL GROUP BY clause. 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.

1query LeadSourceExample {
2  uiapi {
3    query {
4      Lead {
5        edges {
6          node {
7            LeadSource {
8              value
9            }
10          }
11        }
12      }
13    }
14  }
15}

The previous query is similar to the following SOQL statement.

1SELECT 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.

1query LeadSourceExample {
2  uiapi {
3    aggregate {
4      Lead ( groupBy: { LeadSource: { group: true } } ) {
5        edges {
6          node {
7            aggregate {
8              Name {
9                count {
10                  value
11                }
12              }
13            }
14          }
15        }
16      }
17    }
18  }
19}

The previous query is similar to the following SOQL statement.

1SELECT LeadSource, COUNT(Name)
2FROM Lead
3GROUP BY LeadSource

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

1query LeadSourceWithoutNullValues {
2  uiapi {
3    aggregate {
4      Lead ( groupBy: { LeadSource: { group: true } } ) {
5        edges {
6          node {
7            aggregate {
8              LeadSource {
9                value
10              }
11            }
12          }
13        }
14      }
15    }
16  }
17}

The previous query is similar to the folowing SOQL statement.

1SELECT LeadSource
2FROM Lead
3GROUP BY LeadSource