Traversing and Querying sObject Relationships - Apex

sObject Relationships and Dot Notation

If two sObjects are related to each other via a relationship, you can get a parent sObject of an sObject using the dot notation syntax:

sObjectTypeName parentObject = objectA.RelationshipName;

You can also access the fields of the parent sObject by appending it to the relationship name:

DataType s = objectA.RelationshipName.FieldName;

Similarly, you can get the child sObjects of an sObject using the same syntax. The only difference is that you now have a collection of one or more sObject child records, while in the previous case there is only one parent record. The syntax is the following:

List<sObjectTypeName> children = objectA.ChildRelationshipName;

Querying sObject Relationships

If an sObject is related to another by a master-detail or lookup relationship, you can query the parent sObject field by specifying the relationship name and field name in your SELECT statement as follows:

SELECT RelationshipName.Field FROM sObjectName WHERE Where_Condition [...]

To fetch child sObjects, specify a nested query that retrieves all request child sObjects and their fields as follows:

SELECT field1, field1, ..., (Nested query for child sObjects) 
       FROM sObjectName WHERE Where_Condition [...]

Try It Out

This example shows how to traverse the master-detail relationship that exists between an invoice statement and a line item. It first queries the name of the parent invoice statement for a specific line item by specifying Invoice_Statement__r.Name in the query. Next, it retrieves the invoice statement sObject and its name from the returned line item sObject through this statement: li.Invoice_Statement__r.Name. Execute the following:

Line_Item__c li = [SELECT Invoice_Statement__r.Name FROM Line_Item__c LIMIT 1];
// Traverses a relationship using the dot notation. 
    
System.debug('Invoice statement name: ' + li.Invoice_Statement__r.Name);

The Invoice_Statement__r field in the SELECT statement ends with __r. This suffix indicates that this field is a relationship field. It acts like a foreign key and references the parent invoice statement of the line item queried.

The output returned looks something like:

Invoice statement name: INV-0000.

This second example demonstrates the retrieval of child sObjects. It retrieves child line items of an invoice statement using the nested query (SELECT Value__c FROM Line_Items__r). It then obtains the child line items of the invoice statement through the returned invoice statement sObject.

Invoice_Statement__c inv = [SELECT Id, Name, (SELECT Units_Sold__c FROM Line_Items__r)
             FROM Invoice_Statement__c
             WHERE Name='INV-0000'];
// Access child records. 
    
List<Line_Item__c> lis = inv.Line_Items__r;
System.debug('Number of child line items: ' + lis.size());

The nested query retrieves child records from Line_Items__r. The __r suffix in Line_Items__r indicates that this is the name of relationship. This nested query gets the child line items of the invoice statements using the master-detail relationship represented by Line_Items__r.

The sample invoice statement has one line item, so the output of this example is:

Number of child line items: 1.