Aggregate Schema

AVAILABLE API VERSION
API v58.0 and later

Like the Record interface, the RecordQueryAggregate type corresponds to Salesforce fields, in addition to aggregation functions available on the fields.

1type UIAPI {
2  query: RecordQuery
3  aggregate: RecordQueryAggregate!
4}

To view the GraphQL API schema via introspection, use the Altair GraphQL Client.

Note

RecordQueryAggregate Type

The RecordQueryAggregate type allows for querying, filtering, and grouping of aggregations on records. RecordQueryAggregate has one field for each object type. The schema applies to all Salesforce objects. Account is shown here for brevity.

1type RecordQueryAggregate {
2  Account(
3    after: String
4    first: Int
5    groupBy: Account_GroupBy
6    orderBy: Account_OrderBy
7    scope: ACCOUNT_SCOPE
8    where: Account_Filter
9  ): AccountAggregateConnection
10}

The RecordQueryAggregate type contains these fields.

after - Returns the results after the given cursor.
first - Returns the first n results.
groupBy - Groups results according to the field values within the record, with a specified grouping function. Accepts a list of fields. See Group Results.
orderBy - Orders the results using a specified field. See Order Aggregate Results.
scope - An enumeration of the possible scopes that are defined for the object type. Provide this argument to filter the result set to records that have the specified scope.
where - Filters the query with an argument. See Field Operators.

RecordAggregateConnection Type

Every object type corresponds to an <object>AggregateConnection type, for example, AccountAggregateConnection, or RecordAggregateConnection as a representation for Salesforce objects.

The RecordAggregateConnection type allows for paging through result sets of records. For example, the Account field returns the AccountAggregateConnection type. AccountAggregateConnection can be embedded in other types to allow for both regular and aggregate queries across records from a single field.

1type AccountAggregateConnection {
2  edges: [AccountAggregateEdge]
3  pageInfo: PageInfo!
4  totalCount: Int!
5}

The RecordAggregateConnection type contains these fields.

edges - A list of RecordAggregateEdge types.
pageInfo - Information on the relative location in the result set.
totalCount - The number of record aggregates as a result of the query.

Aggregate queries can be paged using the RecordAggregateConnection and RecordAggregateEdge types.

RecordAggregateEdge Type

The RecordAggregateEdge type connects the record aggregation and its cursor.

1type AccountAggregateEdge {
2  cursor: String!
3  node: AccountResult
4}

The RecordAggregateEdge type contains these fields.

cursor - An opaque string used to page directly to this aggregate item in the result set.
node - The GraphQL object equivalent for the Salesforce object.

RecordResult Type

The RecordResult type represents a Salesforce object type and aggregates on those object types.

1type AccountResult {
2  aggregate: AccountAggregate
3}

RecordResult has an aggregate field of RecordAggregate type.

aggregate - The record aggregate, for example, AccountAggregate. Use aggregate with the groupBy argument or to query an aggregation field.

RecordAggregate Type

RecordAggregate has field categories for FieldAggregate types such as StringAggregate or CurrencyAggregate.

1type RecordAggregate {
2  Id: IDAggregate
3  ApiName: String!
4  IntAggregate?: IntAggregate
5  StringAggregate?: StringAggregate
6  BooleanAggregate?: BooleanAggregate
7  IDAggregate?: IDAggregate
8  DateTimeAggregate?: DateTimeAggregate
9  TimeAggregate?: TimeAggregate
10  DateAggregate?: DateAggregate
11  TextAreaAggregate?: TextAreaAggregate
12  PhoneNumberAggregate?: PhoneNumberAggregate
13  EmailAggregate?: EmailAggregate
14  UrlAggregate?: UrlAggregate
15  EncryptedStringAggregate?: EncryptedStringAggregate
16  CurrencyAggregate?: CurrencyAggregate
17  LongitudeAggregate?: LongitudeAggregate
18  LatitudeAggregate?: LatitudeAggregate
19  PicklistAggregate?: PicklistAggregate
20  LongAggregate?: LongAggregate
21  DoubleAggregate?: DoubleAggregate
22  PercentAggregate?: PercentAggregate
23
24}

Here’s an example schema for AccountAggregate.

1type AccountAggregate {
2  Id: IDAggregate
3  ApiName: String!
4  AnnualRevenue: CurrencyAggregate
5  Name: StringAggregate
6  BillingCity: StringAggregate
7  BillingCountry: StringAggregate
8  BillingGeocodeAccuracy: PicklistAggregate
9  BillingLatitude: LatitudeAggregate
10  BillingLongitude: LongitudeAggregate
11  BillingPostalCode: StringAggregate
12  BillingState: StringAggregate
13  BillingStreet: TextAreaAggregate
14  CreatedById: IDAggregate
15  CreatedDate: DateAggregate
16}

For a complete view of the RecordAggregate type schema in your Salesforce org, use the Altair GraphQL client.

Note

Consider these guidelines for RecordAggregate types.

The Id field is of IDAggregate type and is nullable.
LastModifiedById, LastModifiedDate, SystemModstamp, and RecordTypeId are queryable but not supported for aggregation.
LongTextArea, RichTextArea, MultiPicklist, Base64, and JSON can’t be grouped and don’t support aggregate functions. See Aggregate Functions for Field Types.

Certain field categories aren’t supported:

Polymorphic parent relationships
Child relationships

Additionally, polymorphic parent relationships aren’t queryable from RecordAggregate. Only root queries support aggregate expressions. Grouped queries can’t use child relationships in the SELECT list.

FieldAggregate Types

RecordAggregate contains field categories for FieldAggregate types, in comparison to FieldValue types on RecordRepresentation.

FieldAggregate types provide the value, format, label and displayValue fields, in addition to fields for the functions that the data type supports.

Only StringAggregate and CurrencyAggregate are listed here for brevity. The aggregate functions don’t apply to all field types. For example, grouping applies to StringAggregate but not CurrencyAggregate. Also, avg and sum apply to CurrencyAggregate but not StringAggregate. See Aggregate Functions for Field Types.

StringAggregate Type

While the max and min fields on StringAggregate are of StringValue type, the label field is not currently supported for max or min aggregation.

1type StringAggregate {
2  count: LongValue
3  countDistinct: LongValue
4  displayValue: String
5  grouping: IntValue
6  label: String
7  max: StringValue
8  min: StringValue
9  value: String
10}

The StringAggregate type contains these fields.

count - The number of results that matches the query criteria.
countDistinct - The number of distinct non-null field values matching the query criteria.
displayValue - The displayable value for a field.
grouping - Specifies if a field is used when composing the group. Use with the groupBy argument and the ROLLUP or CUBE type.
- Returns 0 if the aggregation is applied to the group.
- Returns 1 if the field is removed from consideration of the group.
- When all groupings return 1, the aggregation is applied to all results.
label - The text label for a field.
max - The maximum value of a field.
min - The minimum value of a field.
value - The raw value of a field.

CurrencyAggregate Type

CurrencyAggregate provides the same fields as StringAggregate, in addition to avg and sum.

1CurrencyAggregate Type {
2  avg: DoubleValue
3  count: LongValue
4  countDistinct: LongValue
5  displayValue: String
6  format: String
7  max: CurrencyValue
8  min: CurrencyValue
9  sum: CurrencyValue
10  value: Currency
11}

The CurrencyAggregate type contains these fields.

avg - The average value of the currency fields.
count - The number of results that matches the query criteria.
countDistinct - The number of distinct non-null field values matching the query criteria.
displayValue - The displayable value for the currency, such as the formatted value of the currency.
format - The localized formatting for the currency value.
max - The maximum value of a field.
min - The minimum value of a field.
sum - The total sum of the currency value.
value - The raw value of the currency value.