GraphQL API Query Limitations

GraphQL has the same limitations as SOQL. When working with GraphQL API queries, consider the following limitations.

• Each GraphQL query can contain up to 10 subqueries.
• Each subquery counts as one request for rate limiting.
• Each subquery can return up to 2000 records within the same GraphQL query.
• By default, the first 10 records are returned. You can use pagination information to retrieve additional records.
• You can query only objects that User Interface API supports.

An object must have a parent or child relationship with another object to form a query similar to an SOQL join. Limitations for relationship queries are discussed in the next few sections.

Child-to-parent relationships follow these limits.

• A query can specify up to 55 child-to-parent relationships. A custom object allows up to 40 relationships, so you can reference all the child-to-parent relationships for a custom object in one query.
• You can specify up to five levels in a child-to-parent relationship.
• A child relationship name can't be the same as a parent relationship name within an object.

This example shows three levels of child-to-parent relationship, which is Contact.Account.Owner.FirstName.

Additionally, consider these differences between API versions.

• In API version 57.0 and earlier, you can specify up to two levels of child-to-parent relationship in a query.
• In API version 58.0 and later, you can specify up to five levels of child-to-parent relationship for standard and custom objects.

Parent-to-child relationships follow these limits.

• A query can specify up to 20 parent-to-child relationships.
• You can specify one level in a parent-to-child relationship.
• A parent relationship name can't be the same as a child relationship name within an object.

This example shows a parent-to-child relationship, which is Account.Contacts.

If you’re querying Account, the fields you select can specify only the Contact or other objects at that level. The query can’t specify a child object of Contact.

GraphQL API follows SOQL restrictions on semi-join and anti-join queries.

• You can use up to two nin and ninq operators in a where argument. A nin and ninq operator can support up to two in or nin operators.
• You can't use the ne operator with semi-joins and anti-joins. Using this operator converts a semi-join to an anti-join and vice versa. Instead, write the query in the appropriate semi-join or anti-join form.

Consider these restrictions on the where argument of a semi-join or anti-join query.

• You must use a single ID for the semi-join or anti-join query.
• The ID in the where argument that's used in the semi-join or anti-join can't use relationships.

This example uses a single ID in a semi-join to return contact names associated with accounts whose ownership is public.

The previous query is similar to this SOQL statement.

A subquery must query a field referencing the same object type as the main query. For example, use the Id field on the where argument followed by ApiName:"AccountId" in the inq operator. Using Account.Id (dot notation) instead of AccountId isn't supported.

This example returns specific accounts using AccountId as the selected field in the subquery, in which the contacts' last names start with "B".

The previous query is similar to this SOQL statement.

There's no limit on the number of records matched in a subquery. By default, the first 10 records are returned. You can use the pagination information to retrieve additional records.

The selected field in a subquery must be a reference to a different object, and can't traverse relationships. In the previous example, the main query selects from accounts and the subquery selects from contacts.

You can’t query on the same object in a subquery as in the main query. Instead of selecting from the same object in the main query and subquery, you can rewrite a semi-join query using the Parent field.

The previous query is similar to this SOQL statement.

A semi-join or anti-join statement:

• Can’t be nested in another semi-join or anti-join statement
• Can’t be used in a subquery where argument.

A subquery can’t be used with:

• The or operator
• The orderBy operator

You can combine semi-join or anti-join clauses in a query using the inq or ninq functions in a where argument. However, you can use only up to two subqueries in a single semi-join or anti-join queries.

This example includes 2 semi-join filters that return accounts if they have an associated opportunity and an associated case that has its Priority field set to "High".

The previous query is similar to this SOQL statement.

Only the UI API supported objects are available in GraphQL API, with these exceptions.

UI API doesn't support the Event and Task objects, but both are available with GraphQL API.

Use Task and Event objects in:

• Record queries
• Aggregate queries
• Parent-to-child relationship queries
• Child-to-parent relationship queries
• Polymorphic field queries

Certain supported objects come with additional limitations.

The Note object has these limitations.

• You can't query the Note object in subqueries.
• You can query the Note object but you can't evaluate the body of a note, such as filtering on Note.Body by using the eq or like operator. You also can’t filter against the content of textarea fields, blobs, or S-control components in any object.

You can return the content of the body of the note like this.

The previous query is similar to this SOQL statement.

You can also return all account names and the owner ID for any notes associated with the account.

The previous query is similar to this SOQL statement.

External objects have these limitations.

• A subquery that involves external objects can fetch up to 1,000 rows of data.
• Each query can have up to 4 joins across external objects and other types of objects. Each join requires a separate round trip to the external system when executing the query. Expect longer response times for each join in a query.
• External objects don’t support the orderBy argument in relationship queries. This limit applies only when the external data is accessed via the OData 2.0 adapter for Salesforce Connect.

SOQL Limits on Objects Understanding Relationship Query Limitations