Skip to content

Commit 0310656

Browse files
robrichardrobrichard
committed
Move examples to Appendix
1 parent abafb76 commit 0310656

File tree

3 files changed

+193
-192
lines changed

3 files changed

+193
-192
lines changed

‎spec/Appendix C -- Examples.md

+191
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# C. Appendix: Examples
2+
3+
## Incremental Delivery Examples
4+
5+
### Example 1 - A query containing both defer and stream
6+
7+
```graphql example
8+
query {
9+
person(id: "cGVvcGxlOjE=") {
10+
...HomeWorldFragment @defer(label: "homeWorldDefer")
11+
name
12+
films @stream(initialCount: 1, label: "filmsStream") {
13+
title
14+
}
15+
}
16+
}
17+
fragment HomeWorldFragment on Person {
18+
homeWorld {
19+
name
20+
}
21+
}
22+
```
23+
24+
The response stream might look like:
25+
26+
Payload 1, the initial response does not contain any deferred or streamed
27+
results in the `data` entry. The initial response contains a `hasNext` entry,
28+
indicating that subsequent payloads will be delivered. There are two Pending
29+
Responses indicating that results for both the `@defer` and `@stream` in the
30+
query will be delivered in the subsequent payloads.
31+
32+
```json example
33+
{
34+
"data": {
35+
"person": {
36+
"name": "Luke Skywalker",
37+
"films": [{ "title": "A New Hope" }]
38+
}
39+
},
40+
"pending": [
41+
{ "id": "0", "path": ["person"], "label": "homeWorldDefer" },
42+
{ "id": "1", "path": ["person", "films"], "label": "filmsStream" }
43+
],
44+
"hasNext": true
45+
}
46+
```
47+
48+
Payload 2, contains the deferred data and the first streamed list item. There is
49+
one Completed Result, indicating that the deferred data has been completely
50+
delivered.
51+
52+
```json example
53+
{
54+
"incremental": [
55+
{
56+
"id": "0",
57+
"data": { "homeWorld": { "name": "Tatooine" } }
58+
},
59+
{
60+
"id": "1",
61+
"items": [{ "title": "The Empire Strikes Back" }]
62+
}
63+
],
64+
"completed": [
65+
{"id": "0"}
66+
]
67+
"hasNext": true
68+
}
69+
```
70+
71+
Payload 3, contains the final stream payload. In this example, the underlying
72+
iterator does not close synchronously so {hasNext} is set to {true}. If this
73+
iterator did close synchronously, {hasNext} would be set to {false} and this
74+
would be the final response.
75+
76+
```json example
77+
{
78+
"incremental": [
79+
{
80+
"id": "1",
81+
"items": [{ "title": "Return of the Jedi" }]
82+
}
83+
],
84+
"hasNext": true
85+
}
86+
```
87+
88+
Payload 4, contains no incremental data. {hasNext} set to {false} indicates the
89+
end of the response stream. This response is sent when the underlying iterator
90+
of the `films` field closes.
91+
92+
```json example
93+
{
94+
"hasNext": false
95+
}
96+
```
97+
98+
### Example 2 - A query containing overlapping defers
99+
100+
```graphql example
101+
query {
102+
person(id: "cGVvcGxlOjE=") {
103+
...HomeWorldFragment @defer(label: "homeWorldDefer")
104+
...NameAndHomeWorldFragment @defer(label: "nameAndWorld")
105+
firstName
106+
}
107+
}
108+
fragment HomeWorldFragment on Person {
109+
homeWorld {
110+
name
111+
terrain
112+
}
113+
}
114+
115+
fragment NameAndHomeWorldFragment on Person {
116+
firstName
117+
lastName
118+
homeWorld {
119+
name
120+
}
121+
}
122+
```
123+
124+
The response stream might look like:
125+
126+
Payload 1, the initial response contains the results of the `firstName` field.
127+
Even though it is also present in the `HomeWorldFragment`, it must be returned
128+
in the initial payload because it is also defined outside of any fragments with
129+
the `@defer` directive. Additionally, There are two Pending Responses indicating
130+
that results for both `@defer`s in the query will be delivered in the subsequent
131+
payloads.
132+
133+
```json example
134+
{
135+
"data": {
136+
"person": {
137+
"firstName": "Luke"
138+
}
139+
},
140+
"pending": [
141+
{ "id": "0", "path": ["person"], "label": "homeWorldDefer" },
142+
{ "id": "1", "path": ["person"], "label": "nameAndWorld" }
143+
],
144+
"hasNext": true
145+
}
146+
```
147+
148+
Payload 2, contains the deferred data from `HomeWorldFragment`. There is one
149+
Completed Result, indicating that `HomeWorldFragment` has been completely
150+
delivered. Because the `homeWorld` field is present in two separate `@defer`s,
151+
it is separated into its own Incremental Result.
152+
153+
The second Incremental Result contains the data for the `terrain` field. This
154+
incremental result contains a `subPath` property to indicate to clients that the
155+
path of this result can be determined by concatenating the path from the Pending
156+
Result with id `"0"` and this `subPath` entry.
157+
158+
```json example
159+
{
160+
"incremental": [
161+
{
162+
"id": "0",
163+
"data": { "homeWorld": { "name": "Tatooine" } }
164+
},
165+
{
166+
"id": "0",
167+
"subPath": ["homeWorld"],
168+
"data": { "terrain": "desert" }
169+
}
170+
],
171+
"completed": [{ "id": "0" }],
172+
"hasNext": true
173+
}
174+
```
175+
176+
Payload 3, contains the remaining data from the `NameAndHomeWorldFragment`.
177+
`lastName` is the only remaining field that has not been delivered in a previous
178+
payload.
179+
180+
```json example
181+
{
182+
"incremental": [
183+
{
184+
"id": "1",
185+
"data": { "lastName": "Skywalker" }
186+
}
187+
],
188+
"completed": [{ "id": "1" }],
189+
"hasNext": false
190+
}
191+
```

‎spec/GraphQL.md

+2
Original file line numberDiff line numberDiff line change
@@ -139,3 +139,5 @@ Note: This is an example of a non-normative note.
139139
# [Appendix: Notation Conventions](Appendix%20A%20--%20Notation%20Conventions.md)
140140

141141
# [Appendix: Grammar Summary](Appendix%20B%20--%20Grammar%20Summary.md)
142+
143+
# [Appendix: Examples](Appendix%20C%20--%20Examples.md)

‎spec/Section 7 -- Response.md

-192
Original file line numberDiff line numberDiff line change
@@ -432,198 +432,6 @@ higher than the Incremental Data Result's path. The `errors` entry must contain
432432
these field errors. The value of this entry is described in the "Errors"
433433
section.
434434

435-
### Examples
436-
437-
#### A query containing both defer and stream:
438-
439-
```graphql example
440-
query {
441-
person(id: "cGVvcGxlOjE=") {
442-
...HomeWorldFragment @defer(label: "homeWorldDefer")
443-
name
444-
films @stream(initialCount: 1, label: "filmsStream") {
445-
title
446-
}
447-
}
448-
}
449-
fragment HomeWorldFragment on Person {
450-
homeWorld {
451-
name
452-
}
453-
}
454-
```
455-
456-
The response stream might look like:
457-
458-
Payload 1, the initial response does not contain any deferred or streamed
459-
results in the `data` entry. The initial response contains a `hasNext` entry,
460-
indicating that subsequent payloads will be delivered. There are two Pending
461-
Responses indicating that results for both the `@defer` and `@stream` in the
462-
query will be delivered in the subsequent payloads.
463-
464-
```json example
465-
{
466-
"data": {
467-
"person": {
468-
"name": "Luke Skywalker",
469-
"films": [{ "title": "A New Hope" }]
470-
}
471-
},
472-
"pending": [
473-
{ "id": "0", "path": ["person"], "label": "homeWorldDefer" },
474-
{ "id": "1", "path": ["person", "films"], "label": "filmsStream" }
475-
],
476-
"hasNext": true
477-
}
478-
```
479-
480-
Payload 2, contains the deferred data and the first streamed list item. There is
481-
one Completed Result, indicating that the deferred data has been completely
482-
delivered.
483-
484-
```json example
485-
{
486-
"incremental": [
487-
{
488-
"id": "0",
489-
"data": { "homeWorld": { "name": "Tatooine" } }
490-
},
491-
{
492-
"id": "1",
493-
"items": [{ "title": "The Empire Strikes Back" }]
494-
}
495-
],
496-
"completed": [
497-
{"id": "0"}
498-
]
499-
"hasNext": true
500-
}
501-
```
502-
503-
Payload 3, contains the final stream payload. In this example, the underlying
504-
iterator does not close synchronously so {hasNext} is set to {true}. If this
505-
iterator did close synchronously, {hasNext} would be set to {false} and this
506-
would be the final response.
507-
508-
```json example
509-
{
510-
"incremental": [
511-
{
512-
"id": "1",
513-
"items": [{ "title": "Return of the Jedi" }]
514-
}
515-
],
516-
"hasNext": true
517-
}
518-
```
519-
520-
Payload 4, contains no incremental data. {hasNext} set to {false} indicates the
521-
end of the response stream. This response is sent when the underlying iterator
522-
of the `films` field closes.
523-
524-
```json example
525-
{
526-
"hasNext": false
527-
}
528-
```
529-
530-
### Examples
531-
532-
#### A query containing overlapping defers:
533-
534-
```graphql example
535-
query {
536-
person(id: "cGVvcGxlOjE=") {
537-
...HomeWorldFragment @defer(label: "homeWorldDefer")
538-
...NameAndHomeWorldFragment @defer(label: "nameAndWorld")
539-
firstName
540-
}
541-
}
542-
fragment HomeWorldFragment on Person {
543-
homeWorld {
544-
name
545-
terrain
546-
}
547-
}
548-
549-
fragment NameAndHomeWorldFragment on Person {
550-
firstName
551-
lastName
552-
homeWorld {
553-
name
554-
}
555-
}
556-
```
557-
558-
The response stream might look like:
559-
560-
Payload 1, the initial response contains the results of the `firstName` field.
561-
Even though it is also present in the `HomeWorldFragment`, it must be returned
562-
in the initial payload because it is also defined outside of any fragments with
563-
the `@defer` directive. Additionally, There are two Pending Responses indicating
564-
that results for both `@defer`s in the query will be delivered in the subsequent
565-
payloads.
566-
567-
```json example
568-
{
569-
"data": {
570-
"person": {
571-
"firstName": "Luke"
572-
}
573-
},
574-
"pending": [
575-
{ "id": "0", "path": ["person"], "label": "homeWorldDefer" },
576-
{ "id": "1", "path": ["person"], "label": "nameAndWorld" }
577-
],
578-
"hasNext": true
579-
}
580-
```
581-
582-
Payload 2, contains the deferred data from `HomeWorldFragment`. There is one
583-
Completed Result, indicating that `HomeWorldFragment` has been completely
584-
delivered. Because the `homeWorld` field is present in two separate `@defer`s,
585-
it is separated into its own Incremental Result.
586-
587-
The second Incremental Result contains the data for the `terrain` field. This
588-
incremental result contains a `subPath` property to indicate to clients that the
589-
path of this result can be determined by concatenating the path from the Pending
590-
Result with id `"0"` and this `subPath` entry.
591-
592-
```json example
593-
{
594-
"incremental": [
595-
{
596-
"id": "0",
597-
"data": { "homeWorld": { "name": "Tatooine" } }
598-
},
599-
{
600-
"id": "0",
601-
"subPath": ["homeWorld"],
602-
"data": { "terrain": "desert" }
603-
}
604-
],
605-
"completed": [{ "id": "0" }],
606-
"hasNext": true
607-
}
608-
```
609-
610-
Payload 3, contains the remaining data from the `NameAndHomeWorldFragment`.
611-
`lastName` is the only remaining field that has not been delivered in a previous
612-
payload.
613-
614-
```json example
615-
{
616-
"incremental": [
617-
{
618-
"id": "1",
619-
"data": { "lastName": "Skywalker" }]
620-
}
621-
],
622-
"completed": [{"id": "1"}],
623-
"hasNext": false
624-
}
625-
```
626-
627435
## Serialization Format
628436

629437
GraphQL does not require a specific serialization format. However, clients

0 commit comments

Comments
 (0)