--- schema_version: "1" id: 91cbc25e958ef3609b0def1d111edd0e15ca3d9670715404c4ab79583c143e1e title: Aggregate Schema collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/graphql-api/graphql/guides/aggregate/aggregate-schema.md canonical_url: https://developer.salesforce.com/docs/platform/graphql/guide/aggregate-schema.html source_site: developer.salesforce.com content_type: documentation content_hash: a82db502c5af5c40a21e9053966b45234e0572a0d7fd2e19bb178bccbaa7b8f9 products: - GraphQL API --- # Aggregate Schema | AVAILABLE API VERSION | | --------------------- | | API v58.0 and later | Like the [`Record` interface](https://developer.salesforce.com/docs/platform/graphql/query/query-record-objects.md), 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](https://developer.salesforce.com/docs/platform/graphql/get-started-graphql.md). ## 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](https://developer.salesforce.com/docs/platform/graphql/guide/aggregate-groupby.md). - `orderBy` - Orders the results using a specified field. See [Order Aggregate Results](https://developer.salesforce.com/docs/platform/graphql/guide/aggregate-orderby.md). - `scope` - An enumeration of the possible [scopes](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_using_scope.htm) 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](https://developer.salesforce.com/docs/platform/graphql/filter/filter-fields.md). ## RecordAggregateConnection Type Every object type corresponds to an `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](https://developer.salesforce.com/docs/platform/graphql/get-started-graphql.md). 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](https://developer.salesforce.com/docs/platform/graphql/guide/aggregate-support.md). 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`](https://developer.salesforce.com/docs/platform/graphql/query/query-record-objects.md#mapping-sobjects-to-graphql-objects). `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](https://developer.salesforce.com/docs/platform/graphql/guide/aggregate-support.md). ### 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.