Eager Loading

Overview

ent supports querying entities with their associations (through their edges). The associated entities are populated to the Edges field in the returned object.

Let’s give an example of what the API looks like for the following schema:

er-group-users

Query all users with their pets:

  1. users, err := client.User.
  2.     Query().
  3.     WithPets().
  4.     All(ctx)
  5. if err != nil {
  6.     return err
  7. }
  8. // The returned users look as follows:
  9. //
  10. //  [
  11. //      User {
  12. //          ID:   1,
  13. //          Name: "a8m",
  14. //          Edges: {
  15. //              Pets: [Pet(...), ...]
  16. //              ...
  17. //          }
  18. //      },
  19. //      ...
  20. //  ]
  21. //
  22. for _, u := range users {
  23.     for _, p := range u.Edges.Pets {
  24.         fmt.Printf("User(%v) -> Pet(%v)\n", u.ID, p.ID)
  25.         // Output:
  26.         // User(...) -> Pet(...)
  27.     }
  28. }

Eager loading allows to query more than one association (including nested), and also filter, sort or limit their result. For example:

  1. admins, err := client.User.
  2.     Query().
  3.     Where(user.Admin(true)).
  4.     // Populate the `pets` that associated with the `admins`.
  5.     WithPets().
  6.     // Populate the first 5 `groups` that associated with the `admins`.
  7.     WithGroups(func(q *ent.GroupQuery) {
  8.         q.Limit(5)              // Limit to 5.
  9.         q.WithUsers()           // Populate the `users` of each `groups`.
  10.     }).
  11.     All(ctx)
  12. if err != nil {
  13.     return err
  14. }
  16. // The returned users look as follows:
  17. //
  18. //  [
  19. //      User {
  20. //          ID:   1,
  21. //          Name: "admin1",
  22. //          Edges: {
  23. //              Pets:   [Pet(...), ...]
  24. //              Groups: [
  25. //                  Group {
  26. //                      ID:   7,
  27. //                      Name: "GitHub",
  28. //                      Edges: {
  29. //                          Users: [User(...), ...]
  30. //                          ...
  31. //                      }
  32. //                  }
  33. //              ]
  34. //          }
  35. //      },
  36. //      ...
  37. //  ]
  38. //
  39. for _, admin := range admins {
  40.     for _, p := range admin.Edges.Pets {
  41.         fmt.Printf("Admin(%v) -> Pet(%v)\n", u.ID, p.ID)
  42.         // Output:
  43.         // Admin(...) -> Pet(...)
  44.     }
  45.     for _, g := range admin.Edges.Groups {
  46.         for _, u := range g.Edges.Users {
  47.             fmt.Printf("Admin(%v) -> Group(%v) -> User(%v)\n", u.ID, g.ID, u.ID)
  48.             // Output:
  49.             // Admin(...) -> Group(...) -> User(...)
  50.         }
  51.     }
  52. }

API

Each query-builder has a list of methods in the form of With<E>(...func(<N>Query)) for each of its edges. <E> stands for the edge name (like, WithGroups) and <N> for the edge type (like, GroupQuery).

Note that only SQL dialects support this feature.

Named Edges

In some cases there is a need for preloading edges with custom names. For example, a GraphQL query that has two aliases referencing the same edge with different arguments. For this situation, Ent provides another API named WithNamed<E> that can be enabled using the namedges feature-flag and seamlessly integrated with EntGQL Fields Collection.

  • Ent
  • GraphQL

See the GraphQL tab to learn more about the motivation behind this API.

  1. posts, err := client.Post.Query().
  2.     WithNamedComments("published", func(q *ent.CommentQuery) {
  3.         q.Where(comment.StatusEQ(comment.StatusPublished))
  4.     })
  5.     WithNamedComments("draft", func(q *ent.CommentQuery) {
  6.         q.Where(comment.StatusEQ(comment.StatusDraft))
  7.     }).
  8.     Paginate(...)
  10. // Get the preloaded edges by their name:
  11. for _, p := range posts {
  12.     published, err := p.Edges.NamedComments("published")
  13.     if err != nil {
  14.         return err
  15.     }
  16.     draft, err := p.Edges.NamedComments("draft")
  17.     if err != nil {
  18.         return err
  19.     }
  20. }

An example of a GraphQL query that has two aliases referencing the same edge with different arguments.

  1. query {
  2.   posts {
  3.     id
  4.     title
  5.     published: comments(where: { status: PUBLISHED }) {
  6.       edges {
  7.         node {
  8.           text
  9.         }
  10.       }
  11.     }
  12.     draft: comments(where: { status: DRAFT }) {
  13.       edges {
  14.         node {
  15.           text
  16.         }
  17.       }
  18.     }
  19.   }
  20. }

Implementation

Since an Ent query can eager-load more than one edge, it is not possible to load all associations in a single JOIN operation. Therefore, Ent executes additional query to load each association. This expected to be optimized in future versions.