Polymorphic Relationship Filters

AVAILABLE API VERSION
API v56.0 and later
Event and Task (Beta) available in API v59.0 and later

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

Common polymorphic fields include the Owner, Who, and What fields.

To query using a polymorphic relationship, use inline fragments with the ... on Object syntax.

Owner Polymorphic Field

The Owner field represents the parent of the record. For example, a case owner can be a Group or User object.

When the parent relationship is polymorphic, an input object following the naming convention <ObjectName>_<RelationshipName>_Filters is constructed and used as the filter type for that parent relationship.

The Owner field follows the naming convention <ObjectName>_Owner, which is used as the filter type for that parent relationship.

For example, the Case object’s Owner filter has a type of Case_Owner_Filters.

1type Case {
2  Owner: Case_Owner
3}

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

1union Case_Owner = Group | User

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

1input Case_Owner_Filters {
2  Group: Group_Filter
3  Name: Name_Filter
4  User: User_Filter
5}

Let’s say you query cases that match a specified Owner.Name value. Case records correspond to owners that are either groups or users. This example queries cases where the owner’s username starts with “D” and the Owner.Type is a User object.

1query  {
2  uiapi {
3    query {
4      Case ( where: { Owner: { User: { Name: {like: "D%"} }}} ) {
5        edges {
6          node {
7            Id
8            Owner {
9              ... on User {
10                  Name { value }
11              }
12            }
13          }
14        }
15      }
16    }
17  }
18}

The previous query is similar to this SOQL statement.

1SELECT Id, Owner.Name
2FROM Case
3WHERE Owner.Name like 'D%'

In the next example, the Name field is available only when the node is of type User.

1query AccountCasesDetail {
2  uiapi {
3      query {
4        Contact ( where: { Name: { like: "Rose%" } } ) {
5            edges {
6                node {
7                    Id
8                    Name {
9                        value
10                        displayValue
11                    }
12                    Cases {
13                        edges {
14                            node {
15                                Subject {
16                                    value
17                                }
18                                Owner {
19                                    ... on User {
20                                        Name {
21                                            value
22                                        }
23                                    }
24                                }
25                                CreatedDate {
26                                    displayValue
27                                }
28                                IsEscalated  {
29                                    value
30                                }
31                            }
32                        }
33                    }
34                }
35            }
36          }
37      }
38  }
39}

Who Polymorphic Field

The Who field represents the person associated with the record. Some objects, like Event, Task, ContactRequest, and SocialPost, have a Who field. For more information, see the Object Reference for the Salesforce Platform.

Not all objects that have a Who field are available in GraphQL API via UI API.

Note

For example, the ContactRequest object’s Who filter has a type of ContactRequest_Who_Filters. This input object has one input object field for each concrete type that participates in the polymorphic relationship.

1type ContactRequest {
2  who: ContactRequest_Who
3}

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

1union ContactRequest_Who = Contact | Lead | User

1input ContactRequest_Filter {
2  who: ContactRequest_Who_Filters # the filter object contains another filter object constructed for the polymorphic type
3}

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

1input ContactRequest_Who_Filters {
2  Contact: Contact_Filter
3  Lead:    Lead_Filter
4  Name:    Name_Filter
5  User:    User_Filter
6}

ContactRequest records have a Who field that can reference a contact, lead, name, or user. This example query applies to ContactRequest records whose owners can be either a Group or User object. It filters the records based on the User object and select records where the Who.Type is a Contact object.

1query  {
2  uiapi {
3    query {
4      ContactRequest ( where: { Owner: { User: { FirstName: {like: "D%"} }}} ) {
5        edges {
6          node {
7            Id
8            Who {
9              ... on Contact {
10                  Name { value }
11              }
12            }
13          }
14        }
15      }
16    }
17  }
18}

The previous query is similar to this SOQL statement.

1SELECT Id, Who.FirstName, Who.LastName
2FROM ContactRequest
3WHERE Owner.FirstName LIKE 'D%'

What Polymorphic Field

The What field represents non-person objects that are associated with the record. Some objects, like Event and ContactRequest, have a What field. For more information, see the Object Reference for the Salesforce Platform.

Not all objects that have a Who field are available in GraphQL API via UI API.

Note

For example, the ContactRequest object’s What filter has a type of ContactRequest_What_Filters. This input object has one input object field for each concrete type that participates in the polymorphic relationship.

1type ContactRequest {
2  who: ContactRequest_What
3}

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

1union ContactRequest_What = Account | Case | Opportunity

1input ContactRequest_Filter {
2  What: ContactRequest_What_Filters # the filter object contains another filter object constructed for the polymorphic type
3}

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

1input ContactRequest_What_Filters {
2  Account:     Account_Filter
3  Case:        Case_Filter
4  Name:        Name_Filter
5  Opportunity: Opportunity_Filter
6}

ContactRequest records have a What field that can reference an account, case, name, or opportunity. This example query applies to ContactRequest records whose What field is Account. It returns ContactRequest records with the Name field, the What.Name field where the What.Type is Account.

1query  {
2  uiapi {
3    query {
4      ContactRequest {
5        edges {
6          node {
7            Id
8            Name { value }
9            What {
10              ... on Account {
11                Name { value }
12              }
13            }
14          }
15        }
16      }
17    }
18  }
19}

The previous query is similar to this SOQL statement.

1SELECT Id, Name, What.Name
2FROM ContactRequest

Filter Polymorphic Fields with Boolean Operators

You can filter the result set by the value of the underlying polymorphic types data. Each filter is combined with an and operator to assert the polymorphic relationship is of the filter type.

1query  {
2  uiapi {
3    query {
4      ContactRequest ( where: {
5        and: [{
6          Who: { Contact: { FirstName: {
7            like: "R%" } } },
8          Who: {Contact: { LastName: {
9            like: "G%" } } }
10        }]
11       }) {
12        edges {
13          node {
14            Id
15            Name { value }
16          }
17        }
18      }
19    }
20  }
21}

The query is similar to this SOQL statement.

1SELECT Id, Name
2FROM ContactRequest
3WHERE Who.FirstName LIKE 'R%' AND Who.LastName LIKE 'G%'

You can work with multiple fields on a polymorphic filter with an or operator. This example returns ContactRequest records with the Id, Name, and What.Name fields where the What.Type is Account. It filters the records where the What.Name is “Salesforce” or the Who.FirstName contact names start with “R”.

1query  {
2  uiapi {
3    query {
4      ContactRequest ( where: {
5        or: [{
6          What: { Account: { Name: {
7            eq: "Salesforce" } } },
8          Who: { Contact: { FirstName: {
9            like: "R%" } } }
10        }]
11       }) {
12        edges {
13          node {
14            Id
15            Name { value }
16            What {
17              ... on Account {
18                Name { value }
19              }
20            }
21          }
22        }
23      }
24    }
25  }
26}

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

1SELECT Id, Name, What.Name
2FROM ContactRequest
3WHERE What.Name = 'Salesforce' OR Who.FirstName LIKE 'R%'

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.

Note

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

Non-Polymorphic Relationships

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

1type Account {
2  CreatedBy: User
3}

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

1input Account_Filter {
2  CreatedBy: User_Filter
3}

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

1query  {
2  uiapi {
3    query {
4      Account ( where: { CreatedBy: { FirstName: { like: "Misato" } } } ) {
5        edges {
6          node {
7            Id
8            Name { value }
9          }
10        }
11      }
12    }
13  }
14}

This query is similar to this SOQL statement.

1SELECT Id, Name
2FROM Account
3WHERE CreatedBy.FirstName='Misato'