| 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 can be many-to-one, just like multiple child contacts can be on a parent account.
1query {
2 uiapi {
3 query {
4 Contact (where: { Account: {
5 Industry: { eq : "media" } } } ) {
6 edges {
7 node {
8 Id
9 Name { value }
10 Account {
11 Name { value }
12 }
13 }
14 }
15 }
16 }
17 }
18}The previous query is similar to this SOQL statement.
1SELECT Id, Name, Account.Name
2FROM Contact
3WHERE 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.
1query AccountWithNameAndParent {
2 uiapi {
3 query {
4 Account(where: { Name: { like: "Express%" } }) {
5 edges {
6 node {
7 Id
8 Name {
9 value
10 }
11 Parent {
12 Id
13 Name {
14 value
15 }
16 }
17 }
18 }
19 }
20 }
21 }
22}Accounts without parent account records are also returned. The previous query returns this example response.
1{
2 "data": {
3 "uiapi": {
4 "query": {
5 "Account": {
6 "edges": [
7 {
8 "node": {
9 "Id": "001RM000005ZdMLYA0",
10 "Name": {
11 "value": "Express Logistics",
12 "displayValue": null
13 },
14 "Parent": {
15 "Id": "001RM000005Zcl7YAC",
16 "Name": {
17 "value": "Express Logistics and Transport"
18 }
19 }
20 }
21 },
22 {
23 "node": {
24 "Id": "001RM000005Zcl7YAC",
25 "Name": {
26 "value": "Express Logistics and Transport",
27 "displayValue": null
28 },
29 "Parent": null
30 }
31 }
32 ]
33 }
34 }
35 }
36 },
37 "errors": []
38}Here’s a query that returns cases with their parent accounts. Cases without parent accounts are also returned by the query.
1query CasesWithParent {
2 uiapi {
3 query {
4 Case {
5 edges {
6 node {
7 Subject {
8 value
9 }
10 Parent {
11 Id
12 Account {
13 Name {
14 value
15 }
16 }
17 }
18 }
19 }
20 }
21 }
22 }
23}You can filter records to return only those accounts without a null Parent Id value.
1query {
2 uiapi {
3 query {
4 Account (where: { Parent: { Id: { ne: null }}}) {
5 edges {
6 node {
7 Name { value }
8 Parent {
9 Name { value }
10 }
11 }
12 }
13 }
14 }
15 }
16}The previous query is similar to this SOQL statement.
1SELECT Name, Parent.Name
2FROM Account
3WHERE Parent.Id!=nullOnly accounts with parent account records are returned. The previous query returns this example response.
1{
2 "data": {
3 "uiapi": {
4 "query": {
5 "Account": {
6 "edges": [
7 {
8 "node": {
9 "Name": {
10 "value": "United Oil & Gas Corp"
11 },
12 "Parent": {
13 "Name": {
14 "value": "United Oil & Gas, UK"
15 }
16 }
17 }
18 }
19 ]
20 }
21 }
22 }
23 },
24 "errors": []
25}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.
1query {
2 uiapi {
3 query {
4 Account {
5 edges {
6 node {
7 Id
8 Name { value }
9 Cases {
10 edges {
11 node {
12 Subject { value }
13 Priority { value }
14 }
15 }
16 }
17 }
18 }
19 }
20 }
21 }
22}The previous query is similar to this SOQL statement.
1SELECT Name,
2 (
3 SELECT Subject, Priority
4 FROM Cases
5 )
6FROM AccountYou can also query account names and the last name of contacts on each account.
1query {
2 uiapi {
3 query {
4 Account {
5 edges {
6 node {
7 Name { value }
8 Contacts {
9 edges {
10 node {
11 LastName { value }
12 }
13 }
14 }
15 }
16 }
17 }
18 }
19 }
20}The previous query is similar to this SOQL statement.
1SELECT Name,
2 (
3 SELECT LastName
4 FROM Contacts
5 )
6FROM AccountSome 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.
1query AccountWithChildrenAccounts {
2 uiapi {
3 query {
4 Account(where: { Name: { like: "Express%" } }) {
5 edges {
6 node {
7 Id
8 Name {
9 value
10 }
11 ChildAccounts {
12 edges {
13 node {
14 Name {
15 value
16 }
17 }
18 }
19 }
20 }
21 }
22 }
23 }
24 }
25}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.
1query {
2 uiapi {
3 query {
4 Account {
5 edges {
6 node {
7 Name { value }
8 Notes {
9 edges {
10 node {
11 CreatedBy {
12 Name {
13 value
14 }
15 }
16 }
17 }
18 }
19 }
20 }
21 }
22 }
23 }
24}The previous query is similar to this SOQL statement.
1SELECT Name,
2 (
3 SELECT CreatedBy.Name
4 FROM Notes
5 )
6FROM AccountA 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’.
1query {
2 uiapi {
3 query {
4 Account ( where: { Industry: { eq: "Technology"}} ) {
5 edges {
6 node {
7 Name { value }
8 Contacts (where: { CreatedBy: { FirstName: { eq : "Marc" } } } ) {
9 edges {
10 node {
11 LastName { value }
12 }
13 }
14 }
15 }
16 }
17 }
18 }
19 }
20}The previous query is similar to this SOQL statement.
1SELECT Name,
2 (
3 SELECT LastName
4 FROM Contacts
5 WHERE CreatedBy.FirstName = 'Marc')
6 FROM Account WHERE Industry = 'Technology'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.
1query AccountWithContacts {
2 uiapi {
3 query {
4 Account(where: { Name: { like: "Edge%" } }) {
5 edges {
6 node {
7 Name {
8 value
9 }
10 Contacts {
11 edges {
12 node {
13 Name {
14 value
15 }
16 }
17 }
18 }
19 }
20 }
21 }
22 }
23 }
24}Accounts without child contact records are also returned. The previous query returns this example response.
1{
2 "data": {
3 "uiapi": {
4 "query": {
5 "Account": {
6 "edges": [
7 {
8 "node": {
9 "Name": {
10 "value": "Edge Engineering"
11 },
12 "Contacts": {
13 "edges": []
14 }
15 }
16 },
17 {
18 "node": {
19 "Name": {
20 "value": "Edge Communications",
21 "displayValue": null
22 },
23 "Contacts": {
24 "edges": [
25 {
26 "node": {
27 "Name": {
28 "value": "Sean Forbes"
29 }
30 }
31 },
32 {
33 "node": {
34 "Name": {
35 "value": "Rose Gonzalez"
36 }
37 }
38 }
39 ]
40 }
41 }
42 }
43 ]
44 }
45 }
46 }
47 },
48 "errors": []
49}You can also use the orderBy clause to order your child records in ascending or descending order.
1query AccountsWithContactsOrderBy {
2 uiapi {
3 query {
4 Account (where: {Name: { eq: "Alpha Dynamics"}}) {
5 edges {
6 node {
7 Name {
8 value
9 }
10 Contacts(orderBy: {
11 Name: {order: ASC }
12 }) {
13 edges {
14 node {
15 Name {
16 value
17 }
18 }
19 }
20 }
21 }
22 cursor
23 }
24 }
25 }
26 }
27}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.
1{
2 "data": {
3 "uiapi": {
4 "query": {
5 "Account": {
6 "edges": [
7 {
8 "node": {
9 "Name": {
10 "value": "Alpha Dynamics"
11 },
12 "Contacts": {
13 "edges": [
14 {
15 "node": {
16 "Name": {
17 "value": "Amy Taylor"
18 }
19 }
20 },
21 {
22 "node": {
23 "Name": {
24 "value": "Caroline Kingsley"
25 }
26 }
27 },
28 {
29 "node": {
30 "Name": {
31 "value": "Jennifer Wu"
32 }
33 }
34 }
35 ]
36 }
37 },
38 "cursor": "djE6MA=="
39 }
40 ]
41 }
42 }
43 }
44 },
45 "errors": []
46}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.
1query {
2 uiapi {
3 query {
4 Case (orderBy: { Account: { Name: { order: ASC } } } ) {
5 edges {
6 node {
7 Id
8 CaseNumber { value }
9 AccountId { value }
10 Account {
11 Name { value }
12 }
13 }
14 }
15 }
16 }
17 }
18}The previous query is similar to this SOQL statement.
1SELECT Id, CaseNumber, Account.Id, Account.Name
2FROM Case
3ORDER BY Account.NameWith 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.
1query {
2 uiapi {
3 query {
4 Contact (where: {
5 or: [
6 { LastName: { eq: "Young" } },
7 { Account : { Name: { eq: "Edge Communications" } } }
8 ]
9 }) {
10 edges {
11 node {
12 Id
13 FirstName { value }
14 }
15 }
16 }
17 }
18 }
19}The previous query is similar to this SOQL statement.
1SELECT Id, FirstName
2FROM Contact
3WHERE 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.
1query {
2 uiapi {
3 query {
4 Case (where: { Contact: { LastName: { eq: null } } } ) {
5 edges {
6 node {
7 Id
8 Description { value }
9 Priority { value }
10 }
11 }
12 }
13 }
14 }
15}The previous query is similar to this SOQL statement.
1SELECT Id, Description, Priority
2FROM Case
3WHERE Contact.LastName = nullSOQL and SOSL Reference: Understanding Relationship Fields and Polymorphic Fields
j