Declare once that a post has an author (addRelationship('posts', 'author', 'authors')), and MQDB will embed the author record into your post whenever you ask for it. Your app gets a single nested object back instead of having to issue a second lookup per post.
addRelationship(source, field, target) tells MQDB that source.<field>_id points at target.id. So addRelationship('posts', 'author', 'authors') links posts.author_id → authors.id.db.readWithIncludes(entity, id, [fields]) returns the record with each listed relationship embedded as a nested object.db.list(entity, { includes: [fields] }) does the same for a whole list.
flowchart LR
P["posts/1
{ title, author_id: 'a1' }"] --> R{includes: author?}
R -- no --> OUT1[post only]
R -- yes --> L["lookup authors/a1"]
L --> M["merge → post.author = {...}"]
M --> OUT2["{ ...post, author: {...} }"]
style OUT2 fill:#ede7f6,stroke:#5e35b1
style R fill:#e3f2fd,stroke:#1565c0
Seed test data to create two authors and three posts linked via author_id.Define posts→authors relationship. The rule appears below.Show side-by-side. The Without includes panel shows posts with a bare author_id; the With includes panel shows the same posts with the full author record nested under .author.Creates authors (Alice, Bob) and three posts with author_id set.
Joins posts.author_id → authors.id
None yet.
The same list, queried with and without includes: ['author'].
Bare rows — only author_id.
Click "Show side-by-side".
Same rows, author object nested under .author.
Click "Show side-by-side".
Run all tests runs these 5 steps and reports pass/fail:
posts→authors relationshipreadWithIncludes('posts', id, ['author']) returns a nested author objectlist('posts', { includes: ['author'] }) nests author on every row