Child Relationship
A child relationship in Salesforce is the schema link that lets a parent object reach the many child records that point at it through a lookup or master-detail field.
Definition
A child relationship in Salesforce is the schema link that lets a parent object reach the many child records that point at it through a lookup or master-detail field. The lookup field lives on the child and references one parent. The child relationship is the reverse view, the path that walks from a single parent record back to its set of children.
Every lookup and master-detail field automatically creates one child relationship on the parent object, and each one carries a name. SOQL uses that name in subqueries, Apex reads it through the describe API, and Lightning record pages render it as a related list. For standard objects the name is usually the plural child label, like Contacts on Account. For custom objects it ends in __r. Getting the name right matters because queries, related lists, and dynamic code all refer to the relationship by that exact name.
How child relationships wire parents to their children
Where the name comes from
When you create a lookup or master-detail field, Salesforce builds a child relationship on the object the field points to. The field definition has a Child Relationship Name property that you set at creation. For standard objects the name is typically the plural form of the child label, so the Account-to-Contact link is named Contacts, and Account-to-Case is named Cases. You reference it directly in a subquery without any suffix. Custom relationships behave differently. A custom lookup field named Project_Update__c produces a relationship whose name ends in __r, written as Project_Updates__r when you query it. The platform takes the relationship name you entered and appends __r at query time. If you leave the default, you often get a plural of the child object, but the platform sometimes adds a numeric suffix when names would clash. That is where the awkward Tasks1 or Contacts2 names come from, and why naming the relationship yourself at field creation saves trouble later.
Parent-to-child subqueries in SOQL
The most visible use of a child relationship is the SOQL subquery. You select from the parent and nest an inner query that uses the relationship name, not the child object name. A query like SELECT Id, Name, (SELECT Id, Subject FROM Cases) FROM Account returns each Account with a list of its related Case records. The inner SELECT reads Cases because that is the child relationship name, even though the object is Case. For custom objects the inner query uses the __r form. To pull child Project Updates under a Project, you write SELECT Id, (SELECT Id, Status__c FROM Project_Updates__r) FROM Project__c. A frequent mistake is using the object API name (Project_Update__c) in the FROM clause of the subquery, which throws an error. The relationship name and the object name are different things, and the subquery wants the relationship name. Schema Builder and the developer console both show you the exact name to use.
Reading children in Apex
After a subquery runs, Apex exposes the children as a list on the parent record. With the Cases example, account.Cases returns the List of Case records the subquery matched. You iterate that list the same way you would any other collection. The relationship name becomes a property on the parent sObject. Beyond querying, Apex can inspect relationships without knowing their names in advance. Call getDescribe on an sObject to get a DescribeSObjectResult, then call getChildRelationships, which returns a list of Schema.ChildRelationship objects. Each one answers three useful questions through getChildSObject (the child object type), getField (the field on the child that points back), and getRelationshipName (the relationship name itself). Dynamic tools, managed packages, and admin utilities use this to walk a data model they did not write. It is the reflection layer that makes generic record-cloning and cascade-aware logic possible.
Related lists are child relationships on screen
The Related List component on a Lightning record page is the visual form of a child relationship. When you add a related list to an Account page, you are choosing one of the Account's child relationships, and the records shown are the children that reference that Account. The related list label tracks the child relationship name unless you override the label on the page layout or in the Lightning App Builder. This connection explains a common admin question. If a related list shows an unexpected or ugly title, the cause is often the underlying relationship name set when the lookup field was created. Renaming the relationship affects the default label everywhere it appears. Because related lists, reports, and SOQL all lean on the same relationship name, a clear name set once pays off across the user interface and the code at the same time. Reports that join a parent to its children also rely on these relationships for cross-object groupings.
Self-referencing and polymorphic cases
Some objects point at themselves. Account has a ParentId lookup to another Account, and Case has a ParentId to another Case. These self-referencing fields still generate a child relationship, but the parent and child are the same object. The platform's default name for these is rarely readable, often something like ChildAccounts or a numbered variant, so renaming it to something meaningful is worth the small effort. Other relationships are polymorphic, meaning one field can point at several object types. Task.WhatId and Task.WhoId are the classic examples, since an activity can relate to an Account, an Opportunity, a Contact, and more. Each parent object that can be referenced gets its own child relationship, so Account has Tasks and Opportunity has Tasks as separate relationships. Querying polymorphic relationships needs care, because the parent type varies row to row and your code has to handle whichever object the record actually points to.
Query depth and governor limits
Relationship queries are not unlimited. In a child-to-parent direction, where you walk from child up to ancestors with dot notation, SOQL allows up to five levels, as in Contact.Account.Owner.Manager and so on. Parent-to-child subqueries were historically capped at a single level below the parent. Winter '22 (API version 53) raised that, so you can now nest parent-to-child subqueries up to five levels deep in supported API versions. Governor limits still apply. In a SOQL query that uses parent-to-child subqueries, each subquery counts as an additional query against the limit, and the rule of thumb is three times the top-level query count for these nested forms. A parent with a huge number of children can also return more rows than you expect, so filtering the inner query with a WHERE clause is good practice. Querying SELECT Id FROM Cases WHERE Status = 'Open' under Account is safer than pulling every Case for accounts that have thousands.
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Child Relationship.
Hands-on resources to go deeper on Child Relationship.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What does a Child Relationship let you do that a plain lookup field alone does not?
Q2. In a SOQL parent-to-child subquery, what relationship name goes inside the inner parentheses?
Q3. Why do admins often rename the auto-generated Child Relationship Name?
Discussion
Loading discussion…