In SOQL, the direction of the relationship determines the query shape: use dot notation to read parent fields from a child record, and a nested subquery to retrieve child records from a parent. The names in those paths come from Salesforce relationship metadata, not necessarily the object or lookup field names. Check the target org’s schema and the API version and execution context before using deeper traversals.
Choose the query shape by relationship direction
SOQL relationship queries follow relationships defined between Salesforce objects; they are not arbitrary SQL joins. As Salesforce explains in its Relationship Queries reference, the queried objects must have a relationship that supports the traversal.
| What you need | Query from | Syntax | Result shape |
|---|---|---|---|
| Parent fields for matching children | Child object | Dot notation, such as Account.Name |
Child records with selected parent fields |
| Related children for each parent | Parent object | Nested subquery, such as (SELECT LastName FROM Contacts) |
Parent records with nested child results |
The outer query’s FROM identifies the driving object. Decide whether the records you want returned are parents or children first; that choice determines the direction and syntax.
Get a parent field from a child record
For child-to-parent traversal, put the parent relationship name and field in the outer query’s field list or use the path in a filter. For example, this returns Contacts whose related Account has the Industry value Media, including the Account name:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsSELECT Id, FirstName, Account.Name
FROM Contact
WHERE Account.Industry = 'Media'Here, Account is the relationship name from Contact to its parent Account. Salesforce documents relationship paths in Using Relationship Queries and illustrates them in SOQL SELECT Examples.
Get child records from a parent
For parent-to-child traversal, nest a query in parentheses in the outer SELECT. The nested query’s FROM takes the child relationship name. For Accounts and Contacts, that name is Contacts (plural), not Contact:
SELECT Name,
(SELECT LastName FROM Contacts)
FROM AccountTo filter the child records, put the condition inside the child subquery. A condition in the outer WHERE filters parent records instead. For instance, to select qualifying Accounts and only their Contacts created by a user with alias jdoe:
SELECT Name,
(SELECT LastName FROM Contacts WHERE CreatedBy.Alias = 'jdoe')
FROM Account
WHERE Industry = 'Media'The outer filter selects Accounts in Media; the nested filter limits the Contacts returned for each selected Account. See Salesforce’s relationship-query syntax guidance.
Recommended Free Tools
Find the correct relationship name in your org
The two directions use different metadata names:
- Child to parent: use the parent relationship name in the dot path, such as
Account.Name. - Parent to child: use the configured child relationship name in the subquery’s
FROM, such asContacts.
For a custom lookup field whose API name ends in __c, traversal to the parent uses its relationship name ending in __r. For example, a custom field might be traversed as Mother_of_Child__r.FirstName__c. In the reverse direction, the subquery uses that relationship’s configured child relationship name. Do not assume it is the custom object’s plural form.
Salesforce recommends inspecting object metadata with describeSObjects() as the most reliable way to identify relationships and their names; the Enterprise WSDL is another source. Verify the metadata in the target org, especially for custom objects, installed packages, and fields whose labels or API names suggest a relationship that may not be exposed to SOQL. See Identifying Parent and Child Relationships, Understanding Relationship Names, and Understanding Relationship Names, Custom Objects, and Custom Fields.
Understand the returned data shape
Child-to-parent traversal returns one row per matching child, with the requested parent values available along the relationship path. Parent-to-child traversal returns parent rows; each child subquery is a nested query result on its parent record. Salesforce describes this structure in Understanding Query Results.
Account row
├── Name: Acme
└── Contacts (nested query result)
├── Contact row: LastName = Smith
└── Contact row: LastName = LeeWhen consuming API results, treat the child collection as a nested result associated with its parent, rather than as additional top-level rows.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
Check traversal limits, API version, and execution context
The documented limits vary by direction and context. Salesforce’s Understanding Relationship Query Limitations specifies:
| Traversal or constraint | Documented limit or qualification |
|---|---|
| Child-to-parent relationships in a query | Up to 55; custom objects allow up to 40. A polymorphic field can count more than once toward the cap, while repeated use of the same relationship counts as one. |
| Parent-to-child relationships in a query | Up to 20. |
| Child-to-parent path depth | Up to five levels. |
| Parent-to-child depth through API v57.0 | Two levels or fewer. |
| Parent-to-child depth from API v58.0 | Up to five levels for REST, SOAP, and Apex query calls on standard and custom objects. |
| Five-level parent-to-child queries | Not supported for big objects, external objects, Bulk API, or Bulk API 2.0. |
These depth rules make the API version and how a query is executed part of the query design. A five-level parent-to-child query supported through REST, SOAP, or Apex is not thereby supported through Bulk API or Bulk API 2.0. Check the relevant object type and execution path rather than assuming one context’s allowance applies everywhere.
External objects have further constraints: Salesforce documents up to four joins across external and other objects, possible extra round trips and latency, and restrictions on ordering and subquery results. Adapter and object conditions matter, so consult the limitations reference for the specific external-object setup.
Troubleshoot a relationship query that fails
- Wrong direction or query form: use a dot path when querying parent fields from a child; use a parent query with a nested subquery when retrieving children.
- Wrong name: confirm whether the query needs the parent relationship name or the child relationship name. For custom relationships, check the
__rtraversal name rather than using the lookup field’s__cname. - No SOQL relationship: verify that the objects have an exposed relationship; a diagram or matching field labels alone do not establish one.
- Unsupported depth or context: check the API version, execution method, object type, and applicable relationship limits.
- Unexpected result structure: parent-to-child results are nested under each parent, unlike the child rows returned by a child-to-parent query.
For custom schema questions, validate names with describeSObjects() against the org where the query will run. For depth or object restrictions, check Salesforce’s current limitations reference rather than relying on a query example written for a different API version or execution path.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
