|AVAILABLE API VERSION|
|API v56.0 and later|
|Compound fields available in API v59.0 and later|
Use queries to load objects such as Accounts or Contacts. The
query field under the
uiapi field is of
RecordQuery type and gives you access to all object types your Salesforce user has access to. Only objects supported by UI API are available for querying.
Access to supported objects and fields on those objects is controlled by the context user's object-level and field-level permissions. That is, an object is accessible if the user has the right permissions, and the object is either on the supported object list or is a custom object.
RecordQuery type has one field for each object type accessible to the user. Only
Account is shown here for brevity.
RecordQuery type contains these fields.
after- Returns the results after the given cursor. See Paginate Results.
first- Returns the first n results. See Paginate Results.
orderBy- Orders the query using a specified field. See Order 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. Relay Record Connections don’t have a
scopeargument, as child relationships can’t be filtered by a scope.
upperBound- Specifies the number of records by which to limit the query. Allows pagination up to
upperBoundnumber of records. Valid values are 200 to 2000.
where- Filters the query with an argument. See Field Operators.
Account field returns the
AccountConnection type, which represents a result set of records that ties together the records and page info.
AccountConnection ties together the elements of the result set (the edges) with information on the relative position of the returned edges to all possible results. See Paginate Results.
RecordConnection type contains these fields.
edges- A list of RecordEdge types.
pageInfo- Information on the relative location in the result set.
totalCount- The number of records as a result of the query.
RecordEdge type, represented by
AccountEdge here, ties together the record and its cursor.
RecordEdge type contains these fields.
cursor- An opaque string used to page directly to this item in the result set.
node- The GraphQL object equivalent for the Salesforce object.
PageInfo type contains relative position information, which shows where in the entire result set the current page is located. The
PageInfo type is the same for every
PageInfo type contains these fields.
hasNextPage- Specifies whether the result set have a next page
hasPreviousPage- Specifies whether the result set have a previous page
startCursor- An opaque string used to page to the first record in the result set
endCursor- An opaque string used to page to the last record in the result set
For more information on pagination, see Paginate Results.
Each supported sObject type the user has access to is mapped to a corresponding GraphQL object type of the same name. That is,
Account is mapped to a GraphQL object type named
MyCustomObject__c is mapped to
All object types implement the
Record interface, which has a standard set of fields that are useful for most applications.
For a complete list of fields on each object type, we recommend that you review the schema documentation using the Altair GraphQL client.
Standard fields on the
Record interface includes:
Id- The record ID.
ApiName- The API name of the Salesforce object.
WeakEtag- If the weak etag is non-zero, two records that have the same
WeakEtagis of the same version. This means they represent the same record at that point in time. When two records have the same
WeakEtag, the record with the greater
WeakEtagis the more recent version of the record.
DisplayValue- The displayable value for a field.
LastModifiedById- The ID of the user who last updated this record.
LastModifiedDate- The date and time when a user last modified this record. Date and time information is in ISO 8601 format.
SystemModStamp- The date and time when a user or an automated process (such as a trigger) last modified this record. Date and time information is in ISO 8601 format.
RecordTypeId- The record type ID for this record.
An object can map to three categories of fields:
Fields on the object are either mapped to a GraphQL Scalar or a "Field Value" type. The GraphQL Schema contains at least one scalar for each field type on Salesforce objects. The list of scalars that are used when mapping a field into the schema are as follows:
This list doesn't include every scalar type in the schema. Only the scalars that represent possible types for Salesforce object fields are listed.
Field value types have the naming pattern
<ScalarTypeName>Value, for example,
PicklistValue. All field value types have a field named
value, of the corresponding
scalar type. That is,
PicklistValue has a field value of type
Picklist. The field value type has a field called
label if the field type supports the
toLabel() SOQL function. The field value type has a field called
format if the field type supports the
format() SOQL function.
In addition, the field value type has a field called
displayValue, backed by whichever of the two
format() function calls the field type supports.
Currently, no field type supports both
toLabel(), and so there’s no ambiguity on which value is used for the
Here’s an example of a few field value types:
When mapping a Salesforce object field into the schema, the field is mapped to either a field value type or the scalar directly. The following is the process for the field type-mapping operation:
If the field name is Id, the scalar ID is used.
If the field type is Double, the field participates in a compound field of type Address or Geolocation and the field name is or ends with Latitude then the
LatitudeValueobject type is used.
If the field type is Double, the field participates in a compound field of type Address or Geolocation and the field name is or ends with Longitude then the
LongitudeValueobject type is used.
If the field type is TextArea, and the fields extra type info has the rich text flag, then the
RichTextAreaValueobject type is used.
If the field type is TextArea, and the fields length value is greater than 255, the
LongTextAreaValueobject type is used.
Otherwise, the field has the corresponding value type for the field type. That is, fields of type Picklist use the
PicklistValue type, while fields of type Currency use the
CurrencyValue type, and so on.
Compound fields correspond to the
ObjectName__FieldName__CompoundField GraphQL type. For example, the
BillingAddress field on the Account object, or the
Address field on the Lead object are compound fields. They correspond to the
Account_BillingAddress_CompoundField type and
Lead_Address_CompoundField type respectively.
Here’s an example of the
An address compound field comprises several constituent fields, like
A geolocation compound field includes the
Compound fields follow these restrictions.
- Include a compound field with its constituent fields in a query.
- Use the constituent fields when ordering by or filtering using a
- Use the constituent fields when working with aggregate queries.
This example queries accounts with its billing address fields.
Compound fields follow the limitations described at Object Reference for the Salesforce Platform.
Each parent relationship on an object has a corresponding field on the GraphQL object, if one of the sObjects that participates in the relationship also participates in the schema. The field name on the GraphQL object matches the relationship name. For example, both
Account participate in the schema, so an Account field (relationship name) of type
Account (sObject name) is present on type
If the object pointed at doesn’t appear in the schema, then no field for that relationship is added to the object type. For example, a relationship points at an object that's not supported by UI API, so it isn't mapped into the schema. As a result, the relationship isn’t mapped onto the object.
If the relationship is non-polymorphic, then the field has a type of that sObject.
If the relationship is polymorphic, then the fields name is still the relationship name, but the field type is a Union. The unions type name follows the pattern
<ObjectName>_<RelationshipName>. For example, the
SocialPost object has a polymorphic relationship named
Who, and so the union type name is
SocialPost_Who. Each concrete type in the schema that participates in the polymorphic relationship becomes a possible type of the union.
If no object types that participate in the polymorphic relationship are mappable into the schema, then the field for the relationship isn’t added to the type.
Each child relationship that points at an sObject type that participates in the schema is added as a field with a Relay Record Connection type to the GraphQL object. The name of the field matches the name of the child relationship. For example,
Account has a field named
Contacts of type
orderBy are constructed following the rules outlined in Filtering and Ordering, respectively. Scopes can’t be applied to querying child relationships, and as a result the field doesn’t have a