| AVAILABLE API VERSION |
|---|
| API v56.0 and later |
In Field Operators and Boolean Operators, we discussed how fields map to the filter type and how to combine filters with the AND, OR, and NOT functions. The sObject is also added to the filter type for each parent relationship.
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, and other objects.
Child-to-Parent Relationships
Child-to-parent relationships can be many-to-one, just like multiple child contacts can be on a parent account.
query {
uiapi {
query {
Contact (where: { Account: {
Industry: { eq : "media" } } } ) {
edges {
node {
Id
Name { value }
Account {
Name { value }
}
}
}
}
}
}
}
The previous query is similar to this SOQL statement.
SELECT Id, Name, Account.Name
FROM Contact
WHERE Account.Industry = 'media'
For some objects that can have a parent relationship with the same object, you can query the parent relationship using the Parent field. For example, an account can have a parent account and a campaign can have a parent campaign.
query AccountWithNameAndParent {
uiapi {
query {
Account(where: { Name: { like: "Express%" } }) {
edges {
node {
Id
Name {
value
}
Parent {
Id
Name {
value
}
}
}
}
}
}
}
}
Accounts without parent account records are also returned. The previous query returns this example response.
{
"data": {
"uiapi": {
"query": {
"Account": {
"edges": [
{
"node": {
"Id": "001RM000005ZdMLYA0",
"Name": {
"value": "Express Logistics",
"displayValue": null
},
"Parent": {
"Id": "001RM000005Zcl7YAC",
"Name": {
"value": "Express Logistics and Transport"
}
}
}
},
{
"node": {
"Id": "001RM000005Zcl7YAC",
"Name": {
"value": "Express Logistics and Transport",
"displayValue": null
},
"Parent": null
}
}
]
}
}
}
},
"errors": []
}
Here’s a query that returns cases with their parent accounts. Cases without parent accounts are also returned by the query.
query CasesWithParent {
uiapi {
query {
Case {
edges {
node {
Subject {
value
}
Parent {
Id
Account {
Name {
value
}
}
}
}
}
}
}
}
}
You can filter records to return only those accounts without a null Parent Id value.
query {
uiapi {
query {
Account (where: { Parent: { Id: { ne: null }}}) {
edges {
node {
Name { value }
Parent {
Name { value }
}
}
}
}
}
}
}
The previous query is similar to this SOQL statement.
SELECT Name, Parent.Name
FROM Account
WHERE Parent.Id!=null
Only accounts with parent account records are returned. The previous query returns this example response.
{
"data": {
"uiapi": {
"query": {
"Account": {
"edges": [
{
"node": {
"Name": {
"value": "United Oil & Gas Corp"
},
"Parent": {
"Name": {
"value": "United Oil & Gas, UK"
}
}
}
}
]
}
}
}
},
"errors": []
}
Parent-to-Child Relationships
Parent-to-child relationships are usually one-to-many, just like a parent account can have many child contacts. To include subqueries for standard objects, specify the plural form of the object name, which is the name of the relationship for the object. For example, by selecting from Account, you can query the children records via the Cases, Contacts, and Opportunities fields.
Let’s say you want to query cases on an account.
query {
uiapi {
query {
Account {
edges {
node {
Id
Name { value }
Cases {
edges {
node {
Subject { value }
Priority { value }
}
}
}
}
}
}
}
}
}
The previous query is similar to this SOQL statement.
SELECT Name,
(
SELECT Subject, Priority
FROM Cases
)
FROM Account
You can also query account names and the last name of contacts on each account.
query {
uiapi {
query {
Account {
edges {
node {
Name { value }
Contacts {
edges {
node {
LastName { value }
}
}
}
}
}
}
}
}
}
The previous query is similar to this SOQL statement.
SELECT Name,
(
SELECT LastName
FROM Contacts
)
FROM Account
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.
query AccountWithChildrenAccounts {
uiapi {
query {
Account(where: { Name: { like: "Express%" } }) {
edges {
node {
Id
Name {
value
}
ChildAccounts {
edges {
node {
Name {
value
}
}
}
}
}
}
}
}
}
}
To query object metadata that includes child relationships, pass in the childRelationships field.
You can also traverse the parent-to-child relationship using a reference to a different object. In this case, the CreatedBy field references the Name field on the User object.
query {
uiapi {
query {
Account {
edges {
node {
Name { value }
Notes {
edges {
node {
CreatedBy {
Name {
value
}
}
}
}
}
}
}
}
}
}
}
The previous query is similar to this SOQL statement.
SELECT Name,
(
SELECT CreatedBy.Name
FROM Notes
)
FROM Account
A query and its subqueries can include the where argument. The argument can filter on a supported object in the current scope via parent relationships.
For example, you can query accounts in a given industry and the last name of every contact whose created by first name is 'Marc'.
query {
uiapi {
query {
Account ( where: { Industry: { eq: "Technology"}} ) {
edges {
node {
Name { value }
Contacts (where: { CreatedBy: { FirstName: { eq : "Marc" } } } ) {
edges {
node {
LastName { value }
}
}
}
}
}
}
}
}
}
The previous query is similar to this SOQL statement.
SELECT Name,
(
SELECT LastName
FROM Contacts
WHERE CreatedBy.FirstName = 'Marc')
FROM Account WHERE Industry = 'Technology'
Lookup Relationships
With a lookup relationship, you can retrieve field information on a child or parent object. For example, you can query accounts and their associated contact names.
query AccountWithContacts {
uiapi {
query {
Account(where: { Name: { like: "Edge%" } }) {
edges {
node {
Name {
value
}
Contacts {
edges {
node {
Name {
value
}
}
}
}
}
}
}
}
}
}
Accounts without child contact records are also returned. The previous query returns this example response.
{
"data": {
"uiapi": {
"query": {
"Account": {
"edges": [
{
"node": {
"Name": {
"value": "Edge Engineering"
},
"Contacts": {
"edges": []
}
}
},
{
"node": {
"Name": {
"value": "Edge Communications",
"displayValue": null
},
"Contacts": {
"edges": [
{
"node": {
"Name": {
"value": "Sean Forbes"
}
}
},
{
"node": {
"Name": {
"value": "Rose Gonzalez"
}
}
}
]
}
}
}
]
}
}
}
},
"errors": []
}
You can also use the orderBy clause to order your child records in ascending or descending order.
query AccountsWithContactsOrderBy {
uiapi {
query {
Account (where: {Name: { eq: "Alpha Dynamics"}}) {
edges {
node {
Name {
value
}
Contacts(orderBy: {
Name: {order: ASC }
}) {
edges {
node {
Name {
value
}
}
}
}
}
cursor
}
}
}
}
}
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.
{
"data": {
"uiapi": {
"query": {
"Account": {
"edges": [
{
"node": {
"Name": {
"value": "Alpha Dynamics"
},
"Contacts": {
"edges": [
{
"node": {
"Name": {
"value": "Amy Taylor"
}
}
},
{
"node": {
"Name": {
"value": "Caroline Kingsley"
}
}
},
{
"node": {
"Name": {
"value": "Jennifer Wu"
}
}
}
]
}
},
"cursor": "djE6MA=="
}
]
}
}
}
},
"errors": []
}
Lookup Relationships with null Values
With an orderBy argument, records are returned even if the reference field has a null value.
For example, any case records with a null AccountId field are also returned.
query {
uiapi {
query {
Case (orderBy: { Account: { Name: { order: ASC } } } ) {
edges {
node {
Id
CaseNumber { value }
AccountId { value }
Account {
Name { value }
}
}
}
}
}
}
}
The previous query is similar to this SOQL statement.
SELECT Id, CaseNumber, Account.Id, Account.Name
FROM Case
ORDER BY Account.Name
With a where argument that uses the or boolean operator, records are returned even if the reference field value in a record is null.
For example, if a contact with a specific LastName has a null AccountId field and another contact with a different last name and specific parent account name, the query returns both contacts.
query {
uiapi {
query {
Contact (where: {
or: [
{ LastName: { eq: "Young" } },
{ Account : { Name: { eq: "Edge Communications" } } }
]
}) {
edges {
node {
Id
FirstName { value }
}
}
}
}
}
}
The previous query is similar to this SOQL statement.
SELECT Id, FirstName
FROM Contact
WHERE LastName = 'Young' or Account.Name = 'Edge Communications'
With a where argument that checks for a value in a parent field, the record is returned even if the parent value is null.
query {
uiapi {
query {
Case (where: { Contact: { LastName: { eq: null } } } ) {
edges {
node {
Id
Description { value }
Priority { value }
}
}
}
}
}
}
The previous query is similar to this SOQL statement.
SELECT Id, Description, Priority
FROM Case
WHERE Contact.LastName = null
See Also
SOQL and SOSL Reference: Understanding Relationship Fields and Polymorphic Fields