# 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`](/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](/docs/platform/graphql/guide/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.

```sfdocs-code {"lang":"graphql", "title": "Query LeadSource from Lead", "src": "" }
query LeadSourceExample {
  uiapi {
    query {
      Lead {
        edges {
          node {
            LeadSource {
              value
            }
          }
        }
      }
    }
  }
}
```

The previous query is similar to the following SOQL statement.

```sfdocs-code {"lang":"sql", "title": "SOQL statement to query LeadSource", "src": "" }
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.

```sfdocs-code {"lang":"graphql", "title": "Query lead sources with grouping", "src": "" }
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.

```sfdocs-code {"lang":"sql", "title": "SOQL statement with GROUP BY clause", "src": "" }
SELECT LeadSource, COUNT(Name)
FROM Lead
GROUP BY LeadSource
```

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

```sfdocs-code {"lang":"graphql", "title": "Query distinct lead sources excluding null values", "src": "" }
query LeadSourceWithoutNullValues {
  uiapi {
    aggregate {
      Lead ( groupBy: { LeadSource: { group: true } } ) {
        edges {
          node {
            aggregate {
              LeadSource {
                value
              }
            }
          }
        }
      }
    }
  }
}
```

The previous query is similar to the folowing SOQL statement.

```sfdocs-code {"lang":"sql", "title": "SOQL statement with GROUP BY clause", "src": "" }
SELECT LeadSource
FROM Lead
GROUP BY LeadSource
```