What are SOQL Relationship Queries?<\/h2>\n\n\n\n
SOQL Relationship Queries read fields from related objects in a single query. There are two directions. Child-to-parent queries read fields from a parent, such as the course of an enrolment. Parent-to-child queries read a list of children, such as all enrolments of a course.<\/p>\n\n\n\n
Think of a school register. From a student’s row, you can read the class teacher’s name, which is child to parent. From the class page, you can read every student in the class, which is parent to child. Both views use the same link between student and class.<\/p>\n\n\n\n
Why SOQL Relationship Queries Matter<\/h2>\n\n\n\n
Every extra query uses one of your 100 allowed queries. SOQL Relationship Queries reduce that count and keep code simple. Here is how they help at Bright Path Tutors.<\/p>\n\n\n\n
- \n
- First, the enrolment email needs the course name and start date.<\/li>\n\n
- Also, the trainer dashboard lists each course with its active students.<\/li>\n\n
- Next, a class must find courses that have no enrolments yet.<\/li>\n\n
- A report shows each enrolment with the student’s account name.<\/li>\n\n
- Finally, triggers must read parent data without a query per record.<\/li>\n<\/ul>\n\n\n\n
So one well-written query often replaces two or three simple ones.<\/p>\n\n\n\n
How SOQL Relationship Queries Work<\/h2>\n\n\n\n
SOQL Relationship Queries use relationship names. First, you find the relationship name on the lookup or master-detail field. Next, for child-to-parent, you use dot notation, such as
Course__r.Name<\/code>. Then, for parent-to-child, you write a subquery in brackets using the child relationship name, such asEnrolments__r<\/code>. Finally, Apex returns parent records with their related fields or child lists attached.<\/p>\n\n\n\n![\"SOQL](\"https:\/\/swapnilzambare.com\/blog\/wp-content\/uploads\/2026\/11\/soql-relationship-queries-parent-child-diagram-1-1024x640.png\")
How SOQL follows relationships in both directions.<\/figcaption><\/figure>\n\n\n\n Child-to-Parent with Dot Notation<\/h3>\n\n\n\n
On a custom lookup field named
Course__c<\/code>, the relationship name isCourse__r<\/code>. SoCourse__r.Name<\/code> reads the parent course name. For standard fields, you drop the suffix, such asAccount.Name<\/code> on Contact. You can go up to five levels, such asCourse__r.Trainer__r.Name<\/code>.<\/p>\n\n\n\nParent-to-Child with Subqueries<\/h3>\n\n\n\n
A subquery sits inside the SELECT list, in brackets. It uses the child relationship name, which is usually plural, such as
Enrolments__r<\/code> orContacts<\/code>. Each parent record then carries a list of its children.<\/p>\n\n\n\nFinding Relationship Names<\/h3>\n\n\n\n
Open Object Manager, then the child object, then the lookup field. The field details show the Child Relationship Name, such as “Enrolments”. In SOQL, custom names add
__r<\/code>, so it becomesEnrolments__r<\/code>.<\/p>\n\n\n\nSemi-Joins and Anti-Joins<\/h3>\n\n\n\n
A semi-join filters parents by their children, such as
WHERE Id IN (SELECT Course__c FROM Enrolment__c)<\/code>. An anti-join usesNOT IN<\/code> to find parents with no matching children.<\/p>\n\n\n\nRelationship Names at a Glance<\/h2>\n\n\n\n
The table below shows how names change between fields and queries.<\/p>\n\n\n\n
Field or relationship<\/th> API name<\/th> Name in SOQL<\/th><\/tr><\/thead> Custom lookup on Enrolment<\/td> Course__c<\/td> Course__r.Name<\/td><\/tr> Lookup on Course to a user<\/td> Trainer__c<\/td> Trainer__r.Name<\/td><\/tr> Standard lookup on Contact<\/td> AccountId<\/td> Account.Name<\/td><\/tr> Custom child list on Course<\/td> Enrolments<\/td> Enrolments__r<\/td><\/tr> Standard child list on Account<\/td> Contacts<\/td> Contacts<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Child-to-Parent vs Parent-to-Child<\/h2>\n\n\n\n
The table below compares the two directions of SOQL Relationship Queries.<\/p>\n\n\n\n
Feature<\/th> Child-to-parent<\/th> Parent-to-child<\/th><\/tr><\/thead> Syntax<\/td> Dot notation, Course__r.Name<\/td> Subquery, (SELECT … FROM Enrolments__r)<\/td><\/tr> Starts from<\/td> The child object<\/td> The parent object<\/td><\/tr> Returns<\/td> One parent value per row<\/td> A list of children per row<\/td><\/tr> Depth<\/td> Up to five levels up<\/td> Usually one level down in Apex<\/td><\/tr> Example<\/td> Enrolment with course name<\/td> Course with its enrolments<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n When to use which depends on your starting point. Start from the child when you need parent details. Start from the parent when you need its list of children.<\/p>\n\n\n\n
![\"SOQL](\"https:\/\/swapnilzambare.com\/blog\/wp-content\/uploads\/2026\/11\/soql-relationship-queries-parent-child-diagram-2-1024x640.png\")
Child-to-parent vs parent-to-child queries.<\/figcaption><\/figure>\n\n\n\n A Real SOQL Relationship Queries Example in Apex<\/h2>\n\n\n\n
Let’s build two queries for Bright Path Tutors. The Enrolment__c object has a lookup to Course__c and a lookup to Contact called Student__c.<\/p>\n\n\n\n
Step 1: Child-to-Parent Query<\/h3>\n\n\n\n
List<Enrolment__c> enrolments = [\n SELECT Id, Status__c,\n Student__r.Name,\n Course__r.Name, Course__r.Start_Date__c,\n Course__r.Trainer__r.Name\n FROM Enrolment__c\n WHERE Status__c = 'Active'\n LIMIT 5\n];\n\nfor (Enrolment__c e : enrolments) {\n System.debug(e.Student__r.Name + ' joined ' + e.Course__r.Name\n + ' with trainer ' + e.Course__r.Trainer__r.Name);\n}<\/code><\/pre>\n\n\n\nThe query starts from Enrolment__c. Dot notation reads the student name, the course name and start date, and even the trainer name two levels up. Inside the loop, we read those fields with the same dot notation.<\/p>\n\n\n\n
Step 2: Parent-to-Child Query<\/h3>\n\n\n\n
List<Course__c> courses = [\n SELECT Id, Name,\n (SELECT Id, Student__r.Name, Status__c\n FROM Enrolments__r\n WHERE Status__c = 'Active'\n ORDER BY CreatedDate)\n FROM Course__c\n WHERE Is_Online__c = true\n];\n\nfor (Course__c c : courses) {\n System.debug(c.Name + ' has ' + c.Enrolments__r.size() + ' active students');\n}<\/code><\/pre>\n\n\n\nThe subquery returns each course’s active enrolments. In Apex,
c.Enrolments__r<\/code> is a list, sosize()<\/code> counts the students. The subquery can have its own WHERE and ORDER BY.<\/p>\n\n\n\nStep 3: Read the Output<\/h3>\n\n\n\n
Here is an example of the debug log for Step 2.<\/p>\n\n\n\n
USER_DEBUG [12]|DEBUG|Apex Basics has 18 active students\nUSER_DEBUG [12]|DEBUG|SOQL Basics has 0 active students\nUSER_DEBUG [12]|DEBUG|LWC Basics has 7 active students<\/code><\/pre>\n\n\n\nStep 4: Find Courses with No Enrolments<\/h3>\n\n\n\n
List<Course__c> emptyCourses = [\n SELECT Id, Name\n FROM Course__c\n WHERE Id NOT IN (SELECT Course__c FROM Enrolment__c)\n];\nSystem.debug('Courses without enrolments: ' + emptyCourses.size());<\/code><\/pre>\n\n\n\nThis anti-join is one of the most useful SOQL Relationship Queries. It returns courses that no enrolment points to. Also, it is one query, with no loops or maps needed.<\/p>\n\n\n\n
SOQL Relationship Queries and Limits<\/h2>\n\n\n\n
SOQL Relationship Queries still count as one query each. However, the rows inside subqueries count toward the 50,000 row limit. So keep subqueries filtered. Also, when a parent has very many children, loop over the child list with a for loop rather than copying it into a new list.<\/p>\n\n\n\n
Common Mistakes with SOQL Relationship Queries<\/h2>\n\n\n\n
- \n
- Using
Course__c.Name<\/code> instead ofCourse__r.Name<\/code>.<\/li>\n\n- Guessing the child relationship name instead of checking the field.<\/li>\n\n
- Reading a parent field that was not selected, which throws an error.<\/li>\n\n
- Forgetting that a parent lookup can be blank, which gives a null value.<\/li>\n\n
- Returning thousands of children in a subquery without a filter.<\/li>\n<\/ul>\n\n\n\n
Best Practices for SOQL Relationship Queries<\/h2>\n\n\n\n
- \n
- Check relationship names in Object Manager before writing queries.<\/li>\n\n
- Use child-to-parent dot notation to avoid extra queries in triggers.<\/li>\n\n
- Filter subqueries with WHERE and limit them when possible.<\/li>\n\n
- Check for null before reading parent fields from optional lookups.<\/li>\n\n
- Use semi-joins and anti-joins instead of loops that compare lists.<\/li>\n<\/ul>\n\n\n\n
Practice Task<\/h2>\n\n\n\n
Write a query on Contact that returns each student with the names of their active courses. Hint: use a subquery on the child relationship from Contact to Enrolment__c, then read
Course__r.Name<\/code> inside it.<\/p>\n\n\n\nMost Asked Interview Questions on SOQL Relationship Queries<\/h2>\n\n\n\n
SOQL Relationship Queries are among the most tested topics in interviews. Here are the 20 questions asked most, with short answers.<\/p>\n\n\n\n
Basic Questions on SOQL Relationship Queries<\/h3>\n\n\n\n
Q1: What is a relationship query?<\/strong><\/p>\n\n\n\n
It reads fields from related objects in one SOQL query, so you avoid running separate queries.<\/p>\n\n\n\n
Q2: What are the two types of relationship queries?<\/strong><\/p>\n\n\n\n
Child-to-parent, which uses dot notation, and parent-to-child, which uses a subquery.<\/p>\n\n\n\n
Q3: What does __r mean?<\/strong><\/p>\n\n\n\n
It marks a custom relationship name. For example, the field Course__c has the relationship name Course__r.<\/p>\n\n\n\n
Q4: How do you read a standard parent field?<\/strong><\/p>\n\n\n\n
Use the relationship name without a suffix. For example, Contact uses Account.Name.<\/p>\n\n\n\n
Q5: How many levels can child-to-parent queries go?<\/strong><\/p>\n\n\n\n
Up to five levels, for example Course__r.Trainer__r.Manager.Name.<\/p>\n\n\n\n
Q6: Where do you find the child relationship name?<\/strong><\/p>\n\n\n\n
On the lookup or master-detail field in Object Manager, under Child Relationship Name.<\/p>\n\n\n\n
Q7: What does a subquery return in Apex?<\/strong><\/p>\n\n\n\n
A list of child records on each parent record, such as course.Enrolments__r.<\/p>\n\n\n\n
Code and Scenario Questions on SOQL Relationship Queries<\/h3>\n\n\n\n
Q8: Write a query for accounts with their contacts.<\/strong><\/p>\n\n\n\n
For example, use SELECT Name, (SELECT LastName FROM Contacts) FROM Account.<\/p>\n\n\n\n
Q9: How do you find accounts with no contacts?<\/strong><\/p>\n\n\n\n
Use an anti-join, such as WHERE Id NOT IN (SELECT AccountId FROM Contact).<\/p>\n\n\n\n
Q10: How do you find courses with active enrolments only?<\/strong><\/p>\n\n\n\n
Use a semi-join, such as WHERE Id IN (SELECT Course__c FROM Enrolment__c WHERE Status__c = ‘Active’).<\/p>\n\n\n\n
Q11: Can a subquery have its own WHERE and ORDER BY?<\/strong><\/p>\n\n\n\n
Yes. A subquery can use WHERE, ORDER BY and LIMIT.<\/p>\n\n\n\n
Q12: What happens if a lookup is blank?<\/strong><\/p>\n\n\n\n
The parent reference is null, so reading a field on it gives null. Check for null before using it.<\/p>\n\n\n\n
Q13: How do relationship queries help in triggers?<\/strong><\/p>\n\n\n\n
They let you read parent data for all records in one query, so you avoid queries inside loops.<\/p>\n\n\n\n
Q14: Do subquery rows count toward limits?<\/strong><\/p>\n\n\n\n
Yes. Child rows count toward the 50,000 row limit, so filter subqueries.<\/p>\n\n\n\n
Advanced Questions on SOQL Relationship Queries<\/h3>\n\n\n\n
Q15: What is a polymorphic relationship?<\/strong><\/p>\n\n\n\n
It is a lookup that can point to different objects, such as WhatId on Task. You can use TYPEOF in SOQL to read fields by type.<\/p>\n\n\n\n
Q16: Can you filter parents by a child field without a semi-join?<\/strong><\/p>\n\n\n\n
No. To filter parents by children, use a semi-join. A subquery alone only returns children, it does not filter parents.<\/p>\n\n\n\n
Q17: Why might parent-to-child subqueries with many children cause problems?<\/strong><\/p>\n\n\n\n
Large child lists use heap and row limits. So filter them, or query children separately in batches.<\/p>\n\n\n\n
Q18: How do you query fields from a master-detail parent?<\/strong><\/p>\n\n\n\n
The same way as a lookup, with the relationship name and dot notation.<\/p>\n\n\n\n
Q19: What is the difference between a semi-join and a subquery in SELECT?<\/strong><\/p>\n\n\n\n
A semi-join filters parent records in the WHERE clause. A subquery in SELECT returns child records.<\/p>\n\n\n\n
Q20: How would you reduce three queries into one?<\/strong><\/p>\n\n\n\n
Use child-to-parent dot notation for parent fields and a subquery for children, so one query returns all three levels of data.<\/p>\n\n\n\n
Official Resources<\/h2>\n\n\n\n
- Using