The Salesforce Developers website will undergo maintenance on May 29, 2024 from 3:00 a.m. UTC to 10:00 a.m. UTC. The maintenance process may affect the availability of our documentation. Please plan accordingly.

Aggregate Schema

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.

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

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.

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.

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.

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.

The RecordAggregateEdge type connects the record aggregation and its cursor.

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.

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

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 has field categories for FieldAggregate types such as StringAggregate or CurrencyAggregate.

Here's an example schema for AccountAggregate.

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

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.

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.

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

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 provides the same fields as StringAggregate, in addition to avg and sum.

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.