From 78fbd49a1d2d5f1f20e72ba90982eb7a1b8248df Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Sat, 22 Aug 2026 06:38:20 -0600 Subject: [PATCH] Document preconfigured eager loading Closes #47 --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index 3f5457d0..c2289294 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,30 @@ component { Now that you've seen an example, [dig in to what you can do](https://quick.ortusbooks.com/) with Quick! +### Preconfigured eager loading + +Entities can declare relationships that should be eager loaded on every query by assigning an array of relationship paths to `variables._with`: + +```javascript +component extends="quick.models.BaseEntity" accessors="true" { + + variables._with = [ "author", "comments.author" ]; + + function author() { + return belongsTo( "User" ); + } + + function comments() { + return hasMany( "Comment" ); + } + +} +``` + +The paths use the same dot notation as the query builder's `with()` method, so nested relationships can be preconfigured. Quick adds these relationships whenever it creates a new query for the entity, including calls such as `all()`, `get()`, `first()`, and `find()`. + +Preconfigured eager loading is most useful for relationships that nearly every consumer needs. Use it selectively: every configured relationship adds work to each entity query and can retrieve substantially more data than the caller needs. For relationships used only by specific operations, prefer an explicit query-level call such as `getInstance( "Post" ).with( "comments" ).get()`. + ### Tests and Contributing To run the tests, first clone this repo and run a `box install`.