DOC Document manipulating eager loading queries

en/02_Developer_Guides/00_Model/02_Relations.md

@@ -891,10 +891,15 @@ Eager loading supports all relationship types.
 
 > [!WARNING]
 > Eager loading is only intended to be used in read-only scenarios such as when outputting data on the front-end of a website. When using default lazy-loading, relationship methods will return a subclass of [`DataList`](api:SilverStripe\ORM\DataList) such as [`HasManyList`](api:SilverStripe\ORM\HasManyList). However when using eager-loading, an [`EagerLoadedList`](api:SilverStripe\ORM\EagerLoadedList) will be returned instead. `EagerLoadedList` has common methods such as `filter()`, `sort()`, `limit()` and `reverse()` available to manipulate its data, as well as some methods you'd expect on the various relation list implementations such as [`getExtraData()`](api:SilverStripe\ORM\EagerLoadedList::getExtraData()).
->
-> Note that filtering or sorting an `EagerLoadedList` will be done in PHP rather than as part of the database query, since we have already loaded all its relevant data into memory.
->
-> Note also that `EagerLoadedList` can't filter or sort by fields on relations using dot notation (e.g. `sort('MySubRelation.Title')` won't work).
+
+### Manipulating eager loaded data
+
+There are some limitations to manipulating data in an `EagerLoadedList` (i.e. after the query has been executed).
+
+The main limitation is that filtering or sorting an `EagerLoadedList` will be done in PHP rather than as part of the database query, since we have already loaded all its relevant data into memory.
+
+> [!WARNING]
+> `EagerLoadedList` can't filter or sort by fields on relations using dot notation (e.g. `sort('MySubRelation.Title')` won't work).
 
 ## Cascading deletions
 

en/04_Changelogs/5.2.0.md

@@ -41,6 +41,27 @@ We have provided a severity rating of the vulnerabilities below based on the CVS
 
 This release comes jampacked with new ORM features, granting you access to some new abstractions for more powerful and efficient queries.
 
+#### Prefiltering eager loaded relation data {#eager-loading}
+
+Something here about what we added, and why it's beneficial.
+
+The old syntax is still supported, because it can be used in templates for simple scenarios.
+
+Something here about how the new syntax works.
+
+```php
+use SilverStripe\ORM\DataList;
+
+$teams = Team::get()->eagerLoad([
+    'Players' => fn (DataList $list) => $list->filter(['Age:GreaterThan' => 18]),
+]);
+```
+
+> [!WARNING]
+> It is very important to remember to return the list in your callback function.
+
+There are a few edge cases to be aware of with this new feature. To learn more, see [eager loading](/developer_guides/model/relations/#eager-loading).
+
 #### Multi-relational `has_one` relations
 
 Traditionally, if you wanted to have multiple `has_many` relations for the same class, you would have to include a separate `has_one` relation for *each* `has_many` relation.