website-source/docs/query/fetchgroup.html at master · ebean-orm/website-source · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
<html>
<head>
  <title>FetchGroup | Query | Ebean</title>
  <meta name="layout" content="_layout2/base-docs.html"/>
  <meta name="bread1" content="Query" href="/docs/query/"/>
  <meta name="bread2" content="fetchGroup" href="/docs/query/fetchgroup"/>
  <#assign n0_docs="true">
  <#assign n1_query="true">
  <#assign fetchgroup= "true">
</head>
<body>
<h2>FetchGroup</h2>
<p>
  As an alternative to <em>select</em> and <em>fetch</em> we can use <em>FetchGroup</em> to specify what part of
  the object graph to fetch.
</p>
<p>
  We can use <em>FetchGroup</em> with both query beans and standard queries.
</p>
<p>
  FetchGroups provide a clean way to separate the definition of "what part of the object graph to load" (query tuning)
  from the definition of the query predicates (query business logic).
</p>
<p>
  A FetchGroup is immutable, most often declared as a <code>static final</code> and can be combined to make other
  FetchGroups.
</p>

<h4>e.g. Just top level select properties</h4>
<pre content="java">
// immutable and threadsafe

static final QCustomer CUST = QCustomer.alias();

static final FetchGroup<|Customer> fetch = QCustomer.forFetchGroup()
    .select(CUST.name, CUST.version, CUST.whenCreated)
    .buildFetchGroup();

...

List<|Customer> customers =
  new QCustomer()
    .select(fetch)
    .name.istartsWith("Rob")
    .findList();

</pre>
<p>
  The above FetchGroup can be created without using query beans like the below:
</p>
<pre content="java">
static final FetchGroup<|Customer> fetch =
    FetchGroup.of(Customer.class, "name, version, whenCreated"); // root level properties
</pre>

<p>&nbsp;</p>

<h4>e.g. select and fetch properties</h4>
<pre content="java">
// immutable and threadsafe

static final QCustomer CUST = QCustomer.alias();
static final QContact  CONT = QContact.alias();

static final FetchGroup<|Customer> fetch = QCustomer.forFetchGroup()
    .select(CUST.name, CUST.version, CUST,whenCreated)
    .contacts.fetch(CONT.email)          // fetch the contacts with just their email
    .billingAddress.fetch()              // fetch all properties of billingAddress
    .buildFetchGroup();

...

List<|Customer> customers =
  new QCustomer()
    .select(fetch)
    .name.istartsWith("Rob")
    .findList();
</pre>
<p>
  The above FetchGroup can be created without query beans by:
</p>
<pre content="java">
// immutable and threadsafe
static final FetchGroup<|Customer> fetch =
   FetchGroup.of(Customer.class)
    .select("name, status")       // root level properties
    .fetch("contacts", "email")   // associated bean properties
    .build();
</pre>

<h3>Example</h3>
<p>
  This is a bigger example fetching orders with related lines, shipments, customer,
  customer.billingAddress and customer.contacts.
</p>
<p>
  Note we control which properties (or all) are fetched on each path.
</p>
<p>
  In this example we have several ToMany paths and we are using <em>fetchQuery</em> to
  explicitly control how the ORM query is broken into multiple SQL queries to build the graph.
</p>

<pre content="java">
// immutable and threadsafe

static final QOrder ORD = QOrder.alias();
static final QCustomer CUST = QCustomer.alias();
static final QContact CONT = QContact.alias();

static final FetchGroup<|Order> fetch = QOrder.forFetchGroup()
    .customer.fetch(CUST.name, CUST.version, CUST,whenCreated)
    .customer.shippingAddress.fetch()
    .customer.contacts.fetch(CONT.email)                        // a ToMany path
    .lines.fetchQuery()                                         // a ToMany path
    .shipments.fetchQuery()                                     // a ToMany path
    .buildFetchGroup();

...

List<|Order> orders =
  new QOrder()
    .select(fetch)
    .status.eq(Order.Status.NEW)
    .findList();
</pre>

<@next_edit "FilterMany" "/docs/query/filterMany" "/docs/query/fetchgroup.html"/>
</body>
</html>