@@ -2211,9 +2211,9 @@ directive @defer(
2211
2211
2212
2212
The `@defer ` directive may be provided on a fragment spread or inline fragment
2213
2213
to indicate that execution of the related selection set should be deferred . When
2214
- a request includes the `@defer ` directive , the result may consist of multiple
2215
- responses : the initial response containing all non -deferred data , while
2216
- subsequent responses include deferred data .
2214
+ a request includes the `@defer ` directive , it may return an _incremental stream_
2215
+ consisting of an _initial response_ containing all non -deferred data , followed
2216
+ by one or more _subsequent payloads_ including the deferred data .
2217
2217
2218
2218
The `@include ` and `@skip ` directives take precedence over `@defer `.
2219
2219
@@ -2238,11 +2238,11 @@ fragment someFragment on User {
2238
2238
related note below). When `false `, fragment must not be deferred . Defaults to
2239
2239
`true ` when omitted .
2240
2240
- `label : String ` - An optional string literal (variables are disallowed) used
2241
- by GraphQL clients to identify data from responses and associate it with the
2242
- corresponding defer directive . If provided , the GraphQL service must include
2243
- this label in the corresponding pending object within the response . The
2244
- `label ` argument must be unique across all `@defer ` and ` @stream ` directives
2245
- in the document .
2241
+ by GraphQL clients to identify data in the _incremental stream_ and associate
2242
+ it with the corresponding defer directive . If provided , the GraphQL service
2243
+ must include this label in the corresponding pending object within the
2244
+ _incremental stream_ . The `label ` argument must be unique across all `@defer `
2245
+ and ` @stream ` directives in the document .
2246
2246
2247
2247
### @stream
2248
2248
@@ -2256,7 +2256,7 @@ directive @stream(
2256
2256
2257
2257
The `@stream ` directive may be provided for a field whose type incorporates a
2258
2258
`List ` type modifier . The directive enables returning a partial list initially ,
2259
- followed by additional items in subsequent responses . Should the field type
2259
+ followed by additional items in subsequent payloads . Should the field type
2260
2260
incorporate multiple `List ` type modifiers , only the outermost list is streamed .
2261
2261
2262
2262
Note : The mechanism through which items are streamed is implementation -defined
@@ -2277,37 +2277,37 @@ query myQuery($shouldStream: Boolean! = true) {
2277
2277
2278
2278
#### @stream Arguments
2279
2279
2280
- - `initialCount : Int ! = 0` - The number of list items to include initially . If
2281
- omitted , defaults to `0`. A field error will be raised if the value of this
2282
- argument is less than `0`. When the size of the list is greater than or equal
2283
- to the value of `initialCount `, the GraphQL service _must_ initially include
2284
- at least as many list items as the value of ` initialCount ` (see related note
2285
- below).
2280
+ - `initialCount : Int ! = 0` - The number of list items to include initially when
2281
+ completing the parent selection set . If omitted , defaults to `0`. A field
2282
+ error will be raised if the value of this argument is less than `0`. When the
2283
+ size of the list is greater than or equal to the value of `initialCount `, the
2284
+ GraphQL service _must_ initially include at least as many list items as the
2285
+ value of ` initialCount ` (see related note below).
2286
2286
- `if : Boolean ! = true ` - When `true `, field _should_ be streamed (see related
2287
2287
note below). When `false `, the field must behave as if the `@stream ` directive
2288
2288
is not present —it must not be streamed and all of the list items must be
2289
2289
included . Defaults to `true ` when omitted .
2290
2290
- `label : String ` - An optional string literal (variables are disallowed) used
2291
- by GraphQL clients to identify data from responses and associate it with the
2292
- corresponding stream directive . If provided , the GraphQL service must include
2293
- this label in the corresponding pending object within the response . The
2294
- `label ` argument must be unique across all `@defer ` and ` @stream ` directives
2295
- in the document .
2291
+ by GraphQL clients to identify data in the _incremental stream_ and associate
2292
+ it with the corresponding stream directive . If provided , the GraphQL service
2293
+ must include this label in the corresponding pending object within the
2294
+ _incremental stream_ . The `label ` argument must be unique across all `@defer `
2295
+ and ` @stream ` directives in the document .
2296
2296
2297
2297
Note : The
2298
2298
[Defer And Stream Directive Labels Are Unique ](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
2299
2299
validation rule ensures uniqueness of the values passed to `label` on both the
2300
2300
`@defer` and `@stream` directives. Variables are disallowed in the `label`
2301
2301
because their values may not be known during validation.
2302
2302
2303
- Note : The ability to defer and /or stream parts of a response can have a
2304
- potentially significant impact on application performance . Developers generally
2305
- need clear , predictable control over their application's performance. It is
2306
- highly recommended that GraphQL services honor the `@defer` and `@stream`
2307
- directives on each execution. However, the specification allows advanced use
2308
- cases where the service can determine that it is more performant to not defer
2309
- and/or stream. Therefore, GraphQL clients _must_ be able to process a response
2303
+ Note : The ability to defer and /or stream data can have a potentially significant
2304
+ impact on application performance . Developers generally need clear , predictable
2305
+ control over their application's performance. It is highly recommended that
2306
+ GraphQL services honor the `@defer` and `@stream` directives on each execution.
2307
+ However, the specification allows advanced use cases where the service can
2308
+ determine that it is more performant to not defer and/or stream. Therefore,
2309
+ GraphQL clients _must_ be able to process a _response_ or _incremental stream_
2310
2310
that ignores individual `@defer` and/or `@stream` directives. This also applies
2311
2311
to the `initialCount` argument on the `@stream` directive. Clients must be able
2312
- to process a streamed response that contains more initial list items than what
2313
- was specified in the `initialCount` argument.
2312
+ to process a streamed field result that contains more initial list items than
2313
+ what was specified in the `initialCount` argument.
0 commit comments