Skip to content

docs: loading all relationships #100

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 18, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 30 additions & 2 deletions docs/guide/relationships/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ const users = store.$repo(User).with('posts', (query) => {

### Lazy Relationship Loading

Sometimes you may need to load a relationship after the model has already been retrieved. For example, this may be useful if you need to dynamically decide whether to load related models. You may use `load` method on a repository to load relationships on the fly in such a case.
Sometimes you may need to load a relationship after the model has already been retrieved. For example, this may be useful if you need to decide whether to load related models dynamically. You may use the `load` method on a repository to load relationships on the fly in such a case.

```js
const userRepo = store.$repo(User)
Expand All @@ -142,7 +142,7 @@ userRepo.with('posts', (query) => {
}).load(users)
```

Note that the `load` method will mutate the given models. It would be safer to use the method within a single `computed` method.
Note that the `load` method will mutate the given models, therefore, it is advised to use the method within a single `computed` property.

```js
import { mapRepos } from '@vuex-orm/core'
Expand Down Expand Up @@ -173,6 +173,34 @@ export default {
}
```

### Loading All Relationships

To load all relationships, you may use the `withAll` and `withAllRecursive` methods.

The `withAll` method will load all model level relationships. Note that any constraints will be applied to all top-level relationships.

```js
// Fetch models with all top-level relationships.
store.$repo(User).withAll().get()

// As above, with a constraint.
store.$repo(User).withAll((query) => {
// This constraint will apply to all of the relationship User has. For this
// example, all relationship will be sorted by `createdAt` field.
query.orderBy('createdAt')
}).get()
```

The `withAllRecursive` method will load all model level relationships and sub relationships recursively. By default, the maximum recursion depth is 3 when an argument is omitted.

```js
// Fetch models with relationships recursively.
store.$repo(User).withAllRecursive().get()

// As above, limiting to 2 levels deep.
store.$repo(User).withAllRecursive(2).get()
```

## Inserting Relationships

You may use `save` method to save a record with its nested relationships to the store. When saving new records into the store via `save` method, Vuex ORM automatically normalizes and stores data that contains any nested relationships in it's data structure. For example, let's say you have the `User` model that has a relationship to the `Post` model:
Expand Down