Relationship Filters

In the earlier sections of Filter Results, we’ve discussed how fields are mapped into the filter type and how to combine filters with the AND, OR, and NOT functions. In addition, each parent relationship the sObject is added to the filter type as well.

Objects can have a child-to-parent relationship or a parent-to-child relationship. For example, the Contact object has a child-to-parent relationship to the Account object. An Account has parent-to-child relationships to Assets, Cases, and Contacts among other objects.

You can query a record that has a parent relationship to another object using the Parent field.

Accounts without parent account records are also returned. The previous query returns this example response.

Here's a query that returns cases with their parent accounts. Cases without parent accounts are also returned by the query.

Some objects have children relationships to the same object. For example, use the ChildAccounts field to query children accounts on account records. Accounts without children accounts are also returned.

To query object metadata that includes child relationships, pass in the childRelationships field.

A lookup relationship enables you to retrieve field information on a child or parent object. For example, you can query accounts and their associated contact names.

Accounts without child contact records are also returned. The previous query returns this example response.

You can also use the orderBy clause to order your child records in ascending or descending order.

The child records are paginated and include cursor and pagination information. By default, the first 10 children records are returned. To specify the number of children records to return, use the first argument on the child object.

A polymorphic relationship is one where an object can be one of several object types. For example, an event can have a a polymorphic relationship to an account, campaign, or opportunity via the Related To field. Contrastingly, a contact has a non-polymorphic relationship to an account via the Account Name field.

To query using a polymorphic relationship, use inline fragments. In this example, the Name field is available only when the node is of type User.

If the parent relationship is polymorphic, then an input object following the naming convention <ObjectName>_<RelationshipName>_Filters is constructed and used as the filter type for that parent relationship. For example, the SocialPost object's Who filter has a type of SocialPost_Who_Filters. This input object has one input object field for each concrete type that participates in the polymorphic relationship.

The union has one possible type for each concrete type that participates in the polymorphic relationship.

The input object type has one input object field of the filter type for each object that participates in the polymorphic relationship.

With this structure, it's possible to filter the result set by the value of the underlying polymorphic types data. Each filter is combined with an AND condition to assert the polymorphic relationship is of the filter type.

The query is similar to the following SOQL statement.

You can work with multiple fields on a polymorphic filter.

The previous query is similar to the following SOQL statement where the individual clauses are joined with OR, allowing selective filtering based on the underlying type of the polymorphic relationship.

Although objects with an OwnerId, WhatId or WhoId field have polymorphic parent relationships, GraphQL API includes as possible types only those objects that are available via the User Interface API.

If the parent relationship is non-polymorphic, then the corresponding filter type for that object is used.

Consider an account that as a parent relationship CreatedBy that points to the User object.

As the relationship is non-polymorphic, the filter has a field with the same name of the parent relationship with the corresponding filter type.

To find all accounts created by a particular user, we can construct a where argument as follows.

This query is similar to the following SOQL statement.

When querying for records using a polymorphic parent relationship, you can order and filter by the Name object. Using the Name object enables you to filter and order using the fields supported on the Name object. If you ask for a filter on the relationshipName.FirstName field and the underlying object is a Contact, then the filter is applied to that object. Otherwise, if the object is of a different type that does not have the FirstName field, the filter evaluates to false and no record is returned.

Only the Name object is currently supported for ordering and filtering in a polymorphic parent relationship. Other object types can result in a runtime error and might not be available in a future release.

For example, the Who relationship field in a SocialPost object can reference an Account, Contact, or Lead. Let's say you want to find the underlying record with a specific email field value using the Who relationship field.

Similar to an ORDER BY or WHERE clause, the above query is similar to the following SOQL.

SOQL and SOSL Reference: Understanding Relationship Fields and Polymorphic Fields

Paginate Results