Skip to content

Commit 554bf1b

Browse files
robrichardrobrichard
committed
Update to address feedback in exampled appendix
1 parent ff9c30c commit 554bf1b

1 file changed

Lines changed: 48 additions & 32 deletions

File tree

‎spec/Appendix E -- Examples.md‎

Lines changed: 48 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,21 @@ fragment HomeWorldFragment on Person {
2121
}
2222
```
2323

24-
The _incremental stream_ might look like:
24+
The response to this request will be an _incremental stream_ consisting of an
25+
_initial execution result_ followed by one or more _execution update result_.
2526

26-
The _initial execution result_ does not contain any deferred or streamed results
27-
in the {"data"} entry. The initial execution result contains a {"hasNext"}
28-
entry, indicating that _execution update result_ will be delivered. There are
29-
two _pending result_ indicating that results for both the `@defer` and `@stream`
30-
in the query will be delivered in the execution update results.
27+
The _initial execution result_ has:
28+
29+
- a {"data"} entry containing the results of the GraphQL operation except for
30+
the `@defer` and `@stream` selections;
31+
- a {"pending"} entry containing two _pending result_, one for the `@defer`
32+
selection and for the the `@stream` selection, indicating that these results
33+
will be delivered in a later _execution update result_;
34+
- a {"hasNext"} entry with the value {true}, indicating that the response is not
35+
yet complete.
36+
37+
If an error were to occur, it would also have an {"error"} entry; but not in
38+
this example.
3139

3240
```json example
3341
{
@@ -45,9 +53,11 @@ in the query will be delivered in the execution update results.
4553
}
4654
```
4755

48-
_Execution update result_ 1 contains the deferred data and the first streamed
49-
list item. There is one _completed result_, indicating that the deferred data
50-
has been completely delivered.
56+
Depending on the behavior of the backend and the time at which the deferred and
57+
streamed resources resolve, the stream may produce results in different orders.
58+
In this example, our first _execution update result_ contains the deferred data
59+
and the first streamed list item. There is one _completed result_, indicating
60+
that the deferred data has been completely delivered.
5161

5262
```json example
5363
{
@@ -68,10 +78,10 @@ has been completely delivered.
6878
}
6979
```
7080

71-
_Execution update result_ 2 contains the final stream results. In this example,
72-
the underlying iterator does not close synchronously so {"hasNext"} is set to
73-
{true}. If this iterator did close synchronously, {"hasNext"} would be set to
74-
{false} and this would be the final execution update result.
81+
The second _execution update result_ contains the final stream results. In this
82+
example, the underlying iterator does not close synchronously so {"hasNext"} is
83+
set to {true}. If this iterator did close synchronously, {"hasNext"} would be
84+
set to {false} and this would be the final execution update result.
7585

7686
```json example
7787
{
@@ -85,9 +95,9 @@ the underlying iterator does not close synchronously so {"hasNext"} is set to
8595
}
8696
```
8797

88-
_Execution update result_ 3 contains no incremental data. {"hasNext"} set to
89-
{false} indicates the end of the _incremental stream_. This response is sent
90-
when the underlying iterator of the `films` field closes.
98+
The third _execution update result_ contains no incremental data. {"hasNext"}
99+
set to {false} indicates the end of the _incremental stream_. This execution
100+
update result is sent when the underlying iterator of the `films` field closes.
91101

92102
```json example
93103
{
@@ -121,14 +131,15 @@ fragment NameAndHomeWorldFragment on Person {
121131
}
122132
```
123133

124-
The _incremental stream_ might look like:
134+
In this example the response is an _incremental stream_ of the following
135+
results.
125136

126137
The _initial execution result_ contains the results of the `firstName` field.
127138
Even though it is also present in the `HomeWorldFragment`, it must be returned
128-
in the initial response because it is also defined outside of any fragments with
129-
the `@defer` directive. Additionally, there are two _pending result_ indicating
130-
that results for both `@defer`s in the query will be delivered in the execution
131-
update results.
139+
in the initial execution result because it is also defined outside of any
140+
fragments with the `@defer` directive. Additionally, there are two _pending
141+
result_ indicating that results for both `@defer`s in the query will be
142+
delivered in later _execution update result_.
132143

133144
```json example
134145
{
@@ -145,15 +156,17 @@ update results.
145156
}
146157
```
147158

148-
_Execution update result_ 1 contains the deferred data from `HomeWorldFragment`.
149-
There is one Completed Result, indicating that `HomeWorldFragment` has been
150-
completely delivered. Because the `homeWorld` field is present in two separate
151-
`@defer`s, it is separated into its own _incremental result_.
159+
In this example, the first _execution update result_ contains the deferred data
160+
from `HomeWorldFragment`. There is one _completed result_, indicating that
161+
`HomeWorldFragment` has been completely delivered. Because the `homeWorld` field
162+
is present in two separate `@defer`s, it is separated into its own _incremental
163+
result_.
152164

153-
The second _incremental result_ contains the data for the `terrain` field. This
154-
_incremental result_ contains a {"subPath"} entry to indicate to clients that
155-
the path of this result can be determined by concatenating the path from the
156-
_pending result_ with id `"0"` and this {"subPath"} entry.
165+
The second _incremental result_ in this _execution update result_ contains the
166+
data for the `terrain` field. This _incremental result_ contains a {"subPath"}
167+
entry to indicate to clients that the _response position_ of this result can be
168+
determined by concatenating the path from the _pending result_ with id `"0"` and
169+
the value of this {"subPath"} entry.
157170

158171
```json example
159172
{
@@ -173,9 +186,12 @@ _pending result_ with id `"0"` and this {"subPath"} entry.
173186
}
174187
```
175188

176-
_Execution update result_ 2 contains the remaining data from the
177-
`NameAndHomeWorldFragment`. `lastName` is the only remaining field that has not
178-
been delivered in a previous response.
189+
The second _execution update result_ contains the remaining data from the
190+
`NameAndHomeWorldFragment`. `lastName` is the only remaining field from this
191+
selection that has not been delivered in a previous result. With this field now
192+
delivered, clients are informed that the `NameAndHomeWorldFragment` has been
193+
completed by the presence of the associated _completed result_. Additionally,
194+
{"hasNext"} is set to {false} indicating the end of the _incremental stream_.
179195

180196
```json example
181197
{

0 commit comments

Comments
 (0)