Salesforce Docs Portal

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.

type UIAPI {
  query: RecordQuery
  aggregate: RecordQueryAggregate!
}

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

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.

type RecordQueryAggregate {
  Account(
    after: String
    first: Int
    groupBy: Account_GroupBy
    orderBy: Account_OrderBy
    scope: ACCOUNT_SCOPE
    where: Account_Filter
  ): AccountAggregateConnection
}

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.

type AccountAggregateConnection {
  edges: [AccountAggregateEdge]
  pageInfo: PageInfo!
  totalCount: Int!
}

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.

type AccountAggregateEdge {
  cursor: String!
  node: AccountResult
}

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.

type AccountResult {
  aggregate: AccountAggregate
}

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.

type RecordAggregate {
  Id: IDAggregate
  ApiName: String!
  IntAggregate?: IntAggregate
  StringAggregate?: StringAggregate
  BooleanAggregate?: BooleanAggregate
  IDAggregate?: IDAggregate
  DateTimeAggregate?: DateTimeAggregate
  TimeAggregate?: TimeAggregate
  DateAggregate?: DateAggregate
  TextAreaAggregate?: TextAreaAggregate
  PhoneNumberAggregate?: PhoneNumberAggregate
  EmailAggregate?: EmailAggregate
  UrlAggregate?: UrlAggregate
  EncryptedStringAggregate?: EncryptedStringAggregate
  CurrencyAggregate?: CurrencyAggregate
  LongitudeAggregate?: LongitudeAggregate
  LatitudeAggregate?: LatitudeAggregate
  PicklistAggregate?: PicklistAggregate
  LongAggregate?: LongAggregate
  DoubleAggregate?: DoubleAggregate
  PercentAggregate?: PercentAggregate

}

Here's an example schema for AccountAggregate.

type AccountAggregate {
  Id: IDAggregate
  ApiName: String!
  AnnualRevenue: CurrencyAggregate
  Name: StringAggregate
  BillingCity: StringAggregate
  BillingCountry: StringAggregate
  BillingGeocodeAccuracy: PicklistAggregate
  BillingLatitude: LatitudeAggregate
  BillingLongitude: LongitudeAggregate
  BillingPostalCode: StringAggregate
  BillingState: StringAggregate
  BillingStreet: TextAreaAggregate
  CreatedById: IDAggregate
  CreatedDate: DateAggregate
}

note: 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.

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.

type StringAggregate {
  count: LongValue
  countDistinct: LongValue
  displayValue: String
  grouping: IntValue
  label: String
  max: StringValue
  min: StringValue
  value: String
}

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.

CurrencyAggregate Type {
  avg: DoubleValue
  count: LongValue
  countDistinct: LongValue
  displayValue: String
  format: String
  max: CurrencyValue
  min: CurrencyValue
  sum: CurrencyValue
  value: Currency
}

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.