Query Objects
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 the UI API are available for querying.
Access to supported objects and fields on those objects is controlled by the current 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.
To access an object type, request a field with the same name under the RecordQuery
type. This example queries accounts with their IDs and names.
The query returns only objects and fields that the user has access to.
Within RecordQuery
, each field is a Relay Record Connection type. Connections enable paging through the result set with ease. Connections are made up of four types:
Connection
: The root object for the paged collection, which ties together the result set with thePageInfo
type. TheConnection
type is specific to the type of resource being paged, for example when paging throughAccount
objects theConnection
type isAccountConnection
.Edge
: Ties together the actual record result type, for exampleAccount
. Includes a cursor that points to the specific location in the result set and theNode
type.Node
: The actual resource being paged.PageInfo
: Contains relative position information, which shows where in the entire result set the current page is located. ThePageInfo
type is the same for everyConnection
type.
RecordQuery Type
The RecordQuery
type schema for Account
is as follows.
As shown in the schema, Account
gets a corresponding AccountConnection
and AccountEdge
type constructed. The Connection
type is the entry point to the result set. It ties together the elements of the result set (the edges) with information on the relative position of the returned edges to all possible results. Relative position information is kept under the PageInfo
type. In addition, the total number of records that result from the applied filter can be accessed via the totalCount
field.
The scope
argument is 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. Child Relationship Relay Record Connections don’t have a scope argument, as child relationships can’t be filtered by a scope.
Here's an example query for accounts with cursors.
The query returns the account IDs and names with cursor information.
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 Account
, or MyCustomObject__c
is mapped to MyCustomObject__c
. All object types implement the Record
interface, which has a standard set of fields believed to be useful for most applications.
An object can map to three categories of fields:
- Salesforce object fields
- Parent Relationships
- Child Relationships
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 toLabel()
or format()
function calls the field type supports.
Currently, no field type supports both format()
and toLabel()
, and so there’s no ambiguity on which value is used for the displayValue
field.
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
LatitudeValue
object 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
LongitudeValue
object type is used. -
If the field type is TextArea, and the fields extra type info has the rich text flag, then the
RichTextAreaValue
object type is used. -
If the field type is TextArea, and the fields length value is greater than 255, the
LongTextAreaValue
object 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.
Parent Relationships
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 Contact
and Account
participate in the schema, so an Account field (relationship name) of type Account
(sObject name) is present on type Contact
.
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 the Task object. Task isn’t on the UI API Supported object list, 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.
Child Relationships
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 ContactConnection
.
The arguments where
and 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 scope
argument.