--- schema_version: "1" id: 866ce0bc2aade3008275ea81cb453a2cd3c8a44af9aa053b0977983d4789b7d7 title: Query Objects collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/graphql-api/graphql/guides/query/query-record-objects.md canonical_url: https://developer.salesforce.com/docs/platform/graphql/guide/query-record-objects.html source_site: developer.salesforce.com content_type: documentation content_hash: 3bc85bd93e0190fc5923519d6d39e0a4463b14cb7c88225d12e602de0f9c8bf1 products: - GraphQL API --- # Query Objects | AVAILABLE API VERSION | | ------------------------------------------------ | | API v56.0 and later | | Compound fields available in API v59.0 and later | | Optional fields available in API v65.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](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm) are available for querying. ## Object Access Schema The context user’s [object-level and field-level permissions](https://developer.salesforce.com/docs/atlas.en-us.securityImplGuide.meta/securityImplGuide/security_data_access.htm) control access to supported objects and fields on those objects. An object or field is accessible if the user has the correct permissions, and the object is either on the supported object list or is a custom object. Starting in API v68.0, admins can control unauthenticated guest user access to GraphQL from Setup. Unauthenticated guest user access is turned off by default in new orgs. To update guest user access, from Setup, in the Quick Find box, enter **API Access Controls** and select it, and then update guest user access. In orgs with guest user access, GraphQL API honors the same object-level and field-level permissions that guest users have in the org. In orgs with guest user access turned off, guest users can’t access the GraphQL endpoint and receive errors when making requests. For more information about guest user access, see [Securely Share Your Exerience Cloud Sites with Guest Users](https://help.salesforce.com/s/articleView?id=platform.networks_secure_community.htm&type=5). To construct queries that succeed even if the context user doesn’t have access to a field, use [optional fields](#optional-fields). ### RecordQuery Type The `RecordQuery` type has one field for each object type accessible to the user. Only `Account` is shown here for brevity. ``` type RecordQuery { Account( # request the "Account" field to query "Account" objects after: String first: Int orderBy: Account_OrderBy scope: ACCOUNT_SCOPE updateMRU: Boolean upperBound: Int where: Account_Filter ): AccountConnection } ``` The `RecordQuery` type contains these fields. - `after` - Returns the results after the given cursor. See [Paginate Results](https://developer.salesforce.com/docs/platform/graphql/paginate.md). - `first` - Returns the first n results. See [Paginate Results](https://developer.salesforce.com/docs/platform/graphql/paginate.md). - `orderBy` - Orders the query using a specified field. See [Order Results](https://developer.salesforce.com/docs/platform/graphql/order.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. Relay Record Connections don’t have a `scope` argument, as child relationships can’t be filtered by a scope. - `updateMRU` - If set to `true`, updates the `LastViewedDate` field on the records that your query returns. Results for queries with the `updateMRU` field are the same as those without the field. To see the updated last viewed dates, make another query that includes the `LastViewedDate` field. The `updateMRU` field is available in API v66.0 and later. - `upperBound` - Specifies the number of records by which to limit the query. Allows pagination up to `upperBound` number of records. Valid values are 200 to 2000. - `where` - Filters the query with an argument. See [Field Operators](https://developer.salesforce.com/docs/platform/graphql/filter/filter-fields.md). ### RecordConnection Type The `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 about the relative position of the returned edges to all possible results. See [Paginate Results](https://developer.salesforce.com/docs/platform/graphql/paginate.md). ``` type AccountConnection { edges: [AccountEdge] pageInfo: PageInfo! totalCount: Int! pageResultCount: Int! } ``` The `RecordConnection` type contains these fields. - `edges` - A list of RecordEdge types. - `pageInfo` - Information about the relative location in the result set. - `totalCount` - The number of records that are queried. - `pageResultCount` - The number of records in the page of results. Available in API v60.0 and later. ### RecordEdge Type The `RecordEdge` type, represented by `AccountEdge` here, ties together the record and its cursor. ``` type AccountEdge { cursor: String! node: Account } ``` The `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. For supported sObjects that are added before API v60.0, the node type name and sObject type name are the same. To avoid name collisions, supported sObjects that are added in API v60.0 and later have a node type name with a `_Record` suffix. For example, `FeedItem` is added in API v60.0 and its node type name is `FeedItem_Record`. ### PageInfo Type The `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 `Connection` type. ``` type PageInfo { hasNextPage: Boolean hasPreviousPage: Boolean startCursor: String endCursor: String } ``` The `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 **tip:** For more information about pagination, see [Paginate Results](https://developer.salesforce.com/docs/platform/graphql/paginate.md). ## Mapping sObjects to GraphQL Objects Each supported sObject type the user has access to maps to a corresponding GraphQL object type. For supported sObjects that are added before API v60.0, the sObject type and the corresponding GraphQL object type have the same name. That is, `Account` maps to a GraphQL object type named `Account`, or `MyCustomObject__c` maps to `MyCustomObject__c`. To avoid name collisions, supported sObjects that are added in API v60.0 and later map to a GraphQL object type name with a `_Record` suffix. For example, `FeedItem` is added in API v60.0 and maps to a GraphQL object type named `FeedItem_Record`. All object types implement the `Record` interface, which has a standard set of fields that are useful for most applications. **tip:** For a complete list of fields on each object type, we recommend that you review the schema documentation using the [Altair GraphQL client](https://developer.salesforce.com/docs/platform/graphql/get-started-graphql.md). ``` interface Record { Id: ID! ApiName: String! WeakEtag: Long! DisplayValue: String LastModifiedById: IDValue LastModifiedDate: DateTimeValue SystemModStamp: DateTimeValue RecordTypeId: IDValue } ``` 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 `ApiName`, `Id` and `WeakEtag` is of the same version. This means they represent the same record at that point in time. If two records have the same `ApiName` and `Id` but different `WeakEtag`, the record with the greater `WeakEtag` is the more recent version of the record. - `DisplayValue` - The displayable value for a field. In API v60.0 and later, `DisplayValue` is also supported for polymorphic fields. Querying `DisplayValue` for multiple polymorphic fields requires additional processing time. - `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: - Salesforce object fields - [Parent Relationships](https://developer.salesforce.com/docs/platform/graphql/filter/filter-parent.md) - [Child Relationships](https://developer.salesforce.com/docs/platform/graphql/filter/filter-parent.md) ### Fields Fields on the object are either mapped to a [GraphQL Scalar](https://graphql.org/learn/schema/#scalar-types) or a "Field Value" type. The GraphQL Schema contains at least one scalar for each field type on Salesforce objects. Mapping a field into the schema uses these scalars. ``` scalar Base64; scalar Boolean; scalar Currency; scalar Date; scalar DateTime; scalar Double; scalar Email; scalar EncryptedString; scalar ID; scalar IdorRef; scalar Int; scalar JSON; scalar Latitude; scalar Long; scalar LongTextArea; scalar Longitude; scalar MultiPicklist; scalar Percent; scalar PhoneNumber; scalar Picklist; scalar RichTextArea; scalar String; scalar TextArea; scalar Time; scalar Url; ``` **note:** 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 `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. **note:** 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: ``` type PicklistValue { value: Picklist # the raw value of the field on the object label: String # execute a SOQL toLabel() call displayValue: String # backed by the toLabel() call } type CurrencyValue { value: Currency # the raw value of the field on the object format: String # execute a SOQL format() call displayValue: String # backed by the format() call } ``` When mapping a Salesforce object field into the schema, the field maps to either a field value type or the scalar directly. This 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. For example, fields of type Picklist use the `PicklistValue` type, and fields of type Currency use the `CurrencyValue` type. ## Optional Fields Use the `@optional` field directive for successful query execution even if some fields are inaccessible to the context user. Mark fields, including parent and child relationship fields, as optional anywhere in your query. If the context user has access to the optional field, the query returns all the data. If the context user doesn’t have access to the optional field, the query succeeds but doesn’t return the optional field or any subfields. Arguments can’t take the optional directive, but fields that take arguments can. If an optional field takes an argument that is set to a variable, the context user must also have access to the variable type for the query to succeed. ## Compound Fields 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 `Account_BillingAddress_CompoundField` type: ``` type Account { BillingAddress: BillingAddress # `Account_BillingAddress_CompoundField type Location__c: Location__c # Account_Location__c_CompoundField type } ``` An address compound field comprises several constituent fields, like `BillingCity` and `BillingCountry`. ``` type BillingAddress { BillingCity: StringValue BillingCountry: StringValue BillingGeocodeAccuracy: PicklistValue BillingLatitude: LatitudeValue BillingLongitude: LongitudeValue BillingPostalCode: StringValue BillingState: StringValue BillingStreet TextAreaValue } ``` A [geolocation compound field](https://developer.salesforce.com/docs/platform/graphql/filter/filter-location.md) includes the `FieldName__Latitude__s` and `FieldName__Longitude__s` fields. ``` type Account_Location__c_CompoundField { Location__Latitude__s: DoubleValue Location__Longitude__s DoubleValue } ``` 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 `where` argument. - Use the constituent fields when working with aggregate queries. This example queries accounts with its billing address fields. ``` query AccountsWithBillingAddress{ uiapi { query { Account { edges { node { Name { value } BillingAddress { BillingCity { value displayValue label } BillingCountry { value displayValue label } } } } } } } } ``` **note:** Compound fields follow the limitations described at [Object Reference for the Salesforce Platform](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/compound_fields.htm). ## 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 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. ``` type Account { LastModifiedBy: User # lastModifiedBy is non-polymorphic LastModifiedById: IDValue # The ID field of the parent relationship is included as well } # the 'LastModifiedBy' field on 'Account' points at the 'User' object type User { ... } ``` If the relationship is polymorphic, then the field’s name is still the relationship name, but the field type is a Union. The unions type name follows the pattern `_`. 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. ``` type SocialPost { Who: SocialPost_Who # the polymorphic relationship becomes a field that has a Union type WhoId: IDValue # The ID field of the parent relationship is included } union SocialPost_Who = Account | Contact | Lead # the union has one possible type for each concrete type that participates in the polymorphic relationship ``` ## 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](https://relay.dev/graphql/connections.htm) 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`. ``` type Account { Contacts( # the object will have a field for each child relationship first: Int after: String orderBy: Contact_OrderBy where: Contact_Filter ): ContactConnection # the field type will be a Relay Connection for the child object type } ``` Construct the arguments `where` and `orderBy` using the rules outlined in [Filtering](https://developer.salesforce.com/docs/platform/graphql/filter/filter.md) and [Ordering](https://developer.salesforce.com/docs/platform/graphql/order.md), respectively. Scopes can’t be applied to querying child relationships, and as a result the field doesn’t have a `scope` argument. ## See Also [Relationship Filters](https://developer.salesforce.com/docs/platform/graphql/filter/filter-parent.md) [Polymorphic Relationship Filters](https://developer.salesforce.com/docs/platform/graphql/filter/filter-polymorphic.md)