From e9358c88af35492c4af06386198ddcee5c8c1182 Mon Sep 17 00:00:00 2001 From: Steve Boyd Date: Wed, 21 Jun 2023 14:12:55 +1200 Subject: [PATCH] DOC Update eagerLoad() docblock --- src/ORM/DataList.php | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/ORM/DataList.php b/src/ORM/DataList.php index f33685dbd..a2ec43de2 100644 --- a/src/ORM/DataList.php +++ b/src/ORM/DataList.php @@ -1209,7 +1209,19 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li } /** - * $myDataList->eagerLoad('Some.Nested.Relation', 'Another.Relation') + * Eager load relations for DataObjects in this DataList including nested relations + * + * Eager loading alleviates the N + 1 problem by querying the nested relationship tables before they are + * needed using a single large `WHERE ID in ($ids)` SQL query instead of many `WHERE RelationID = $id` queries. + * + * You can speicify nested relations by using dot notation, and you can also pass in multiple relations. + * When speicifying nested relations there is a maximum of 3 levels of relations allowed i.e. 2 dots + * + * Example: + * $myDataList->eagerLoad('MyRelation.NestedRelation.EvenMoreNestedRelation', 'DifferentRelation') + * + * IMPORTANT: Calling eagerLoad() will cause any relations on DataObjects to be returned as an ArrayList + * instead of a subclass of DataList such as HasManyList i.e. MyDataObject->MyHasManyRelation() returns an ArrayList */ public function eagerLoad(...$relations): static {